# What changed in i18next

> 94 changes in i18next 25 to 26 from its official release notes, upgrade guides and advisories: 13 breaking, 4 security, 18 new APIs and options. Each one cited. Sources checked 2026-10-18. HTML: https://unstale.sh/npm/i18next/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## i18next 26

### Breaking changes

- Clones no longer inherit preload by default, avoiding redundant loading across preloaded languages and namespaces. Passing preload to cloneInstance() retains the old behavior. (26.4.7) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.4.7)
- 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. (26.4.4) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.4.4)
- The package no longer emits this file because it was byte-identical to dist/esm/i18next.js. (26.0.7) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.7)
- The Formatter returns undefined and null values as-is instead of producing NaN when the value is missing. (26.0.1) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.1)
- The global suppression state for the console support notice is removed. (26.0.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.0)
- The environment variable for suppressing the console support notice is removed. (26.0.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.0)
- Custom formatters can be registered through the formatter service as part of the new formatting approach. (26.0.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.0)
- The deprecated compatibility mapping from initImmediate to initAsync is removed; use initAsync instead. (26.0.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.0)
- The legacy monolithic format function is no longer supported; use the built-in Formatter or a custom Formatter module. (26.0.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.0)
- The option for controlling the console support notice is removed along with the notice. (26.0.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.0)
- The unused option is removed; the v4 test compatibility layer now defaults to true internally. (26.0.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.0)

### Security

- 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. (26.0.6) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.6)
- Strips CR, LF, NUL, and other C0/C1 control characters from string log arguments to prevent log forging through user-controlled values. (26.0.6) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.6)
- Regex-escapes the delimiter to prevent ReDoS from regex metacharacters and avoid breaking the `{{- var}}` syntax. (26.0.6) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.6)
- Regex-escapes the delimiter to prevent ReDoS from regex metacharacters and avoid breaking the `{{- var}}` syntax. (26.0.6) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.6)

### New APIs and options

- Overrides the inferred type for an ICU format or MF2 function name, including custom functions. (26.5.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.5.0)
- Opting into ICU or MF2 parsing types t() options from message arguments, reporting missing, misspelled, and wrongly typed arguments, including when options are omitted. (26.5.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.5.0)
- 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. (26.3.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.3.0)
- Exposes enableSelector on InitOptions so selector settings typecheck without a module augmentation; accepts false, true, 'optimize', or 'strict'. (26.2.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.2.0)
- Adds a CustomTypeOptions flag, defaulting to true, to disable type-level parsing of translation strings for {{variable}} patterns; runtime interpolation is unaffected. (26.2.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.2.0)
- 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. (26.1.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.1.0)
- 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. (26.0.10) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.10)
- The TypeScript signature now accepts an optional sixth options parameter, matching the runtime API. (26.0.3) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.3)
- Custom formatters can be registered through the formatter service using the cached registration method. (26.0.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.0)
- EventEmitter adds one-time event subscriptions, and the method is also added to the i18n and ResourceStore type interfaces. (26.0.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.0)

### Performance

- 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. (26.5.1) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.5.1)
- 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. (26.5.1) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.5.1)
- 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. (26.4.3) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.4.3)
- 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. (26.4.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.4.0)

### Behavior and default changes

- Unformatted interpolation values are now typed as string | number; formatted values retain their precise types, and count remains number-only. (26.0.9) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.9)

### Fixes and other changes

- On TypeScript 7, failed t calls with missing, misspelled or wrongly typed options again report the relevant option error, matching TypeScript 5 and 6. (26.5.2) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.5.2)
- 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. (26.5.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.5.0)
- Loads the new namespace for the clone's language and fallbacks instead of every preloaded language. (26.4.7) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.4.7)
- Formatted fallback language codes already in the hierarchy are no longer added a second time, preventing duplicate language lookups while preserving order. (26.4.6) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.4.6)
- Checks the resolved language code actually loaded, or waits for the fallback when lng is outside supportedLngs, preventing readiness loops. (26.4.5) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.4.5)
- Nested values containing `$&`, `$``, `$'` or `$$` now stay literal, and non-string values returned by formatters in the nesting chain are stringified. (26.4.2) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.4.2)
- The selector-form keyPrefix overload is now available when enableSelector is 'strict', preserving the returned t function's keyPrefix scope. (26.4.1) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.4.1)
- The optional TypeScript peer dependency range now allows TypeScript 7, avoiding an npm install peer conflict. (26.3.6) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.3.6)
- The returnDetails path no longer mutates the passed replace object; returned usedParams still includes count. (26.3.5) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.3.5)
- With skipOnVariables: true and escapeValue: true, placeholders inside interpolated values containing escapable characters now stay literal. (26.3.5) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.3.5)
- Multiline options objects in nested $t() calls are now parsed correctly, so nested lookups receive their options and resolve placeholders. (26.3.5) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.3.5)
- 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. (26.3.4) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.3.4)
- Selector calls with context and returnObjects: true now preserve the full shape of heterogeneous JSON array elements instead of collapsing their types. (26.3.3) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.3.3)
- Parenthesised formatter options containing the format separator now work at any position in a chain, preventing inner commas from corrupting output. (26.3.2) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.3.2)
- Using keyPrefix no longer widens t()'s return type to include values from sibling keys in the namespace. (26.3.1) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.3.1)
- 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. (26.0.8) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.8)
- When a plural lookup misses, the debug log shows the plural-resolved key instead of the base key, making the missing plural category clear. (26.0.7) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.7)
- Calling changeLanguage() on a cloneInstance() now updates language state when the target language is not yet loaded, avoiding a race that could skip setLngProps. (26.0.5) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.5)
- Inline formatting options now resolve to their base format type, such as number for currency, instead of falling back to string. (26.0.4) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.4)
- t("key", {} as TOptions) no longer produces a type error when context is unknown, because the context constraint bypasses strict checking. (26.0.2) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.2)
- The Formatter no longer crashes when alwaysFormat is true and no format specifier is present. (26.0.1) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.1)
- The generic parameter naming inconsistency between CJS and ESM type definitions is fixed. (26.0.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.0)
- The cache moves from module scope to the Translator instance, preventing cross-instance state leakage. (26.0.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v26.0.0)

## i18next 25

### Breaking changes

- When a key resolves to plural forms, the selector API now enforces `{ count: number }`. (25.9.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.9.0)
- getCleanedCode now replaces all underscores. (25.8.14) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.8.14)

### New APIs and options

- Exports a stable, readable helper type for typing selector function props. (25.10.9) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.10.9)
- The support notice check also checks the I18NEXT_NO_SUPPORT_NOTICE environment variable. (25.10.3) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.10.3)
- Allows custom formatters to be typed via CustomTypeOptions. (25.10.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.10.0)
- Supports selector syntax in getFixedT and per-call options. (25.10.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.10.0)
- The selector API now accepts an array of selector functions, analogous to an array of keys. (25.8.18) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.8.18)
- An option can suppress the support message. (25.8.2) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.8.2)
- Type definitions were added for the transDefaultProps option in react-i18next. (25.7.3) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.7.3)
- Exports the InterpolationMap type for use by developers. (25.6.2) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.6.2)

### Behavior and default changes

- The support notice is suppressed automatically when NODE_ENV=production. (25.10.10) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.10.10)
- Selector functions used as keyPrefix now provide full type-safe key narrowing, scoping the returned t function to the prefix subtree. (25.10.5) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.10.5)
- The i18nKey prop accepts SelectorKey values, allowing selector keys to be used with Trans. (25.10.4) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.10.4)
- 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. (25.10.2) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.10.2)
- Returns a branded SelectorKey type that t() accepts directly, enabling pre-computed and reusable translation keys. (25.10.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.10.0)

### Tooling

- Type definitions now support TypeScript 6. (25.10.7) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.10.7)
- TypeScript 6 is supported, addressing the cited react-i18next issue. (25.10.6) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.10.6)
- Interpolation values are automatically typed from built-in format specifiers, such as number for `number` and Date for `datetime`. (25.10.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.10.0)

### Fixes and other changes

- Reordered overloads so Parameters<TFunction> resolves to the general selector signature instead of the branded SelectorKey type. (25.10.8) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.10.8)
- FilterKeys now excludes base keys with context variants when the provided context matches none of those variants. (25.10.1) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.10.1)
- In selector mode, preserves non-context, non-plural leaf keys when context is provided, fixing incorrect type narrowing with returnObjects: true. (25.10.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.10.0)
- String unions with invalid members are now correctly detected as type errors when used as the context option. (25.9.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.9.0)
- The selector now resolves namespaces against the effective ns rather than the global init options. (25.8.20) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.8.20)
- 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. (25.8.19) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.8.19)
- The TypeScript return type is now this instead of void, enabling proper method chaining. (25.8.16) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.8.16)
- Fixes the Selector API so it can resolve namespaces. (25.8.15) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.8.15)
- Reverts the fix for compatibility with moduleResolution bundler. (25.8.11) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.8.11)
- Guards against null matchedDoubleQuotes while parsing the nesting option. (25.8.10) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.8.10)
- Escapes nestingOptionsSeparator during nesting option parsing. (25.8.9) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.8.9)
- Adds the missing toJSON declaration to the types. (25.8.8) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.8.8)
- Avoids a ReferenceError crash when the Intl API is unavailable. (25.8.7) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.8.7)
- The return value type definition for getFixedT() was corrected to address an incomplete type definition. (25.8.6) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.8.6)
- Fixes compatibility with moduleResolution set to bundler. (25.8.5) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.8.5)
- Fixes crashes when a backend in the backends array has no name property. (25.8.4) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.8.4)
- Fixes Namespace inference for the selector ns option. (25.8.1) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.8.1)
- Fixes the fallback for TFunctionReturn. (25.8.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.8.0)
- Fixes interpolation breaking when an instance is cloned. (25.7.4) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.7.4)
- Fixes invalid overwriting of the default value for overloadTranslationOptionHandler. (25.7.2) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.7.2)
- A wrong TypeScript signature was removed. (25.7.1) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.7.1)
- Creates a new interpolator when interpolation options are passed in, addressing issue 2371. (25.7.0) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.7.0)
- Fixes createInstance not existing on an instance. (25.6.1) — [release notes](https://github.com/i18next/i18next/releases/tag/v25.6.1)