Typesafe-i18n: Internationalization with Full Type Support in TypeScript

\n\n

In modern web development, internationalization (i18n) is not just about translating text, but a whole system for managing localization. Typesafe-i18n is a library for TypeScript that takes internationalization to the next level, providing complete type safety at all stages: from writing translations to using them in code.

\n\n

Why is this library needed? Traditional i18n solutions (e.g., i18next) often work with dynamic strings, which leads to errors: typos in keys, incorrect arguments, or missing translations. Typesafe-i18n solves this problem radically: if you write LL.WELCOME({name: "Alex"}), TypeScript will check whether the WELCOME key exists, whether it accepts the name parameter, and what type this parameter is. Localization errors become compilation errors, not runtime bugs.

\n\n

The library is ideal for projects where strict typing is important: React/Vue/Angular applications, Node.js servers, component libraries. It supports plurals, interpolation, nested keys, asynchronous loading, and type generation based on your translation files. In this article, we will cover all aspects of working with Typesafe-i18n: from installation to advanced techniques.

\n\n

Installation

\n\n

Installation is done via npm (or yarn/pnpm):

\n\n

npm install typesafe-i18n\n

\n\n

An additional package is required for generating types and translation files:

\n\n

npm install --save-dev typesafe-i18n-cli\n

\n\n

After installation, initialize the project:

\n\n

npx typesafe-i18n --init\n

\n\n

This command will create the basic folder structure and configuration files.

\n\n

Quick Start: Minimal Working Example

\n\n

Let's create a simple application that greets the user in different languages.

\n\n

Step 1: Create a translation file

\n\n

Create the file src/i18n/en/index.ts:

\n\n

import type { Translation } from '../i18n-types'\n\nconst en: Translation = {\n   HI: 'Hello {name}!',\n   GOODBYE: 'Goodbye, {name}!'\n}\n\nexport default en\n

\n\n

Step 2: Create a translation file for Russian

\n\n

Create the file src/i18n/ru/index.ts:

\n\n

import type { Translation } from '../i18n-types'\n\nconst ru: Translation = {\n   HI: 'Привет, {name}!',\n   GOODBYE: 'До свидания, {name}!'\n}\n\nexport default ru\n

\n\n

Step 3: Run type generation

\n\n

npx typesafe-i18n\n

\n\n

Step 4: Use in code

\n\n

import { i18n } from './i18n/i18n-util'\nimport { loadLocale } from './i18n/i18n-util.sync'\nimport { L } from './i18n/i18n-util'\n\n// Load locales\nloadLocale('en')\nloadLocale('ru')\n\n// Create an instance for English\nconst LL_en = i18n('en')\nconsole.log(LL_en.HI({ name: 'Alex' })) // Output: Hello Alex!\n\n// Switch to Russian\nconst LL_ru = i18n('ru')\nconsole.log(LL_ru.HI({ name: 'Алексей' })) // Output: Привет, Алексей!\n

\n\n

Note: if you try to call LL_en.HI() without the name argument, TypeScript will throw a compilation error. If you make a typo in the key (LL_en.Hello) — also an error.

\n\n