{"id":11071,"library":"i18next","title":"i18next Internationalization Framework","description":"i18next is a comprehensive and highly popular internationalization (i18n) framework designed for JavaScript environments, supporting browsers, Node.js, and Deno. It provides a robust core for handling translations, enabling features like flexible backend connections for loading translations (e.g., via XHR), optional caching, automatic user language detection, proper pluralization rules, translation context management, variable interpolation, and nested translations. The current stable version is 26.0.6, with a regular release cadence addressing bug fixes, type improvements, and occasional minor features, alongside major releases introducing breaking changes and significant enhancements. Its key differentiators include its extensibility through a rich plugin ecosystem and its framework-agnostic nature, allowing integration with React, Angular, Vue, and vanilla JavaScript applications. It focuses on providing a powerful core while allowing developers to choose their preferred building blocks.","status":"active","version":"26.0.6","language":"javascript","source_language":"en","source_url":"https://github.com/i18next/i18next","tags":["javascript","i18next","internationalization","i18n","translation","localization","l10n","globalization","gettext","typescript"],"install":[{"cmd":"npm install i18next","lang":"bash","label":"npm"},{"cmd":"yarn add i18next","lang":"bash","label":"yarn"},{"cmd":"pnpm add i18next","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for type compatibility with projects using TypeScript.","package":"typescript","optional":false}],"imports":[{"note":"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';`","wrong":"const i18next = require('i18next');","symbol":"i18next","correct":"import i18next from 'i18next';"},{"note":"The `init` method is typically called directly on the imported `i18next` default instance, not as a named export. It returns a Promise.","wrong":"import { init } from 'i18next';","symbol":"init","correct":"import i18next from 'i18next';\ni18next.init(...);"},{"note":"TFunction is a TypeScript type used for strong typing translation functions, not a runtime value. Always use `import type`.","wrong":"import { TFunction } from 'i18next';","symbol":"TFunction","correct":"import type { TFunction } from 'i18next';"}],"quickstart":{"code":"import i18next from 'i18next';\n\nconst initI18n = async () => {\n  await i18next.init({\n    debug: true,\n    lng: 'en',\n    fallbackLng: 'en',\n    resources: {\n      en: {\n        translation: {\n          'welcome': 'Welcome to our site, {{name}}!',\n          'plural_key_one': '{{count}} item',\n          'plural_key_other': '{{count}} items',\n          'greeting_context_male': 'Hello Sir',\n          'greeting_context_female': 'Hello Madam',\n          'formatted_date': 'Today is {{date, DATE_HUGE}}'\n        }\n      },\n      de: {\n        translation: {\n          'welcome': 'Willkommen auf unserer Seite, {{name}}!',\n          'plural_key_one': '{{count}} Artikel',\n          'plural_key_other': '{{count}} Artikel',\n          'greeting_context_male': 'Hallo Herr',\n          'greeting_context_female': 'Hallo Frau',\n          'formatted_date': 'Heute ist der {{date, DATE_HUGE}}'\n        }\n      }\n    },\n    interpolation: {\n      escapeValue: false // not needed for react.js, xss is prevented by react\n    }\n  });\n\n  console.log(i18next.t('welcome', { name: 'User' }));\n  console.log(i18next.t('plural_key', { count: 1 }));\n  console.log(i18next.t('plural_key', { count: 5 }));\n  console.log(i18next.t('greeting', { context: 'male' }));\n  console.log(i18next.t('greeting', { context: 'female' }));\n\n  // Example of using a formatter (requires a formatter plugin or custom setup)\n  // i18next.services.formatter.add('DATE_HUGE', (value, lng, options) => {\n  //   return new Intl.DateTimeFormat(lng, { year: 'numeric', month: 'long', day: 'numeric' }).format(value);\n  // });\n  // console.log(i18next.t('formatted_date', { date: new Date() }));\n\n  await i18next.changeLanguage('de');\n  console.log(i18next.t('welcome', { name: 'Nutzer' }));\n};\n\ninitI18n();\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Replace `initImmediate: true` with `initAsync: true` in your i18next configuration. Ensure your initialization logic correctly handles asynchronous operations.","message":"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.","severity":"breaking","affected_versions":">=26.0.0"},{"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)`.","message":"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.","severity":"breaking","affected_versions":">=26.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=26.0.6"},{"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.","message":"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).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Update your i18next configuration to use `initAsync: true` instead of `initImmediate: true`.","cause":"Attempting to use the `initImmediate` option which was removed in i18next v26.0.0.","error":"`i18next.initImmediate is not a function` or `TypeError: Cannot read properties of undefined (reading 'initImmediate')`"},{"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.","cause":"A race condition where `init()`'s deferred `load()` could overwrite `isLanguageChangingTo`, causing `setLngProps` to be skipped.","error":"Translation does not update after `cloneInstance().changeLanguage()` when the language is not yet fully loaded."},{"fix":"Upgrade i18next to version 26.0.4 or newer. This version correctly resolves inline formatting options to their base format types.","cause":"TypeScript was incorrectly inferring the type for inline formatted variables as `string` instead of their base type (e.g., `number` for `currency`).","error":"Type error: 'string' is not assignable to type 'number' for inline formatting options like `{{price, currency(EUR)}}`."},{"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.","cause":"Bugs in the Formatter logic in earlier v26 releases when handling missing format specifiers or `undefined`/`null` input values.","error":"Formatter crashes when `alwaysFormat` is `true` and no format specifier is present, or returns `NaN` for `undefined`/`null` values."}],"ecosystem":"npm"}