Type-Safe Internationalization for TypeScript

Common errors

• TS2339: Property 'nonExistentKey' does not exist on type '{ hello: string; greeting: (name: string) => string; }'.

  cause Attempting to access a translation key that is not defined in the loaded locale object or has a typo.
  fix Ensure the translation key exists in the active locale object and matches the exact property name. TypeScript's inference will highlight these issues at compile time.

• TS2345: Argument of type 'number' is not assignable to parameter of type 'string'.

  cause Providing an argument of the wrong type to a translation function, as defined in your locale object (e.g., calling `greeting(123)` when `greeting` expects a `string`).
  fix Pass arguments to your translation functions that precisely match the type signatures defined in your locale objects. TypeScript provides strong type checking for this.

• TypeError: Cannot read properties of undefined (reading 'translation')

  cause The `i18n` object passed to `I18nResolver` is malformed, the selected locale key (e.g., 'de') does not exist within it, or `default` locale is missing.
  fix Verify that the `i18n` object is correctly structured with defined locale objects (e.g., `en`, `de`) and that the selected locale key matches one of the defined keys. Also, ensure a `default` locale is provided.

Warnings

• gotcha i18n-ts does not provide built-in support for complex i18n features like pluralization, gender, or sophisticated ICU MessageFormat. Users must implement these functionalities manually within their message functions.
  Fix: For complex pluralization or formatting, manually add logic within your message functions, e.g., `(count: number) => count === 1 ? 'item' : 'items'`.
• gotcha All translation messages defined as plain TypeScript objects are typically bundled with your application by default. This can lead to increased bundle sizes for applications supporting a large number of locales, as there is no built-in dynamic locale loading mechanism.
  Fix: Consider code-splitting translation files if bundle size is a concern, and implement manual loading logic to pass the correct locale object to I18nResolver at runtime.
• breaking Major version updates (e.g., v2.0.0) could introduce breaking changes to the expected structure of locale objects or the way message functions receive arguments, necessitating updates to your existing translation files.
  Fix: Always review the release notes carefully when upgrading to a new major version. Test your translation files thoroughly after any major version upgrade.

Install

• npm install i18n-ts npm
• yarn add i18n-ts yarn
• pnpm add i18n-ts pnpm

Imports

• I18nResolver
  wrong:

  const I18nResolver = require('i18n-ts');

  correct:

  import { I18nResolver } from 'i18n-ts';

  The primary class for resolving translations; typically used with named import.

Quickstart

Demonstrates defining type-safe translation messages as plain TypeScript objects and using I18nResolver to access them.

import { I18nResolver } from 'i18n-ts';

const en = {
    hello: "Hi!",
    greeting: (name: string) => `Hi ${name}`
};

const de = {
    hello: "Hallo!",
    greeting: (name: string) => `Hallo ${name}`
};

const i18n = {
    en: en,
    de: de,
    default: en
};

// Initialize the resolver with your locales and desired language
const messages = new I18nResolver(i18n, "de").translation;

// TypeScript will infer the precise type of 'messages', providing compile-time safety
console.log(messages.hello); // Output: Hallo!
console.log(messages.greeting("Alice")); // Output: Hallo Alice

// Example of changing the language
const messagesEn = new I18nResolver(i18n, "en").translation;
console.log(messagesEn.hello); // Output: Hi!