i18next Internationalization Framework

Common errors

• `i18next.initImmediate is not a function` or `TypeError: Cannot read properties of undefined (reading 'initImmediate')`

  cause Attempting to use the `initImmediate` option which was removed in i18next v26.0.0.
  fix Update your i18next configuration to use `initAsync: true` instead of `initImmediate: true`.

• Translation does not update after `cloneInstance().changeLanguage()` when the language is not yet fully loaded.

  cause A race condition where `init()`'s deferred `load()` could overwrite `isLanguageChangingTo`, causing `setLngProps` to be skipped.
  fix Upgrade i18next to version 26.0.5 or newer, which contains a fix for this specific race condition. Ensure you are awaiting the `changeLanguage` call if immediate updates are required.

• Type error: 'string' is not assignable to type 'number' for inline formatting options like `{{price, currency(EUR)}}`.

  cause TypeScript was incorrectly inferring the type for inline formatted variables as `string` instead of their base type (e.g., `number` for `currency`).
  fix Upgrade i18next to version 26.0.4 or newer. This version correctly resolves inline formatting options to their base format types.

• Formatter crashes when `alwaysFormat` is `true` and no format specifier is present, or returns `NaN` for `undefined`/`null` values.

  cause Bugs in the Formatter logic in earlier v26 releases when handling missing format specifiers or `undefined`/`null` input values.
  fix Upgrade i18next to version 26.0.1 or newer. These issues were resolved, with the Formatter now returning `undefined`/`null` as-is and handling missing format specifiers gracefully.

Warnings

• breaking The deprecated `initImmediate` option has been removed. It was previously mapped to `initAsync` (introduced in v24) for backward compatibility. Direct usage of `initAsync` is now required.
  Fix: Replace `initImmediate: true` with `initAsync: true` in your i18next configuration. Ensure your initialization logic correctly handles asynchronous operations.
• breaking The legacy monolithic `interpolation.format` function has been removed. i18next now exclusively relies on the built-in Formatter or a custom Formatter module registered via `.use()` for value formatting.
  Fix: Migrate any custom formatting logic from the old `interpolation.format` function to either the built-in Formatter (if applicable) or by creating and registering a custom Formatter module using `i18next.use(myCustomFormatter)`.
• breaking A security vulnerability (GHSA-qjwx-ccf3-6w6j) was identified where combining `escapeValue: false` with interpolated variables inside `$t(key, { ... "{{var}}" ... })` nesting-options can lead to arbitrary code injection. An attacker-controlled string containing `"` could break out of the JSON literal.
  Fix: Upgrade to v26.0.6 or newer. Review all instances where `escapeValue: false` is used, especially in conjunction with variable interpolation or nested options. Where possible, avoid `escapeValue: false` or carefully sanitize all interpolated values if it's strictly necessary.
• gotcha Using `escapeValue: false` can introduce XSS vulnerabilities if interpolated values are not properly sanitized. This is particularly relevant in frameworks that do not automatically escape content (e.g., vanilla JS rendering, but less so for React which escapes by default).
  Fix: Only set `escapeValue: false` if your environment or framework (like React) handles escaping automatically. Otherwise, manually sanitize any untrusted input before it is passed for interpolation. For most cases, the default `escapeValue: true` is recommended for safety.

Install

• npm install i18next npm
• yarn add i18next yarn
• pnpm add i18next pnpm

Imports

• i18next
  wrong:

  const i18next = require('i18next');

  correct:

  import i18next from 'i18next';

  While CommonJS `require` still works in some Node.js setups, ESM `import` is the idiomatic and recommended way to use i18next, especially in modern projects and bundler environments. Named imports for the default export are also possible: `import { i18next } from 'i18next';`
• init
  wrong:

  import { init } from 'i18next';

  correct:

  import i18next from 'i18next';
  i18next.init(...);

  The `init` method is typically called directly on the imported `i18next` default instance, not as a named export. It returns a Promise.
• TFunction
  wrong:

  import { TFunction } from 'i18next';

  correct:

  import type { TFunction } from 'i18next';

  TFunction is a TypeScript type used for strong typing translation functions, not a runtime value. Always use `import type`.

Quickstart

This quickstart demonstrates basic i18next initialization, loading multiple language resources, and translating keys with interpolation, pluralization, and context. It also shows how to change the active language programmatically.

import i18next from 'i18next';

const initI18n = async () => {
  await i18next.init({
    debug: true,
    lng: 'en',
    fallbackLng: 'en',
    resources: {
      en: {
        translation: {
          'welcome': 'Welcome to our site, {{name}}!',
          'plural_key_one': '{{count}} item',
          'plural_key_other': '{{count}} items',
          'greeting_context_male': 'Hello Sir',
          'greeting_context_female': 'Hello Madam',
          'formatted_date': 'Today is {{date, DATE_HUGE}}'
        }
      },
      de: {
        translation: {
          'welcome': 'Willkommen auf unserer Seite, {{name}}!',
          'plural_key_one': '{{count}} Artikel',
          'plural_key_other': '{{count}} Artikel',
          'greeting_context_male': 'Hallo Herr',
          'greeting_context_female': 'Hallo Frau',
          'formatted_date': 'Heute ist der {{date, DATE_HUGE}}'
        }
      }
    },
    interpolation: {
      escapeValue: false // not needed for react.js, xss is prevented by react
    }
  });

  console.log(i18next.t('welcome', { name: 'User' }));
  console.log(i18next.t('plural_key', { count: 1 }));
  console.log(i18next.t('plural_key', { count: 5 }));
  console.log(i18next.t('greeting', { context: 'male' }));
  console.log(i18next.t('greeting', { context: 'female' }));

  // Example of using a formatter (requires a formatter plugin or custom setup)
  // i18next.services.formatter.add('DATE_HUGE', (value, lng, options) => {
  //   return new Intl.DateTimeFormat(lng, { year: 'numeric', month: 'long', day: 'numeric' }).format(value);
  // });
  // console.log(i18next.t('formatted_date', { date: new Date() }));

  await i18next.changeLanguage('de');
  console.log(i18next.t('welcome', { name: 'Nutzer' }));
};

initI18n();