npm / i18next
i18next
What changed in i18next 25 to 26, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-18.
13 breaking4 security18 new APIs and options4 performance6 behavior and defaults3 tooling46 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initi18next 2653 changes
Breaking changes 11
Clones no longer inherit preload by default, avoiding redundant loading across preloaded languages and namespaces. Passing preload to cloneInstance() retains the old behavior.
nest() resolves $t(...) in a single pass, so text kept literal by skipOnVariables is no longer resolved by an outer loop; this also avoids quadratic work on unclosed input.
The package no longer emits this file because it was byte-identical to dist/esm/i18next.js.
The Formatter returns undefined and null values as-is instead of producing NaN when the value is missing.
The global suppression state for the console support notice is removed.
The environment variable for suppressing the console support notice is removed.
Custom formatters can be registered through the formatter service as part of the new formatting approach.
The deprecated compatibility mapping from initImmediate to initAsync is removed; use initAsync instead.
The legacy monolithic format function is no longer supported; use the built-in Formatter or a custom Formatter module.
The option for controlling the console support notice is removed along with the notice.
The unused option is removed; the v4 test compatibility layer now defaults to true internally.
Security 4
Warns when escapeValue: false is combined with interpolated variables inside a $t nesting-options block, where quotes in attacker-controlled values can inject additional nesting options.
Strips CR, LF, NUL, and other C0/C1 control characters from string log arguments to prevent log forging through user-controlled values.
Regex-escapes the delimiter to prevent ReDoS from regex metacharacters and avoid breaking the
{{- var}}syntax.Regex-escapes the delimiter to prevent ReDoS from regex metacharacters and avoid breaking the
{{- var}}syntax.
New APIs and options 10
Overrides the inferred type for an ICU format or MF2 function name, including custom functions.
Opting into ICU or MF2 parsing types t() options from message arguments, reporting missing, misspelled, and wrongly typed arguments, including when options are omitted.
Adds a mergeable augmentation surface for namespace resource types, allowing packages to contribute namespaces independently; same-key, different-literal conflicts are dropped to avoid poisoning t() overload resolution.
Exposes enableSelector on InitOptions so selector settings typecheck without a module augmentation; accepts false, true, 'optimize', or 'strict'.
Adds a CustomTypeOptions flag, defaulting to true, to disable type-level parsing of translation strings for {{variable}} patterns; runtime interpolation is unaffected.
Opt-in strict mode exposes every namespace only under its own key on $, and rewrites a leading selector path segment matching the scope's namespace list as a namespace prefix, including the primary.
A fourth optional fixedOpts argument carries scopeNs so selector paths with a namespace prefix route correctly under useTranslation([nsA, nsB]), without changing the bound resolution namespace.
The TypeScript signature now accepts an optional sixth options parameter, matching the runtime API.
Custom formatters can be registered through the formatter service using the cached registration method.
EventEmitter adds one-time event subscriptions, and the method is also added to the i18n and ResourceStore type interfaces.
Performance 4
Type-checking the selector API with context is no longer quadratic in object size; context variants are collected in one pass, avoiding excessive type instantiation and out-of-memory failures.
Type-checking t() calls against large namespaces is no longer quadratic; cached key unions and direct literal-key lookups reduce check time without changing keys, return types, or errors.
Non-empty bundle checks are cached across instances, making later checks O(1). Bundles emptied manually with delete remain counted as having translations; use removeResourceBundle() instead.
Caches hierarchy resolution results per (code, fallbackCode) pair to reduce per-call cost. If other resolution-relevant options change at runtime, call i18next.services.languageUtils.clearCache(); dynamic fallbacks remain uncached.
Behavior and default changes 1
Unformatted interpolation values are now typed as string | number; formatted values retain their precise types, and count remains number-only.
Fixes and other changes 23
On TypeScript 7, failed t calls with missing, misspelled or wrongly typed options again report the relevant option error, matching TypeScript 5 and 6.
With default non-strict key checks, missing or misspelled interpolation variables in an options object now report the missing variable instead of a misleading default-value overload error.
Loads the new namespace for the clone's language and fallbacks instead of every preloaded language.
Formatted fallback language codes already in the hierarchy are no longer added a second time, preventing duplicate language lookups while preserving order.
Checks the resolved language code actually loaded, or waits for the fallback when lng is outside supportedLngs, preventing readiness loops.
Nested values containing
$&,$,$'or$$` now stay literal, and non-string values returned by formatters in the nesting chain are stringified.The selector-form keyPrefix overload is now available when enableSelector is 'strict', preserving the returned t function's keyPrefix scope.
The optional TypeScript peer dependency range now allows TypeScript 7, avoiding an npm install peer conflict.
The returnDetails path no longer mutates the passed replace object; returned usedParams still includes count.
With skipOnVariables: true and escapeValue: true, placeholders inside interpolated values containing escapable characters now stay literal.
Multiline options objects in nested $t() calls are now parsed correctly, so nested lookups receive their options and resolve placeholders.
With deep merging and overwrite enabled, inherited built-in properties are now copied as plain own data instead of being recursed into, preventing shared built-ins from being corrupted.
Selector calls with context and returnObjects: true now preserve the full shape of heterogeneous JSON array elements instead of collapsing their types.
Parenthesised formatter options containing the format separator now work at any position in a chain, preventing inner commas from corrupting output.
Using keyPrefix no longer widens t()'s return type to include values from sibling keys in the namespace.
Restores the pre-v25.10.4 type shape so plain arrow functions can be assigned to ExistsFunction-typed variables; direct i18next.exists calls still narrow keys, and custom wrappers can use typeof i18next.exists for narrowing.
When a plural lookup misses, the debug log shows the plural-resolved key instead of the base key, making the missing plural category clear.
Calling changeLanguage() on a cloneInstance() now updates language state when the target language is not yet loaded, avoiding a race that could skip setLngProps.
Inline formatting options now resolve to their base format type, such as number for currency, instead of falling back to string.
t("key", {} as TOptions) no longer produces a type error when context is unknown, because the context constraint bypasses strict checking.
The Formatter no longer crashes when alwaysFormat is true and no format specifier is present.
The generic parameter naming inconsistency between CJS and ESM type definitions is fixed.
The cache moves from module scope to the Translator instance, preventing cross-instance state leakage.
i18next 2541 changes
Breaking changes 2
When a key resolves to plural forms, the selector API now enforces
{ count: number }.getCleanedCode now replaces all underscores.
New APIs and options 8
Exports a stable, readable helper type for typing selector function props.
The support notice check also checks the I18NEXT_NO_SUPPORT_NOTICE environment variable.
Allows custom formatters to be typed via CustomTypeOptions.
Supports selector syntax in getFixedT and per-call options.
The selector API now accepts an array of selector functions, analogous to an array of keys.
An option can suppress the support message.
Type definitions were added for the transDefaultProps option in react-i18next.
Exports the InterpolationMap type for use by developers.
Behavior and default changes 5
The support notice is suppressed automatically when NODE_ENV=production.
Selector functions used as keyPrefix now provide full type-safe key narrowing, scoping the returned t function to the prefix subtree.
The i18nKey prop accepts SelectorKey values, allowing selector keys to be used with Trans.
The selector callback is constrained against resource definitions to catch invalid keys at compile time; optional ns and keyPrefix options support non-default namespace and prefix contexts.
Returns a branded SelectorKey type that t() accepts directly, enabling pre-computed and reusable translation keys.
Tooling 3
Type definitions now support TypeScript 6.
TypeScript 6 is supported, addressing the cited react-i18next issue.
Interpolation values are automatically typed from built-in format specifiers, such as number for
numberand Date fordatetime.
Fixes and other changes 23
Reordered overloads so Parameters<TFunction> resolves to the general selector signature instead of the branded SelectorKey type.
FilterKeys now excludes base keys with context variants when the provided context matches none of those variants.
In selector mode, preserves non-context, non-plural leaf keys when context is provided, fixing incorrect type narrowing with returnObjects: true.
String unions with invalid members are now correctly detected as type errors when used as the context option.
The selector now resolves namespaces against the effective ns rather than the global init options.
Fixes namespace resolution for a single-string ns and the primary namespace in an array; only paths starting with a secondary namespace in a multi-namespace array are rewritten.
The TypeScript return type is now this instead of void, enabling proper method chaining.
Fixes the Selector API so it can resolve namespaces.
Reverts the fix for compatibility with moduleResolution bundler.
Guards against null matchedDoubleQuotes while parsing the nesting option.
Escapes nestingOptionsSeparator during nesting option parsing.
Adds the missing toJSON declaration to the types.
Avoids a ReferenceError crash when the Intl API is unavailable.
The return value type definition for getFixedT() was corrected to address an incomplete type definition.
Fixes compatibility with moduleResolution set to bundler.
Fixes crashes when a backend in the backends array has no name property.
Fixes Namespace inference for the selector ns option.
Fixes the fallback for TFunctionReturn.
Fixes interpolation breaking when an instance is cloned.
Fixes invalid overwriting of the default value for overloadTranslationOptionHandler.
A wrong TypeScript signature was removed.
Creates a new interpolator when interpolation options are passed in, addressing issue 2371.
Fixes createInstance not existing on an instance.