{"id":11067,"library":"i18next-maestroqa","title":"i18next Internationalization Framework","description":"i18next is a comprehensive and highly popular internationalization (i18n) framework for JavaScript environments, including browsers and Node.js. It is currently at version 19.6.4, with active development leading to frequent minor and major releases, indicated by its extensive changelog. The library provides a robust core for handling translations and is designed for high extensibility and flexibility. Key differentiators include its flexible plugin system for backend integrations (e.g., loading translations via HTTP), optional caching mechanisms, automatic user language detection, sophisticated pluralization rules, translation context handling, string nesting, and variable replacement (interpolation). i18next emphasizes building a rich ecosystem, offering integrations with popular frameworks like React, Angular, and jQuery, making it suitable for a wide range of applications. It aims to be a 'learn once - translate everywhere' solution, abstracting complex i18n challenges.","status":"active","version":"19.6.4","language":"javascript","source_language":"en","source_url":"https://github.com/adtribute/i18next","tags":["javascript","i18next","internationalization","i18n","translation","localization","l10n","globalization","gettext","typescript"],"install":[{"cmd":"npm install i18next-maestroqa","lang":"bash","label":"npm"},{"cmd":"yarn add i18next-maestroqa","lang":"bash","label":"yarn"},{"cmd":"pnpm add i18next-maestroqa","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since v19, i18next moved to an ESM-first approach using `export default`. Direct `require('i18next')` in CommonJS environments or without `esModuleInterop: true` in TypeScript might not provide the default export directly, often returning an object with a `default` property.","wrong":"const i18next = require('i18next');","symbol":"i18next","correct":"import i18next from 'i18next';"},{"note":"The `init` function is a method of the default `i18next` instance. It is asynchronous and returns a Promise. Always await its completion to ensure translation resources are loaded before attempting to translate.","wrong":"const i18next = require('i18next');\ni18next.init({...}); // Sync call, might lead to 't is not a function'","symbol":"init","correct":"import i18next from 'i18next';\nawait i18next.init({...});"},{"note":"For TypeScript, the `i18n` interface is available for type declarations, representing the i18next instance. Import it as a type to avoid runtime errors.","wrong":"import { i18n } from 'i18next'; // Incorrectly importing the type as a value","symbol":"i18n (type)","correct":"import type { i18n } from 'i18next';"}],"quickstart":{"code":"import i18next from 'i18next';\n\ninterface MyTranslations {\n  welcome: string;\n  greeting_name: string;\n  item_plural: string;\n}\n\nasync function initializeI18n() {\n  await i18next.init<MyTranslations>({\n    lng: 'en', // default language\n    debug: true,\n    resources: {\n      en: {\n        translation: {\n          welcome: 'Welcome to i18next!',\n          greeting_name: 'Hello, {{name}}!',\n          item_plural: '{{count}} item {{count, plural, one {is} other {are}}} here.'\n        }\n      },\n      de: {\n        translation: {\n          welcome: 'Willkommen bei i18next!',\n          greeting_name: 'Hallo, {{name}}!',\n          item_plural: '{{count}} Artikel {{count, plural, one {ist} other {sind}}} hier.'\n        }\n      }\n    },\n    interpolation: {\n      escapeValue: false // React already escapes values for XSS, set to true for plain JS/Node\n    }\n  });\n\n  console.log(i18next.t('welcome'));\n  console.log(i18next.t('greeting_name', { name: 'World' }));\n  console.log(i18next.t('item_plural', { count: 1 }));\n  console.log(i18next.t('item_plural', { count: 5 }));\n\n  await i18next.changeLanguage('de');\n  console.log(i18next.t('welcome'));\n  console.log(i18next.t('greeting_name', { name: 'Welt' }));\n  console.log(i18next.t('item_plural', { count: 1 }));\n  console.log(i18next.t('item_plural', { count: 5 }));\n}\n\ninitializeI18n();","lang":"typescript","description":"This quickstart demonstrates how to initialize i18next with basic translation resources, perform simple key-based translations, utilize interpolation for dynamic values, and handle pluralization. It also shows how to change the active language programmatically, all within an asynchronous context, which is crucial for i18next's `init` function."},"warnings":[{"fix":"Always `await i18next.init(...)` or use `.then()` to ensure the initialization process has finished before attempting to use the translation instance. In frameworks like React, use hooks or components that handle readiness states.","message":"i18next.init() is asynchronous and returns a Promise. Calling translation functions like `i18next.t()` before `init` has completed (i.e., before its Promise resolves) will result in errors such as 't is not a function' or incorrect translations.","severity":"gotcha","affected_versions":">=13.0.0"},{"fix":"Ensure all `i18next.use(plugin)` calls are made before `i18next.init(options)`. Example: `i18next.use(LanguageDetector).use(Backend).init({...});`","message":"Plugins (e.g., `i18next-http-backend`, `i18next-browser-languagedetector`) must be registered using `i18next.use()` before the `i18next.init()` call. Incorrect order will prevent plugins from being loaded or functioning correctly.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For TypeScript projects, enable `\"esModuleInterop\": true` in your `tsconfig.json`. Alternatively, for strict CommonJS, you might need to import using `const i18next = require('i18next').default;` or `import { default as i18next } from 'i18next';` to correctly access the default export.","message":"With `i18next` v19, the TypeScript definitions and internal module structure shifted to an ESM-first approach, using `export default`. If you are using CommonJS (`require()`) with TypeScript and `esModuleInterop` is not enabled in your `tsconfig.json`, you might encounter type errors or runtime issues when importing. This was noted as a TypeScript change rather than an API change.","severity":"breaking","affected_versions":">=19.0.0"},{"fix":"Configure namespaces in `init` options (e.g., `ns: ['common', 'components'], defaultNS: 'common'`). When translating, specify the namespace for non-default ones: `i18next.t('components:header.title')`.","message":"By default, i18next uses the 'translation' namespace for all keys. If you organize translations into multiple JSON files (e.g., `common.json`, `components.json`), you must explicitly configure namespaces in `i18next.init()` via the `ns` option and specify the desired namespace when calling `t('namespace:key')` or set a default namespace with `defaultNS`.","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":"Ensure that `i18next.init()` is `await`ed or chained with `.then()` before any calls to `i18next.t()` are made. In application entry points, this might involve waiting for initialization before rendering UI that uses translations.","cause":"The `i18next` instance's `t` function is called before `i18next.init()` has completed its asynchronous loading of resources and configuration.","error":"TypeError: i18next.t is not a function"},{"fix":"In your `tsconfig.json`, ensure `\"esModuleInterop\": true` is set under `compilerOptions`. If you cannot use `esModuleInterop`, you might need to adjust your import statement to `import { default as i18next } from 'i18next';` or cast the imported module.","cause":"This TypeScript error typically occurs when `i18next` is imported in a CommonJS-style project (or without `esModuleInterop`) after v19, where the library moved to an `export default` pattern for its main instance.","error":"Property 'use' does not exist on type 'typeof import(\"i18next\")'"},{"fix":"Verify that the key provided to `i18next.t()` directly corresponds to a string value in your translation files. For nested keys, use dot notation (e.g., `t('namespace:path.to.string')`). Ensure the key exists for the active language and its fallbacks.","cause":"This warning (or error if `i18next.strictMode` is enabled) indicates that `i18next.t()` was called with a key that resolves to an object in your translation resources, not a string. This often happens if you're trying to translate a parent object key instead of a specific string within it, or if the key is entirely missing.","error":"i18next: hasKeyEn: key 'your.key' returned an object instead of string."}],"ecosystem":"npm"}