NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm, #2339 most downloaded on npm
i18next internationalization framework
Latest stable
27.2.3
Last release today
21 Nov 2026
Release timing varies
gaps range from 8 days to 6 weeks
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
15 years old
642 releases · first in 2012
Drag across the ruler to compare, or tap a release to open it.
fix: a variable in the options of a nested $t(key, { "name": "{{name}}" }) is escaped once. With the default escapeValue: true it was escaped for HTML
$t(key, { "name": "{{name}}" }) is escaped once. With the default escapeValue: true it was escaped for HTML before the options were parsed and again by the nested t(), so Tom & Jerry came out as Tom & Jerry (and react-i18next's Trans has shown Tom & Jerry since 17.1.10, with escapeValue: false too). These variables are now escaped for the options' JSON, whatever escapeValue is, and the nested t() escapes them like the values of a direct call; defaultValue and joinArrays there, which it does not interpolate, stay escaped once. A value with ", ', \ or a line break no longer breaks the options, with escapeValue: false a value can no longer inject options such as lng, and with skipOnVariables a {{placeholder}} inside a value is no longer interpolated a second time. The warning added in 26.0.6 now covers {{- var}} in these options, the one form still inserted unescaped, instead of escapeValue: false.fix: setDefaultNamespace() works on a clone. A clone's translator keeps its own options object, so the call changed i18n.options.defaultNS while t() k
Your coding agent can read these notes before it upgrades. Set up the MCP server →
setDefaultNamespace() works on a clone. A clone's translator keeps its own options object, so the call changed i18n.options.defaultNS while t() kept using the old default namespace. i18next-http-middleware hands every request a clone, so req.i18n.setDefaultNamespace() did nothing there. (#2106)supportedLngs works in any casing. Every other language code is formatted (pt-br to pt-BR, EN to en, all lowercase with lowerCaseLng), but supportedLngs was compared as written, so supportedLngs: ['pt-br'], ['EN'], or ['pt-BR'] with lowerCaseLng: true refused that language and fell back. They are now compared in that formatted form (also by loadLanguages()), while options.supportedLngs stays as written. (#1791)interfaces get their nested keys. The key types only walked into objects with an index signature, which a type alias has and an interface does not, so t('nested.key') failed with TS2345 while t('nested') compiled. Interfaces now give the same keys as type aliases, so t('nested') without returnObjects is rejected for them too. (#2326)strictNullChecks: false. Without strict null checks undefined passes extends string, so the key prefix, namespace and context checks took a missing keyPrefix, ns or context for a value: t('title') was rejected (only t('ns:title') compiled), t() returned string, and react-i18next's Trans accepted no i18nKey. A new type test project compiles with strictNullChecks: false; with strict null checks the types resolve as before. (#2085)fix: a variable passed as undefined renders as an empty string when its placeholder has a format too ( {{amount, number}} ), as {{amount}} already did
undefined renders as an empty string when its placeholder has a format too ({{amount, number}}), as {{amount}} already did. The placeholder stayed in the result with the default skipOnVariables: true, and debug mode logged "missed to pass in variable" with either setting. Thanks @Vineet829 (#2479)fix: an error thrown by a load callback or a listener (the callback of init , changeLanguage , loadNamespaces or loadLanguages , or a languageChanged
init, changeLanguage, loadNamespaces or loadLanguages, or a languageChanged / loaded listener) is no longer handed back to the backend connector as if the read had failed. With a backend whose read returns a value or a promise, the connector got that error a second time: the namespace that had loaded was marked as failed, failedLoading was emitted with your error and the count of running reads dropped to -1. The error now reaches your app: it is thrown from the call that started the load for a read that returns a value, and it is an unhandled rejection for a read that returns a promise, which ends a Node.js process unless you handle unhandledRejection. Thanks @SudeepGowda55 (#2477)loaded event is still emitted, and the error is thrown on after that. A second loadNamespaces() for the same namespace never called back before.addResourceBundle(lng, ns, resources, true, true) overwrites numbers and booleans too. Only strings were replaced, so { n: 0 } stayed 0 after adding { n: 5 }, and adding an object where the bundle had a number, boolean or null threw Cannot create property ... on number, also without overwrite. With overwrite, a number, boolean or null now also replaces a nested object, as a string already did. Thanks @SudeepGowda55 (#2476)keySeparator: false, a namespace separator inside the key after the namespace is kept. t('common:errors:required') looked up 'errorsfalserequired' instead of the flat key 'errors:required' that i18next-cli extracts (also for a selector like $ => $.common['errors:required']), and reported the missing key under that name. This dates back to 11.3. Thanks @SudeepGowda55 (#2478)fix: off(event, listener) removes a listener added with once() . once() registers a wrapper, so off() with the listener itself found nothing and the l
off(event, listener) removes a listener added with once(). once() registers a wrapper, so off() with the listener itself found nothing and the listener still ran on the next event. A once() listener is now also removed before it runs, so one that emits the same event again (like calling changeLanguage() from languageChanged) or throws runs only once. Thanks @SudeepGowda55 (#2475)fix(types): with enableSelector , assigning a t function to a wider TFunction ( TFunction<'ns'> to TFunction<'ns', string> or TFunction<Namespace> , o
enableSelector, assigning a t function to a wider TFunction (TFunction<'ns'> to TFunction<'ns', string> or TFunction<Namespace>, or a key prefix to a wider one) failed with TS2590 "Expression produces a union type that is too complex to represent" once the namespaces had about 600 top-level keys together. This started in 26.3.3. Selector results for JSON arrays that mix arrays with objects or strings also keep the inner arrays as arrays. Thanks @reckter (#2474)security: a language code named after a property every object inherits ( hasOwnProperty , isPrototypeOf , toLocaleString , __defineGetter__ , ...) mad
hasOwnProperty, isPrototypeOf, toLocaleString, __defineGetter__, ...) made the backend connector throw obj[k].push is not a function when its load finished. A language detector passes such a code on from a request (?lng=hasOwnProperty), and with an asynchronous backend nothing caught the throw, so one request ended a Node.js server process (in a browser, init() never resolved). Now these codes load like any other unknown language. Thanks @superbot-helper (GHSA-q76c-gcvw-89x9)fallbackLng, a language code named like an Object.prototype property (constructor, toString, hasOwnProperty, constructor-US) gets the default fallback instead of making t(), exists(), getFixedT() and changeLanguage() throw fallbackCodes.forEach is not a function. Thanks @cyphercodes (#2473, #2472)security: language codes and namespaces that come from requests no longer grow the memory of a server without end. The backend connector kept one entr
supportedLngs: false, every made-up language a detector found (?lng=xx1, ?lng=xx2, ...) or every made-up namespace requested from i18next-http-middleware's getResourcesHandler added about 180 bytes for good. Now only the most recent 1000 failed loads are kept (an older one is read again when it is needed), and both caches are emptied at 1000 codes, as the formatted language codes already were. Pairs with i18next-http-middleware 3.10.1 (GHSA-mjcw-gfh6-3cxm).perf: t() skips the interpolation and nesting regexp scans when the text has no interpolation or nesting prefix, about 6-14% faster for short texts an
feat: when the plural form selected for count is missing, t() uses the _other form of the same language before the next fallback language, as CLDR doe
count is missing, t() uses the _other form of the same language before the next fallback language, as CLDR does (lateral inheritance), instead of returning the key. Current CLDR data gives French, Spanish, Italian and Portuguese a many form for exact millions, so files with only _one and _other showed the key (or the fallback language) for count: 1000000. The plain key still comes first, so key + key_other keeps resolving key; with a context, key_<context>_other comes before key_other; ordinals use _ordinal_other; and defaultValue_other is used after defaultValue. A form filled in from _other is no longer reported as missing (saveMissing, missingKeyHandler, exists()). Thanks @TenPotatoes (#2468)fix: each cached format keeps at most 1000 formatters, dropping the oldest when full. This covers the built-in formats (number, currency, datetime, re
cacheInBuiltFormats: true, and formats added with addCached. The cache key holds all t() options, including the interpolated values, so every new amount, date or name added a formatter that was never released: about 50 MB per 100k values, growing without end in a long-running server. A dropped formatter is made again from the same language and options, so the output does not change. Thanks @liustack (#2467).Set cleanCode: false to keep codes without a region exactly as they are. cleanCode is deprecated.
This is a major breaking release. It changes defaults that most setups had to override, gives every instance its own logger and post-processors, refuses language codes that look like markup or paths, and removes options that were broken or had no effect. 26.7 warned in debug mode about most of the runtime changes. The migration guide has the details; to keep the v26 behavior where an option exists:
i18next.init({
fallbackLng: 'dev', // or better your source language: there is no implicit 'dev' any more
returnEmptyString: true, // an empty translation is a translation again
cleanCode: false, // keep codes without a region as they are ('EN' stays 'EN')
});declare module 'i18next' {
interface CustomTypeOptions {
strictInterpolationChecks: false;
returnEmptyString: true;
}
}fallbackLng defaults to false instead of ['dev']. Without a fallbackLng, i18next no longer requests dev from the backend (/locales/dev/translation.json with i18next-http-backend), and saveMissing sends missing keys for the current language instead of dev. With supportedLngs and no fallbackLng, an unsupported language leaves language and languages unset, as fallbackLng: false already did. Set fallbackLng to your main language, or to 'dev' for the previous behavior.returnEmptyString defaults to false: an empty translation falls back like a missing value (to the fallback language, the default value or the key), as null already does. i18next-cli writes '' for untranslated keys in the other languages, which now fall back instead of rendering blank. An explicit '' default from code still counts: t('key', '') and t('key', { defaultValue: '' }) return ''. Set returnEmptyString: true (in init() and in CustomTypeOptions) if an empty translation is meant to render nothing, for example for a Locize project with "preserve empty strings" on.'EN' becomes 'en'. Only the casing changes: aliases like tl, iw or eng stay as they are ('TL' becomes 'tl'), and so do codes that are not BCP 47 (en_US, my_custom). i18next 26.7.0 and 26.7.1 warned that v27 turns iw into he or tl into fil; that was wrong and 26.7.2 corrects it. iw, tl and the like stay as they are. Set cleanCode: false to keep codes without a region exactly as they are. cleanCode is deprecated.strictInterpolationChecks defaults to true: t() needs the options for a string with variables, so a {{name}} cannot be left out of a call. Type a wrapper around t() with ParseKeysWithoutVariables, declare the variables interpolation.defaultVariables fills in with defaultVariables in CustomTypeOptions, or set strictInterpolationChecks: false to keep the v26 types (also for ICU and MF2 messages, whose arguments are required either way). The fixes below close the gap plural keys left.returnEmptyString defaults to false in TypeOptions too, so a key whose value is '' is typed as the key.use() of a logger or a post-processor on one instance no longer changes the others, and the init() of one instance no longer rewires the logging of all of them. An instance from createInstance() does not see what the default i18next instance (or any other) registered: call use() on each instance. A clone (cloneInstance()) keeps its parent's logger and post-processors, also those its parent registers later, and what it registers itself stays its own. A plugin that calls use() from its own init() (the Locize InContext editor) registers right away, as before. services.logger stays the instance's logger, with forward(). In debug mode, a postProcess name that is not registered on the instance logs a warning.returnObjects is handled like a missing key: t() returns the default value if one is passed, else the key (with appendNamespaceToMissingKey, parseMissingKeyHandler and the post-processors applied), instead of the sentence key '... (en)' returned an object instead of string., which ended up in the UI. It is not saved as missing, since the key exists. The debug warning stays, and returnedObjectHandler still decides what is returned when it is set (returnedObjectHandler: (key) => `key '${key}' returned an object instead of string.` brings a sentence back).addResources() keeps every value: numbers, booleans and objects were dropped silently, only strings and arrays were added./: '$10/month' stays '$10/month' instead of '$10/month', and dates in react-i18next's Trans no longer render as 17/12/2025 (discussion 2199). &, <, >, " and ' are still escaped, which covers HTML text and quoted attributes; a / cannot end either. Update snapshots that contain /, or pass your own interpolation.escape to keep escaping it.lng, changeLanguage(), a language detector or loadLanguages() that does not have the shape of isSafeLanguageCode() (letters, digits, -, _, @ and ., no .., at most 128 characters) is refused unless it is configured: listed in supportedLngs, in a fallbackLng that is not a function or in preload, or a language in resources, as given to init(). changeLanguage() continues as with an unsupported code: with the detector's next code, else the fallback language, else none (with fallbackLng: false, a code refused at init() leaves language unset); loadLanguages() skips it. With supportedLngs, the input is matched as before ('de-DE;q=0.9' still gives 'de'), and only an unsafe match is refused, which only nonExplicitSupportedLngs can return ('de-<x>' for a supported 'de'). Without supportedLngs, a detector that returned "><img src=x onerror=alert(1)> made that string i18next.language, which apps put into <html lang>, and backends were asked to load it. BCP 47, POSIX (en_US.UTF-8@euro, sr@latin) and private-use codes (en-x-pirate) pass; to use a code with other characters (+, spaces, /), list it in supportedLngs. In debug mode a refused code logs a warning.createInstance(options) merges the defaults right away, without initializing: before init(), instance.options has the defaults, getFixedT() no longer throws (t() returns '' until init()), and debug: true already shows the warnings before init(). init() still tells the options you set from the defaults, so a keySeparator or nsSeparator passed to createInstance() counts as set by you (#2426). loadNamespaces() before init() does nothing and calls back, as it did for an instance without options.keySeparator: false means flat keys only: a lookup no longer splits a key at the text false (t('nestedfalsec') returned the value of nested.c), and a selector path is joined with . like a key prefix, so selectors work on the flat keys ($ => $['a.b'] and $ => $.a.b look up the flat key 'a.b'; $ => $.nested.c no longer resolves nested, then c). types: with keySeparator: false in CustomTypeOptions, the keys are the flat keys (no nestedfalsec keys), a key containing false is no longer split, and keyPrefix takes the parts of the flat keys before a ., which is how getFixedT() joins it ('nested' for 'nested.c'). A key prefix combined with selectors is not typed for flat keys.getResource('en.translation.key'), addResource('en.translation.key', value) and addResourceBundle('en.translation', resources). Pass language, namespace and key as separate arguments; addResource(), addResources() and addResourceBundle() throw a TypeError for the dotted form. A language code with a . (de_DE.UTF-8) is now a language like any other.interpolation.prefixEscaped, suffixEscaped, nestingPrefixEscaped and nestingSuffixEscaped, which were inserted into the RegExp unescaped. Pass the literal delimiters as prefix, suffix, nestingPrefix and nestingSuffix.compatibilityJSON (it had no effect since v24).locizeLastUsed is declared by locize-lastused (5.1.0 and later). ReactOptions stays importable from 'i18next' but is empty: react-i18next fills it in (17.1.13 and later, and 18), so the react options are checked when react-i18next is in the program._ and $ helpers in typescript/t.d.ts and typescript/options.d.ts ($FirstNamespace, _ValueOf and 84 more) are no longer importable; every declaration of those files counted as exported. The other types of those files (TOptionsBase, TFunctionSignature, ParseTReturn, ...) are now exported on purpose. If you imported one of the hidden helpers, please open an issue: exporting it again does not break anything.index.js, a CommonJS shim that the exports map made unreachable.engines); CI tests 22, 24 and 26.defaults, which moved with every update of the browser data. The output is the same as 26.7's.^5 || ^6 || ^7, unchanged.callbackApi still work; i18next guesses their calling convention from the number of parameters and logs a deprecation warning in debug mode.isInitialized, initializedStoreOnce and initializedLanguageOnce stay writable, so react-i18next 17's useSSR and next-i18next's Pages Router work with 27. Writing them is deprecated: call hydrate().services.backendConnector.backend stays readable.strictInterpolationChecksstrictInterpolationChecks, a plural key no longer switches the check off. Without count a plural key like item (item_one, item_other) has no value of its own, and the string it resolved to hid the variables of every other key in a union: (key: 'greeting' | 'item') => t(key) and (key: ParseKeys<'ns'>) => t(key) compiled as soon as the namespace had a plural key, while the same wrapper without one failed. Now such a call is checked against the plural forms, ordinal ones and 'ns:item' keys included: t('item') needs count when the forms use it, and a wrapper over a union with a plural key fails as it does without one. To migrate, pass count, or type the wrapper with ParseKeysWithoutVariables.strictInterpolationChecks, a call with options needs the variables of a plural key's forms too: t('item', { defaultValue: 'x' }) and (key: 'plain' | 'item') => t(key, { defaultValue: 'x' }) need count when the forms use it, as t('item') does. Before, any options object turned the check off for a plural key without count. Without the flag the options types are unchanged.ParseKeysWithoutVariables leaves out a key whose ordinal forms take count, and keeps a key that has its own value next to its plural forms, since t() returns that value without count.t('ns:item') for a plural key without count returns string, as t('item') does, instead of never.fix: the debug-mode deprecation warning for a language code without a region no longer says that v27 replaces aliases. 26.7.0 and 26.7.1 warned that v…
'iw' into 'he' or 'tl' into 'fil' and asked you to rename them. v27 only gives such codes their canonical casing ('EN' becomes 'en', 'IW' becomes 'iw'), so iw, tl, eng and similar codes stay as they are. If you renamed them because of that warning, you can keep or restore the old codes. The warning now only appears when the casing changes.fix: reloadResources() retries the bundles that failed to load. The load queue skipped them also when reloading, so a language whose first load failed
reloadResources() retries the bundles that failed to load. The load queue skipped them also when reloading, so a language whose first load failed (a backend or network outage at startup) stayed missing. i18next-http-backend 4.0.8, i18next-chained-backend 5.0.7 and i18next-locize-backend 10.0.5 reload through reloadResources() with i18next 26.7, so their reloadInterval no longer recovered from such a failure, as their own reload did before.reloadResources() without languages reloads the current languages and every language the backend loaded or tried to load, for the instance and its clones, as the API docs describe ("pass languages and namespaces if you don't want to reload all"). It reloaded only the current languages, so on a server (one clone per request with i18next-http-middleware) a backend's reloadInterval never refreshed the languages loaded for requests. It never requests cimode. With languages given, nothing changes.…reserved for the callback-less form. Guessing is deprecated: in debug mode an unmarked backend or async detector logs a deprecation warning, once per…
The last 26.x minor before v27, which follows in about a week. It adds the APIs v27 builds on, and with debug: true it warns wherever a setup relies on something v27 changes. Most of the v27 defaults are existing options, so you can try them now:
i18next.init({
debug: true, // prints the warnings below
fallbackLng: 'en', // v27: fallbackLng defaults to false, set your source language (no implicit 'dev')
returnEmptyString: false, // v27 default: an empty string falls back like a missing key
cleanCode: true, // close to v27, which canonicalizes codes without a region ('EN' becomes 'en')
});declare module 'i18next' {
interface CustomTypeOptions {
strictInterpolationChecks: true; // v27 default
returnEmptyString: false; // v27 default
}
}The other v27 changes (/ no longer escaped in values, a logger and post-processors per instance, the key instead of a sentence for an object hit, the dotted-language store calls and *Escaped options removed) have no switch; the debug warnings below show where they apply.
skipOnVariables: true, a missing interpolation variable is now logged in debug mode, once per string and variable: missed to pass in variable name for interpolating Hello {{name}}. The raw {{name}} reached the UI without any log line, even with debug: true, because the warning only ran with skipOnVariables: false. A variable passed as undefined and a missingInterpolationHandler still log nothing.i18next.hydrate(resources, lng) puts resources rendered on the server into the store and changes to the server's language, each only the first time. It does what react-i18next's useSSR did by writing resourceStore.data, options.ns, isInitialized, initializedStoreOnce and initializedLanguageOnce directly, and sets the same flags, so integrations can switch to it and stay compatible with code that still reads or writes them. On a clone it does nothing, as useSSR does: a clone shares its parent's store (one clone per request with i18next-http-middleware). Called before init(), it logs a warning and changes nothing.services.utils.reloadResources() lets a backend reload its bundles through i18next (as i18next.reloadResources(), with retries and the loaded event), instead of calling backendConnector.read() and loaded() itself as the reloadInterval of i18next-http-backend and i18next-chained-backend does. Without languages (no lng, no detector, the default fallbackLng), reloadResources() reloads nothing instead of throwing Cannot read properties of undefined (reading 'forEach'); a backend that also reloads preload passes its languages.callbackApi (an instance or static property). true: read(language, namespace, callback), create(languages, namespace, key, fallbackValue, callback, options) and detect(callback); false: they return a promise or a value, and create gets the options as its fifth argument. Without it, i18next keeps guessing from the number of parameters (Function.length), which default and rest parameters change: i18next-chained-backend's create(..., clb = () => {}, opts = {}) has length 4 and never got its options (isUpdate), and i18next-http-backend's callback form of create has length 5, the length reserved for the callback-less form. Guessing is deprecated: in debug mode an unmarked backend or async detector logs a deprecation warning, once per init().isSafeLanguageCode(code) is exported for plugins that take a language from a request, a URL or storage: letters, digits, -, _, @ and . (no ..), at most 128 characters, not a prototype key. It is not a BCP 47 check, so en_US, zh_Hant_TW, sr@latin and de_DE.UTF-8 pass; markup, slashes and spaces do not. The language detector, i18next-http-middleware and i18next-http-backend each have their own rule today.use() logs a warning in debug mode when a second backend, language detector, i18nFormat or formatter replaces the first one; only one of each is used per instance, and losing an ICU setup this way was silent. As use() usually runs before init(), the warning is printed once init() has set up the logger.ParseKeysWithoutVariables<Ns, KPrefix>, the keys t() takes without options: their string has no variables, and a plural key is left out when its forms take count. A wrapper typed with it, like (key: ParseKeysWithoutVariables<'common'>) => t(key), compiles with strictInterpolationChecks without a cast.defaultVariables in CustomTypeOptions declares the variables interpolation.defaultVariables fills in at runtime (defaultVariables: { appName: string }). They become optional in the t() options, also with strictInterpolationChecks; passed, they keep their type.interpolationFormatSeparator in CustomTypeOptions for a custom interpolation.formatSeparator: the types split {{price, currency}} at a hard-coded ,, so with formatSeparator: ';' the format was not recognized. The per-call skipInterpolation option is typed, and returnedObjectHandler may return a value (what it returns is what t() returns; it was typed as returning void).SelectorFn, ApplyTarget, ConstrainTarget and GetSource are exported on purpose, under their current names. react-i18next imports them for Trans; they were importable only because every declaration in the type files counts as exported.nsSeparator: false in CustomTypeOptions, the key union no longer contains nsfalsekey-style keys for the other namespaces, and a key that contains the text false (isfalsey) is no longer split at it, which typed its t() result as never.saveMissing now checks that the namespace is loaded for the instance that misses the key. Each cloneInstance() pointed the parent's services.utils.hasLoadedNamespace at the new clone, and the backend connector, which all clones share, used that one: a key missing in one request was not saved (did not save key ... as the namespace ... was not yet loaded) while a newer request was still loading its language, and the parent's services.utils answered for the newest clone. A clone's services.utils is now bound to the clone, and the parent keeps its own. A direct services.backendConnector.saveMissing() call, like the missing keys route of i18next-http-middleware, still checks the newest clone (follow-up to #1413).dir() without a language (before init(), or with no language resolved) returns 'ltr' instead of 'rtl' (discussion #2135).t() before init() returns an empty string, as typed (with a warning when debug logging is already on); it returned undefined.off('a b', listener) removes the listener from both events, as on('a b', listener) adds it to both. It looked for an event named 'a b', so once('a b', listener) never removed its listener and ran it on every event.getResource('en.translation.key'), addResource('en.translation.key', value), addResourceBundle('en.translation', resources)) log a deprecation warning in debug mode; they are removed in v27. Pass language, namespace and key as separate arguments.interpolation.prefixEscaped, suffixEscaped, nestingPrefixEscaped and nestingSuffixEscaped (inserted into the RegExp unescaped) log a deprecation warning in debug mode and are marked @deprecated; they are removed in v27. Pass the literal delimiters as prefix, suffix, nestingPrefix and nestingSuffix.compatibilityJSON is marked @deprecated (it has no effect since v24) and removed from the types in v27.'EN' stays 'EN' today and becomes 'en' in v27, 'iw' becomes 'he'. cleanCode: true already lower-cases them.fallbackLng is not set, the first request for the default fallback language dev (loading it, or saving missing keys to it) logs a notice in debug mode: v27 defaults to fallbackLng: false and no longer requests dev. Set fallbackLng to your source language, or to 'dev' to keep the current behavior.lng, changeLanguage() or the language detector, is not configured (supportedLngs, fallbackLng, preload or the resources) and fails isSafeLanguageCode logs a deprecation warning, once per code: without supportedLngs, a detector that returns "><img src=x onerror=alert(1)> makes that string i18next.language, and apps put it into <html lang>. Nothing changes in 26.7; v27 is planned to refuse such codes and continue as with an unsupported code. Language codes are still not bound to a format.use() logs a deprecation warning (call use() on this instance too), and a non-clone init() that replaces the logger another instance set with use() logs one through that logger./ under the default escape logs that v27 no longer escapes / ($10/month renders as $10/month today; not with escapeValue: false, where react-i18next's Trans escapes one call itself and decodes the entities afterwards), and an object or array hit without returnObjects logs that v27 returns the key instead of the sentence key '... (en)' returned an object instead of string..files whitelist instead of .npmignore, which had to mirror every local or secret file by hand. The tarball is unchanged. The root i18next.js and i18next.min.js (copies of dist/umd/, still published for the unversioned unpkg URLs) are built by npm run build and no longer tracked in git.feat(types): new strictInterpolationChecks type option (default false ). With strictInterpolationChecks: true in CustomTypeOptions , t() needs its opt
strictInterpolationChecks type option (default false). With strictInterpolationChecks: true in CustomTypeOptions, t() needs its options for a string with {{variables}}: for 'Hello {{name}}!', t('greeting') is a type error and t('greeting', { name }) compiles. Left out, the variable reaches the UI as the raw {{name}} placeholder. This applies to string keys, selectors, selector arrays and getFixedT, and with strictKeyChecks also to t(key, defaultValue). Without the flag nothing changes. With the flag on, a wrapper that passes on a key type ((key: ParseKeys<'ns'>) => t(key), or a generic K extends ParseKeys) no longer compiles without options, as the variables of its string are not known there. parseInterpolation: 'icu' and 'mf2' require their arguments as before. Thanks @Alex0007 (#2465).count, as a single selector does since v25.9.0. Without count, i18next skips the plural member at runtime, so t([($) => $.item, ($) => $.plain]) returned the plain value while typed as the plural forms. An array of selectors with defaultValue now returns the literal values and the default value ('a' | 'b' | 'x') instead of string. Thanks @Alex0007 (#2465).fix: with keySeparator: false or a custom separator like '::' , a nested interpolation value that is 0 , false or '' is now inserted. 'You have {{stat
keySeparator: false or a custom separator like '::', a nested interpolation value that is 0, false or '' is now inserted. 'You have {{stats.unread}} unread messages' with { stats: { unread: 0 } } kept the raw {{stats.unread}} placeholder (or became '' with skipOnVariables: false), also for formatted values like {{order.total, currency(USD)}} and for nested defaultVariables: a falsy value was looked up again with the configured separator, which does not split stats.unread. The default '.' separator was not affected. When the same name exists both nested and as a flat dotted key ({ a: { b: 0 }, 'a.b': 'flat' }), the nested 0, false or '' now wins, as a truthy one already did; a nested null still falls back to the flat key. Thanks @nk-batman21 (#2464).cloneInstance({ forkResourceStore: true }) no longer changes the options object it is given. It deleted forkResourceStore from it, so reusing the same object for a second clone silently shared the parent's resource store (adding a resource to that clone also changed the parent), and frozen options threw a TypeError. Clones without forkResourceStore are unchanged. Thanks @edsonsims (#2463).t(($) => ...) (enableSelector: true / 'strict') no longer filters the whole namespace, and no longer does it again for every distinct context value. To drop keys without anything to select, the filtered type looked at the filtered keys of every nested object, down to the leaves, also for the branches the selector does not read. It now decides from the source value. With 10,000 keys in 100 groups, one call went from 3.3M type instantiations (1.7s) to 0.85M (0.8s), and ten calls with ten contexts from 21.7M (8.8s) to 1.05M (0.9s), on TypeScript 6. Selected values are unchanged for context, plural, ordinal, nested and array keys, with three side effects: a type error on a selector now shows the type as FilterKeysObject<{ ...source keys }, Context> instead of the filtered object, an object whose values are all null or undefined ({ x: null }) is kept as {} instead of being dropped, and a null key next to its plural forms (foo: null, foo_one, foo_other) is typed as the plural value instead of never. Thanks @GabrielVooDB (#2462).fix: a nested false, 0 or '' is now returned when a flat key with the same dotted name also exists. With { a: { b: false }, 'a.b': 'flat' }, getResour
false, 0 or '' is now returned when a flat key with the same dotted name also exists. With { a: { b: false }, 'a.b': 'flat' }, getResource('en', 'translation', 'a.b') and t('a.b') returned 'flat': the nested result was checked for truthiness, so these present values fell through to the flat-key lookup. Without such a flat key they were already returned. A nested null, which is not a valid lookup by default (returnNull: false), still falls back to the flat key. Thanks @lprnmns (#2461).fix: when none of the detected languages is in supportedLngs, the best match no longer picks a different language whose code only starts with the same
supportedLngs, the best match no longer picks a different language whose code only starts with the same letters. The last fuzzy check took any supported code starting with the language part, so with supportedLngs: ['en', 'fil-PH'] a Finnish user (fi-FI) got Filipino instead of the fallback language, and ha (Hausa) picked haw-US (Hawaiian). Other regions of the same language still match as before (de-CH → de-DE, pt-PT → pt-BR, fil → fil-PH). Compatibility note: a two-letter code no longer matches a supported three-letter code that extends it, like ar → arz-EG, sw → swh-KE or no → nob-NO; list the two-letter code in supportedLngs (or map it with fallbackLng) if you relied on that. Thanks @Pharex38 (#2460).fix: nested lookups no longer resolve to methods inherited from the prototype, like constructor, toString or map. Only the top level was guarded, so {
constructor, toString or map. Only the top level was guarded, so {{constructor}} was treated as missing, but {{user.constructor}} rendered the function source (with a class instance, the full source code of the class), and {{user.toString}}, {{items.map}} or a class method like {{user.greet}} did the same. The same lookup is used for translation keys when ignoreJSONStructure is on (the default): a nested key named like an inherited method that is missing in the current language (t('roles.constructor') with roles.constructor only in the fallback language) returned function Object() { [native code] } instead of falling back, and exists('roles.valueOf') returned true. These keys are now missing, so the fallback language, missingInterpolationHandler, saveMissing and the missing key handler apply as for any other missing key. Getters defined on a class ({{user.fullName}} with get fullName()) still work. Nested lookups also no longer walk into the prototype via __proto__, so {{user.__proto__.constructor}} no longer prints the class source either. Thanks @Pharex38 (#2459).fix: arrays returned with joinArrays now get the same resolved details as strings. The joined value was extended with lastKey in the place of the reso
joinArrays now get the same resolved details as strings. The joined value was extended with lastKey in the place of the resolved lookup, so with postProcessPassResolved a post processor got no usedLng, usedNS or exactUsedKey (t('steps', { joinArrays: ' / ' }) reported undefined/undefined:undefined). This affected the subliminal post processor used by the locize InContext editor, which could not map a joined array to its key. The nesting recursion guard did not get the parent key either, so arrays that nest each other (listA: ['a', '$t(listB)'], listB: ['b', '$t(listA)']) threw Maximum call stack size exceeded. They now stop at the guard, as strings do. An i18nFormat plugin with handleAsObject and parse also no longer throws Cannot read properties of undefined (reading 'usedNS') on joined arrays. Thanks @nk-batman21 (#2458).fix: with the default cacheInBuiltFormats: true, built-in formats now also work when the t() options contain a BigInt or a circular object. The cache
cacheInBuiltFormats: true, built-in formats now also work when the t() options contain a BigInt or a circular object. The cache key was built with JSON.stringify over all options, including the interpolation values, which throws on those, so every built-in format in that call returned the raw value: t('num', { val: 12345678901234567890n }) with 'Total: {{val, number}}' returned 'Total: 12345678901234567890' instead of 'Total: 12,345,678,901,234,567,890', and passing an object with a back-reference (like an ORM entity) left all numbers, dates and lists of that call unformatted. When the key cannot be built, the value is now formatted without the cache, as with cacheInBuiltFormats: false. This also applies to formatters added with addCached. Other calls still use the cache as before. Thanks @nk-batman21 (#2457).fix: cloneInstance({ forkResourceStore: true }) now copies the resources at every level. It copied them only down to the namespace objects, so nested
cloneInstance({ forkResourceStore: true }) now copies the resources at every level. It copied them only down to the namespace objects, so nested keys and arrays stayed shared with the original instance: addResource() with a nested key (fork.addResource('en', 'translation', 'greeting.hello', 'Hi')) or a deep addResourceBundle() on the fork also changed the original instance and every other fork. Flat keys were already isolated. Forking a large store takes a bit longer: with 300k keys in nested groups, about 11 ms instead of 3 ms per fork. Clones without forkResourceStore still share the store as before. Thanks @nk-batman21 (#2456, follow-up to #2270).fix: with the default skipOnVariables: true, a {{placeholder}} inside a value inserted with an unescaped {{- var}} now stays literal, as it already di
skipOnVariables: true, a {{placeholder}} inside a value inserted with an unescaped {{- var}} now stays literal, as it already did for {{var}}. The escape pass ran after the unescaped values were written and scanned them again, so t('{{- a}}', { a: '{{b}}', b: 'c' }) returned 'c' instead of '{{b}}'. With pre-built HTML that carries user text, like t('You may contact {{name}} at {{- emailHTML}}.', { name, emailHTML }), that text could pull another variable of the same t() call into the output. Results with skipOnVariables: false, and values without placeholders, are unchanged. Compatibility note: a {{- var}} value whose placeholders were meant to be filled from the same t() call now keeps them literally; skipOnVariables: false restores the old behavior. Thanks @nk-batman21 (#2455, reported in #1595).fix: with the default skipOnVariables: true, a {{placeholder}} inside an interpolated value now stays literal also when the same placeholder appears l
skipOnVariables: true, a {{placeholder}} inside an interpolated value now stays literal also when the same placeholder appears later in the translation. Each value was written with String.replace, which replaces the first copy of the placeholder text, and that could be the copy inside an earlier value: t('{{name}} has {{count}} items', { name: '{{count}}', count: 5 }) returned '5 has {{count}} items' instead of '{{count}} has 5 items'. The value is now written at the position of the matched placeholder. Results with skipOnVariables: false are unchanged. Thanks @nk-batman21 (#2454, reported in #1595).useRawValueToEscape: true, a non-string value in an unescaped {{- var}} placeholder or with escapeValue: false no longer throws val.replace is not a function; it is converted to a string like any other value.fix(types): with the selector API, a plural key now requires count also when the call passes an explicit ns. t(($) => $.item) already failed without c
count also when the call passes an explicit ns. t(($) => $.item) already failed without count, but t(($) => $.item, { ns: 'items' }) compiled, although at runtime it looks up item instead of item_one / item_other and returns the key. It now fails the same way, also with ordinal: true, defaultValue, an ns array, a key prefix and i18n.t. Calls with count, context, returnObjects: true and arrays of selectors, as well as return types, are unchanged. Thanks @nyarthan (#2452).fix(types): on TypeScript 7, a t() call with a missing, misspelled or wrongly typed option now reports that option again (Property 'album' is missing,
t() call with a missing, misspelled or wrongly typed option now reports that option again (Property 'album' is missing, Type 'string' is not assignable to type 'number'), as TypeScript 5 and 6 do. TypeScript 7 elaborated the error against the default-value signature instead and ended in '{ count: 3; albm: "Summer"; }' is not assignable to type 'string': on a failed call TypeScript explains the last of the equally matching signatures, and TypeScript 7 sorts the 3-element [key, defaultValue, options?] last. It is now written as two signatures, [key, defaultValue] and [key, defaultValue, options]. This affects the default key checks with i18next {{name}} messages as well as parseInterpolation: 'icu' and 'mf2'. Which calls compile, their return types and the error positions are unchanged on TypeScript 5.9, 6 and 7.perf(types): type-checking t() calls against a large namespace is no longer quadratic in the number of keys. TypeScript does not cache keyof of an obj
t() calls against a large namespace is no longer quadratic in the number of keys. TypeScript does not cache keyof of an object type, and the types rebuilt the union of all keys of a namespace once per key while building the key union, and again in every t() call to look up the return type. Both now use a cached key union, and a literal key is looked up directly instead of being intersected with every key. With 5,000 keys in one namespace and one call per key, the check time went from 14.8s to 1.1s (TypeScript 6); with 1,000 keys from 0.75s to 0.27s. Keys, return types and errors are unchanged.enableSelector: true / 'strict') with context is no longer quadratic in the size of an object. To decide which keys a context keeps, the types scanned all keys of the object once for every key, also when TypeScript checks the selector with context widened to string. With 1,000 keys plus one context variant each, a namespace took 18.7s and failed with "Type instantiation is excessively deep and possibly infinite" (TS2589); 2,500 and more ran out of memory. The context variants of an object are now collected once, in one pass over its keys: 1,000 keys check in 0.69s, 5,000 in 3.1s. Long keys (whole sentences with keySeparator: false) work as before. Selected values and errors are unchanged.feat(types): parseInterpolation: 'icu' and parseInterpolation: 'mf2' type t() options from the message's ICU MessageFormat arguments (i18next-icu) or
parseInterpolation: 'icu' and parseInterpolation: 'mf2' type t() options from the message's ICU MessageFormat arguments (i18next-icu) or MessageFormat 2 variables (i18next-mf2), so ICU and MF2 users no longer need parseInterpolation: false and lose argument checking. Missing, misspelled and wrongly typed arguments fail, and so does leaving out the options for a message with arguments (t('greeting')); that error names the missing arguments. Opt-in, default true is unchanged.
{name} takes string | number, {n, number}, plural and selectordinal take number, {d, date} and {t, time} take Date, select takes its case keys or any string (for other), and arguments nested in cases are required too. # and tags are not arguments, apostrophe quoting is read like intl-messageformat does.{$name} takes string | number, a variable annotated with :number, :integer, :currency, :percent or :unit (inline or through .input / .local) takes number, :datetime, :date and :time take Date, :string takes string, option and markup variables (minimumFractionDigits=$digits, {#link href=$url}) are required too, .local variables are not arguments, and |quoted literals| and \{ escapes are skipped.interpolationFormatTypeMap overrides a type by ICU format or MF2 function name, e.g. date: Date | number or a custom uppercase: string.t(), getFixedT(), i18n.t, key prefixes, namespaces, the selector API and react-i18next's Trans values. Messages need literal types, as the resources file from i18next-cli's types command has them.false (TypeScript 6), 0.5s instead of 0.26s with TypeScript 7. Messages that no call uses cost nothing.Property 'name' is missing) instead of '{ nmae: string }' is not assignable to type 'string' from the default-value overload.perf: cloneInstance() no longer inherits preload. loadResources() adds every preload language to each load, and clones copied preload from the parent,
cloneInstance() no longer inherits preload. loadResources() adds every preload language to each load, and clones copied preload from the parent, so a clone's init() and every changeLanguage() walked all preloaded languages × all namespaces through queueLoad() / hasResourceBundle(), although the parent had already loaded them into the shared store. With i18next-http-middleware (one clone + changeLanguage() per request), 25 preloaded languages and 20 namespaces, that was most of the per-request CPU: the reproduction from the issue went from ~90 µs to ~10 µs per request, the same as with a single language. A clone now only loads what it uses itself: its changeLanguage() no longer waits for parent preload languages that are still loading (the parent's own init() still does), and clone.loadNamespaces() loads the new namespace for the clone's language and fallbacks instead of every preloaded language. clone.loadLanguages() works as before, the parent instance is unchanged, and passing preload to cloneInstance() keeps the old behavior. Thanks @theMostCuriousHomunculus for the detailed report (#2451).fix: a fallback language whose formatted code is already in the hierarchy is no longer added a second time. toResolveHierarchy() checked the raw fallb
toResolveHierarchy() checked the raw fallbackLng value against the list, but the list holds formatted codes, so any fallback written differently from its formatted form slipped through: lng: 'de-CH' with fallbackLng: 'de-ch' gave languages ['de-CH', 'de', 'de-CH'], and the same happened with fallbackLng: 'EN' + cleanCode, lowerCaseLng, and Intl aliases (iw-IL → he-IL). Missing keys were looked up in the same language twice. Only exact duplicates are removed; the order is unchanged. Thanks @lprnmns (#2450).fix: hasLoadedNamespace(ns, { lng }) no longer stays false forever when the passed in lng is loaded under another code, or not at all. It checked the
hasLoadedNamespace(ns, { lng }) no longer stays false forever when the passed in lng is loaded under another code, or not at all. It checked the load state of the raw lng, but loadLanguages() stores a language under its resolved code (de-ch → de-CH, de-CH → de with load: 'languageOnly') and skips a lng outside supportedLngs entirely (only the fallback gets loaded), so that state never got set. react-i18next's useTranslation(ns, { lng }) then never became ready: with useSuspense it kept throwing an already resolved promise and React retried forever (100% CPU, SSR never finished), without it the load effect re-rendered in a loop. It now checks the code the language is actually loaded under, and for a lng outside supportedLngs only waits for the fallback, which is also what t() resolves to. Calls without lng and the precheck (react-i18next's bindI18n: 'languageChanging') are unchanged (react-i18next#1934).fix(security): the nesting regexp no longer backtracks exponentially (ReDoS) on an unclosed $t(. Its repeated group had overlapping alternatives ([^()
$t(. Its repeated group had overlapping alternatives ([^()"']+ inside (?:...)*?, and inside parentheses [^()] also matched quotes), so a string containing $t( without a closing ) made the engine try every way to split the text: about 2x the runtime per extra character, and a ~25 character value hung t() for minutes. With the default config this was reachable through any interpolated value (t('greet', { name: '$t(aaaaaaaaaaaaaaaaaaaaaaaa' })): escaping does not touch $, t or (, and the skipOnVariables check runs the regexp on the interpolated result, so nest: false did not help either. Every alternative now starts with a different character (plain char, ", ' or (), so there is only one way to match and the cost is linear. Quoted strings and one level of parentheses in nesting options keep working (#2336). The only difference: a lone " or ' inside unquoted parentheses within $t(...) is no longer matched. Affects 25.3.3 to 26.4.3. Thanks to Anisetti Chaitanya Eshwar Prasad for the responsible disclosure.nest() now resolves $t(...) in a single pass and no longer nests text that came out of a resolved value. Every nested lookup reset the shared nesting regexp, so the loop started over from the beginning of the string after each match. That had two effects. First, a $t(...) inside a variable that the nested lookup deliberately kept literal (default skipOnVariables: true) was resolved anyway by the outer loop: with outer: 'A $t(inner) B' and inner: 'Hi {{name}}', t('outer', { name: '$t(secret)' }) rendered the secret translation. It now stays A Hi $t(secret) B, the same as without the outer nesting; with skipOnVariables: false it is still resolved. Second, the cost was quadratic when an unclosed $t( preceded many nestings, which matters when an app passes untrusted input as the key itself (t(userInput)): 20,000 nestings took ~1.4 s, now ~25 ms. The resolved value is now sliced into the result instead of going through String.replace, so $&, $`, $' and $$ stay literal as before (26.4.2).perf: ResourceStore.hasLanguageSomeTranslations() no longer enumerates every key of a large bundle on each call. It ran Object.keys() on the whole bun
ResourceStore.hasLanguageSomeTranslations() no longer enumerates every key of a large bundle on each call. It ran Object.keys() on the whole bundle just to learn whether it had at least one key, and init() / changeLanguage() reach it three times per instance (once while picking the language, twice via setResolvedLanguage()). With large flat bundles and one i18next instance per SSR request reusing the same resources, that showed up as measurable CPU work before any t() call. Bundle objects already found non-empty are now remembered in a WeakSet shared across instances, so later checks are O(1): 2,000 inits with a 6,800-key bundle went from ~750 ms to ~20 ms, the same as a one-key bundle. Only the non-empty result is cached. No API removes single keys from a bundle, so a non-empty bundle stays non-empty, and empty bundles are re-checked every time, so keys added later (backend loads, addResource, addResourceBundle, direct or silent changes) count right away. The only edge case: a bundle emptied by hand with delete on every key while it is still in the store keeps counting as having translations; use removeResourceBundle() for that. Thanks @dmchoi77 for the detailed report (#2449).fix: $&, ` $ `, $' and $$ inside a nested value ($t(key)) now stay literal. nest() handed the resolved value straight to String.replace as the replace
$&, $`, $' and $$ inside a nested value ($t(key)) now stay literal. nest() handed the resolved value straight to String.replace as the replacement argument, so those sequences were read as replacement patterns: $& re-inserted the $t(...) match, $` / $' inserted the text before / after it, and $$ collapsed to $. Through t() the $& case was worse than a wrong string: the nested lookup resets the shared nesting regexp, so the re-inserted $t(...) was matched again on every pass and t() never returned — also under the default escapeValue: true when the value arrives via a variable forwarded through nesting options ($t(key, { "name": "{{name}}" }) with a name containing $&). The value is now $-escaped at the String.replace call, the same guard interpolate() already has, and a non-string value returned by a formatter in the nesting chain ($t(key, myFormat)) is stringified before that. Nested values are still not HTML-escaped (#854). Thanks @mahirhir (#2447).fix(types): the selector-form keyPrefix overload of getFixedT() is now available under enableSelector: 'strict'. Its constraint was gated on true | 'o
keyPrefix overload of getFixedT() is now available under enableSelector: 'strict'. Its constraint was gated on true | 'optimize' only, so under 'strict' it collapsed to never, the overload dropped out, and the returned t silently lost its keyPrefix scope (t(($) => $.deep) failed with Property 'deep' does not exist on type '{}'). The same call already typechecked under true and 'optimize'. Thanks @hovelopin (#2446).…which resolves all open npm audit findings (0 vulnerabilities) and should close the dependabot alerts on the lockfile.
toResolveHierarchy results per (code, fallbackCode) pair. The hierarchy resolver runs on every t() call and calls Intl.getCanonicalLocales multiple times, which showed up prominently when profiling render-heavy UIs (e.g. virtualized data grids); with the cache the per-call cost drops from ~886 ns to ~41 ns. The cache is invalidated automatically when options.fallbackLng changes (reassignment or in-place array mutation); if you mutate other resolution-relevant options at runtime (load, lowerCaseLng, cleanCode, nonExplicitSupportedLngs), call i18next.services.languageUtils.clearCache() afterwards. Function-valued fallbackLng and per-call array/object fallbackLng options are never cached, so dynamic fallbacks keep working as before. Thanks @equaterina (#2444).@rollup/plugin-babel supports 8, eslint on 9.x for neostandard). Removed the unused coveralls package (CI uses the Coveralls GitHub Action) and replaced sinon with nise + vitest.spyOn in the v1 compatibility tests, which resolves all open npm audit findings (0 vulnerabilities) and should close the dependabot alerts on the lockfile.fix: allow TypeScript 7 in the optional typescript peer dependency range (^5 || ^6 || ^7). With typescript@7.0.2 in a project, npm install failed with
typescript peer dependency range (^5 || ^6 || ^7). With typescript@7.0.2 in a project, npm install failed with an ERESOLVE peer conflict. The published types are TS7-compatible as-is: every test/typescript suite produces identical results under 6.0 and 7.0.2. Reported in react-i18next#1927, thanks @andikapradanaarif.fix: $t() nesting options blocks that span multiple lines are now parsed. nest() decided where the nested key ends by testing match[1] with /{.*}/, wh
$t() nesting options blocks that span multiple lines are now parsed. nest() decided where the nested key ends by testing match[1] with /{.*}/, whose dot does not cross line breaks — so a $t(key, { ... }) options object containing a newline was treated as having no options, mis-split as formatters, and the nested lookup ran without its options (placeholders stayed unresolved). The nesting regexp itself already matches newlines inside $t(...); adding the s (dotAll) flag makes multiline options behave like the single-line form. Thanks @spokodev (#2440).getUsedParamsDetails (the returnDetails: true path) no longer mutates the passed replace object. It wrote count straight onto options.replace so the returned usedParams would include it — a caller reusing one replace object across t() calls then carried a stale count into later interpolations (e.g. a previous call's count: 5 rendered instead of the current call's value). The details are now built from a copy; usedParams still includes count. Thanks @spokodev (#2441).skipOnVariables: true + escapeValue: true, a {{placeholder}} carried inside an interpolated value now stays literal even when the value contains escapable characters. The skip logic advanced the regex lastIndex by the raw value length, but the escaped text written into the string is longer, so lastIndex landed inside the inserted value and a trailing {{placeholder}} in it got interpolated — leaking another in-scope variable that should have stayed literal (values without escapable characters were already skipped correctly). The advance now uses the escaped length that is actually written, and the regex-safe $-doubling is applied only at the String.replace call so it can't distort the length arithmetic. Thanks @spokodev (#2442).…backend/integration does this. Distinct from CVE-2026-48713 / CVE-2026-48714 (different packages, setPath mechanism). Thanks to zx (Jace) for the resp…
deepExtend (used by addResourceBundle(..., deep, overwrite)) no longer recurses into inherited properties. It checked key existence with the in operator, which walks the prototype chain, so a source key matching an inherited built-in (e.g. hasOwnProperty, toString) caused recursion into the shared Object.prototype function and, with overwrite: true, could overwrite e.g. Object.prototype.hasOwnProperty.call with a non-callable value — corrupting a shared built-in process-wide (DoS). Existence is now checked with Object.prototype.hasOwnProperty.call, so such keys are copied as plain own data instead. This complements the existing __proto__/constructor guard and is also strictly more correct for an own-property merge. Only affects applications that pass attacker-controlled data with deep: true and overwrite: true; no standard backend/integration does this. Distinct from CVE-2026-48713 / CVE-2026-48714 (different packages, setPath mechanism). Thanks to zx (Jace) for the responsible disclosure.deepExtend (used by addResourceBundle(..., deep, overwrite)) no longer recurses into inherited properties. It checked key existence with the in operator, which walks the prototype chain, so a source key matching an inherited built-in (e.g. hasOwnProperty, toString) caused recursion into the shared Object.prototype function and, with overwrite: true, could overwrite e.g. Object.prototype.hasOwnProperty.call with a non-callable value — corrupting a shared built-in process-wide (DoS). Existence is now checked with Object.prototype.hasOwnProperty.call, so such keys are copied as plain own data instead. This complements the existing __proto__/constructor guard and is also strictly more correct for an own-property merge. Only affects applications that pass attacker-controlled data with deep: true and overwrite: true; no standard backend/integration does this. Distinct from CVE-2026-48713 / CVE-2026-48714 (different packages, setPath mechanism). See advisory GHSA-6jcc-5g8w-32mx, CVSS 5.9 (CVSS:3.1/AV:N/AC:H/PR:L/UI:N/S:U/C:N/I:L/A:H). Thanks to zx (Jace) @manus-use for the responsible disclosure.fix(types): selector t($ => $.arr, { returnObjects: true, context }) on a JSON array of heterogeneous objects now preserves each element's full shape
t($ => $.arr, { returnObjects: true, context }) on a JSON array of heterogeneous objects now preserves each element's full shape (e.g. { transKey1: string; transKey2: string }[]) instead of collapsing to a union of partial element types. Two type-level causes: (1) FilterKeys evaluated the whole array element type at once, so keyof (A | B) only saw the keys common to every element — it now distributes over the object union and filters each element independently; (2) when TypeScript merges mismatched array element types it injects phantom optional undefined keys (e.g. transKey1_withContext?: undefined on elements that don't define it), which the context-detection helpers mistook for real context variants — they now skip keys typed as undefined. Also adds a dedicated context + returnObjects: true selector overload using const Fn + ReturnType<Fn>, so Target is no longer collapsed to unknown via ApplyTarget. Resolves Problem 1 of #2398 (Problem 2 was already fixed on master). Thanks @sauravgupta-dotcom (#2438). Fixes #2398.fix: chained formatters with a parenthesised option that contains the format separator (e.g. join(separator: ', ')) now work at any position in the ch
join(separator: ', ')) now work at any position in the chain, not just first. Previously the comma-in-parens reassembly only repaired formats[0], so {{v, uppercase, join(separator: ', ')}} split the join(...) option on the inner comma and never rejoined it, producing corrupt output. Replaced the first-position-only repair with a position-independent pass that re-joins fragments until each open paren closes. Thanks @spokodev (#2437).fix(types): t() with a keyPrefix no longer pollutes its return type with sibling keys' values. A regression in 26.3.0 — the [Res] extends [never] guar
t() with a keyPrefix no longer pollutes its return type with sibling keys' values. A regression in 26.3.0 — the [Res] extends [never] guards added to KeysBuilderWithReturnObjects / KeysBuilderWithoutReturnObjects turned the builders into deferred conditional types, so KeyPrefix<Ns> stopped resolving to a literal union and keyPrefix inference widened to the whole namespace. Symptom: useTranslation(ns, { keyPrefix: 'a.b' }) then t('title') would resolve to '<a.b>.title' | '<other.path>.title' | ... instead of just the scoped value. Affected every react-i18next user using keyPrefix. Restored to the eager 26.2.0 form. The same-namespace conflict handling from #2434 still works via _DropConflictKeys at the merge layer (in options.d.ts). Thanks @aaronrosenthal (#2436).feat(types): introduce ResourceNamespaceMap — a separate mergeable augmentation surface for namespace resource types, designed for monorepos where mul
ResourceNamespaceMap — a separate mergeable augmentation surface for namespace resource types, designed for monorepos where multiple packages each want to contribute their own namespaces. Previously, every package had to coordinate on a single CustomTypeOptions.resources declaration (or fall back to typing dependency namespaces as any) because resources is a single property of an interface and TypeScript reports TS2717 when two declarations of the same property disagree. The new interface merges naturally across declare module 'i18next' blocks, so each package can ship its own i18next.d.ts independently. Per-property merge handles same-namespace contributions from multiple packages, and same-key/different-literal conflicts are silently dropped to avoid poisoning t() overload resolution. Fully backwards-compatible — existing CustomTypeOptions.resources augmentations continue to work, and both surfaces can coexist. Scalar options (defaultNS, returnNull, enableSelector, etc.) still belong on CustomTypeOptions. Thanks @sh3xu (#2434). Fixes #2409.feat(types): new parseInterpolation TypeOption (default true). When set to false in CustomTypeOptions, the type-level extractor stops parsing translat
parseInterpolation TypeOption (default true). When set to false in CustomTypeOptions, the type-level extractor stops parsing translation strings for {{variable}} patterns. Required by i18next-icu users — the default extractor mistakes ICU MessageFormat nested-brace plurals like {count, plural, one {{count} row} other {{count} rows}} for an interpolation block and demands a phantom variable name. The flag is type-only; runtime interpolation is governed by InterpolationOptions and is unaffected. Fixes i18next-icu#85.enableSelector on InitOptions so i18next.init({ enableSelector: 'strict' }) typechecks without a module augmentation. The runtime already reads opts?.enableSelector from init options; this lands the matching type declaration next to the other selector-resolution knobs. Accepts false | true | 'optimize' | 'strict'. Thanks @Faithfinder (#2431)feat: enableSelector: 'strict' (TypeOptions + runtime option). Opt-in mode that drops the flattened-primary form from NsResource at the type level — e
enableSelector: 'strict' (TypeOptions + runtime option). Opt-in mode that drops the flattened-primary form from NsResource at the type level — every namespace (primary included) is exposed only under its own key on $, uniformly across single- and multi-ns hooks. At runtime, a leading selector path segment matching the scope's namespace list is always rewritten as a namespace prefix, including the primary. Eliminates the silent-miss surface area where t($ => $.primary.foo) typechecks but doesn't resolve under the default mode (see #2429). Backward-compatible: default enableSelector: false | true | 'optimize' behavior is unchanged. Note: strict mode is incompatible with the #2405 pattern (keys whose names match sibling namespaces) — those users should stay on default mode.feat: getFixedT accepts a fourth optional fixedOpts argument carrying scopeNs — the full namespace list the bound t was created for. The selector API
getFixedT accepts a fourth optional fixedOpts argument carrying scopeNs — the full namespace list the bound t was created for. The selector API uses scopeNs to detect when a path's first segment is a namespace prefix, without changing resolution scope. Resolution still uses the bound ns (a single primary string in the typical react-i18next setup), so plain t('key') lookups stay isolated to the primary namespace exactly as before — only t($ => $.secondaryNs.foo) selectors now route correctly under useTranslation([nsA, nsB]). Fixes the runtime side of #2429 for the react-i18next default-nsMode case. The 4th argument is opt-in: existing 3-arg getFixedT(lng, ns, keyPrefix) callers see no behavior change.fix(types): unformatted interpolation values are now typed as string | number (was string). i18next stringifies values at runtime, so requiring caller
string | number (was string). i18next stringifies values at runtime, so requiring callers to wrap numbers in String(...) for plain {{var}} placeholders was unnecessary friction — and could mask the real problem when a non-string value was passed alongside multiple interpolation slots (the t() overload resolution would fall through to the 3-arg form and report a confusing "not assignable to string" error against the options object). Typed format specifiers like {{x, number}}, {{x, currency}}, {{x, datetime}}, etc. keep their precise types; this only relaxes the no-format default. The count variable remains number-onlyfix(types): restore the pre-v25.10.4 ExistsFunction shape so plain arrow functions can again be assigned to ExistsFunction-typed variables (TypeScript
ExistsFunction shape so plain arrow functions can again be assigned to ExistsFunction-typed variables (TypeScript cannot infer type predicates through multi-overload assignment). Direct i18next.exists(key) calls still narrow key to SelectorKey — the predicate is now declared inline on i18n.exists. Custom wrappers that want the narrowing can type themselves as typeof i18next.exists 2425fix: when a plural lookup misses, the missingKey debug log now shows the actual plural-resolved key (e.g. foo.bar_many for Polish count: 14) instead o
missingKey debug log now shows the actual plural-resolved key (e.g. foo.bar_many for Polish count: 14) instead of the base key — making it obvious which plural category was expected and missing 2423@babel/runtime runtime dependency. The build no longer generates any @babel/runtime imports, so the package is unused by consumers. Rollup now uses babelHelpers: 'bundled' so any helpers that are ever needed in the future will be inlined rather than imported externally 2424dist/esm/i18next.bundled.js. It was byte-identical to dist/esm/i18next.js because no helpers were being imported 2424Security release — all issues found via an internal audit. GHSA advisory filed after release.
Security release — all issues found via an internal audit. GHSA advisory filed after release.
escapeValue: false with interpolated variables inside a $t(key, { ... "{{var}}" ... }) nesting-options block. In that narrow combination, attacker-controlled string values containing " can break out of the JSON options literal and inject additional nesting options (e.g. redirect lng/ns). The default escapeValue: true configuration is unaffected because HTML-escaping neutralises the quote before JSON.parse. See the security docs for mitigation guidance (GHSA-TBD)regexEscape to unescapePrefix / unescapeSuffix on par with the other interpolation delimiters. Prevents ReDoS (catastrophic-backtracking) when a misconfigured delimiter contains regex metacharacters, and fixes silent breakage of the {{- var}} syntax when the delimiter contains characters like (, [, ..env* and *.pem/*.key files in .gitignorefix: cloneInstance().changeLanguage() no longer fails to update language state when the target language is not yet loaded — a race between init()'s de
cloneInstance().changeLanguage() no longer fails to update language state when the target language is not yet loaded — a race between init()'s deferred load() and the user's changeLanguage() could overwrite isLanguageChangingTo, causing setLngProps to be skipped 2422fix(types): inline formatting options like {{price, currency(EUR)}} are now correctly resolved to their base format type (e.g. number for currency) in
{{price, currency(EUR)}} are now correctly resolved to their base format type (e.g. number for currency) instead of falling back to string 2378fix(types): addResourceBundle now accepts an optional 6th options parameter ({ silent?: boolean; skipCopy?: boolean }) matching the runtime API 2419
addResourceBundle now accepts an optional 6th options parameter ({ silent?: boolean; skipCopy?: boolean }) matching the runtime API 2419fix(types): t("key", {} as TOptions) no longer produces a type error — the context constraint now bypasses strict checking when context is unknown (e.
t("key", {} as TOptions) no longer produces a type error — the context constraint now bypasses strict checking when context is unknown (e.g. from TOptions) 2418fix: Formatter no longer crashes when alwaysFormat is true and no format specifier is present (format is undefined)
alwaysFormat is true and no format specifier is present (format is undefined)undefined/null values as-is instead of producing NaN when the value is missingRemove deprecated `initImmediate` option — the backward-compatibility mapping from initImmediate to initAsync (introduced in v24) has been removed. Us…
This is a major breaking release:
initImmediate option — the backward-compatibility mapping from initImmediate to initAsync (introduced in v24) has been removed. Use initAsync instead.interpolation.format function — the old monolithic format function (interpolation: { format: (value, format, lng) => ... }) is no longer supported. The built-in Formatter (or a custom Formatter module via .use()) is now always used. Migrate to the new formatting approach using i18next.services.formatter.add() or .addCached() for custom formatters.showSupportNotice option and all related internal suppression logic (globalThis.__i18next_supportNoticeShown, I18NEXT_NO_SUPPORT_NOTICE env var). See our blog post for the full story.simplifyPluralSuffix option — this option was unused by the core PluralResolver (which relies entirely on Intl.PluralRules). It only had an effect in the old v1/v2/v3 compatibility layer. The v4 test compatibility layer now defaults to true internally.@babel/polyfill from devDependencies.indexOf() > -1 / indexOf() < 0 with .includes() (~40+ occurrences)indexOf() === 0 with .startsWith() where appropriatevar with const, '' + object with String(object), .substring() with .slice().apply(observer, [event, ...args]) with direct call observer(event, ...args).call(this, ...) in BackendConnector retry logicarray-callback-return in LanguageUtils getBestMatchFromCodeseslint-disable comments from source filesonce() method for one-time event subscriptionscheckedLoadedFor cache to Translator instance, preventing cross-instance state leakageBackendModule generic parameter naming inconsistency between CJS and ESM type definitionsonce() method to i18n and ResourceStore type interfacestest.projects configfeat: suppress support notice automatically in production environments (NODE_ENV=production)
NODE_ENV=production)feat(types): export SelectorParam helper type — a stable, readable alternative to Parameters >[0] for typing selector function props 2414
SelectorParam<Ns, KPrefix> helper type — a stable, readable alternative to Parameters<TFunction<Ns>>[0] for typing selector function props 2414fix(types): reorder TFunctionSelector overloads so Parameters resolves to the general selector signature instead of the branded SelectorKey type 2412
TFunctionSelector overloads so Parameters<TFunction> resolves to the general selector signature instead of the branded SelectorKey type 2412One column per quarter.