npm / react-i18next
react-i18next
What changed in react-i18next 16 to 17, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-19.
15 breaking1 security4 deprecations60 new APIs and options3 performance25 behavior and defaults3 tooling74 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initreact-i18next 17149 changes
Breaking changes 14
Explicit values now take precedence over interpolation.defaultVariables in IcuTrans and Trans, matching t().
The minimum i18next peer dependency is now >=26.0.1, affecting compatible versions used with react-i18next.
With the new context API, callers using translate.getWrappedInstance must call instance.getWrappedInstance().getWrappedInstance() instead.
Changing language no longer triggers Suspense by default; adding languageChanging to bindI18n restores the previous behavior.
The I18n render prop was renamed to NamespacesConsumer, which controls which namespaces should be consumed.
Translate HOC overrides must be set under the child react option in i18next init rather than at the top level.
Removed the react-context ponyfill; applications using React below 16.3.0 must polyfill react.createContext themselves.
The TypeScript type for the Trans component's prop is stricter.
HTML tags not included in transKeepBasicHtmlNodesFor are no longer replaced in translation strings.
Trans no longer adds a parent div by default; set react.defaultTransParent to configure a parent element.
Correctly preserves HTML tag names when children contain interpolations or mixed content; update translation files if you rely on auto-generated keys containing indexed tags.
Removed the option to set translateFuncName in the translate HOC.
Initial values are applied only in useSSR and withSSR on cloned i18next instances, not on serverside instances that are not clones.
The translate HOC was renamed to withNamespaces, which controls which namespaces should be loaded.
Deprecations 3
The Babel macro is deprecated in favour of using IcuTrans directly; it continues to work on Babel 7 and is not removed.
A development-only warning logged once appears before useTranslation suspends while translations load, naming a <Suspense> boundary or react.useSuspense: false as fixes.
The Resources type definition is deprecated in favor of CustomTypeOptions.
New APIs and options 54
Adds an entry point with types for using IcuTrans in React Server Components without creating a React context on load.
A TypeScript option was introduced to support React 18 types for the Trans component.
bindI18n, bindI18nStore, and useSuspense defaults can be overridden through useTranslation options or HOC props.
Configure bindI18n as false or as a string of events to control which i18next events trigger updates.
bindI18nStore, alongside bindI18n and useSuspense, can be overridden through useTranslation options or HOC props.
Added bindI18nStore event options so applications can listen to store changes.
Configure bindStore as false or as a string of events to control which store events trigger updates.
The Interpolate component accepts a className.
CustomTypeOptions was introduced for TypeScript configuration, and the Resources type definition was deprecated.
nsSeparator was added to CustomTypeOptions.
withTranslation accepts a forwardedRef prop from outside, independently of the withRef option.
The translate wrapper exposes getWrappedInstance().
Added hashTransKey for custom key generation when Trans has no key and the source value is not wanted as the key.
Added I18n as a render-props alternative to the translate HOC.
The translate HOC accepts an i18next instance via props, allowing developers to provide the instance directly.
Added I18nContext and its provider and consumer for React's new context API.
The i18n instance and defaults can be set with i18next.use(reactI18nextModule), making I18nextProvider obsolete.
Added I18nextProvider for passing an i18n instance through context.
This marker allows Trans to create the correct missing string for dynamically rendered lists.
I18nextProvider accepts initialI18nStore to support simpler server-side rendering.
I18nextProvider accepts initialLanguage to support simpler server-side rendering.
keyPrefix support was added to useTranslation and has type-safe support, including deep prefixes.
Added nsMode: 'fallback' to use namespaces passed to the translate HOC as fallbacks.
Added options.react.exposeNamespace to expose the namespace on data-i18next-options for editor consumption.
The Interpolate component can use raw HTML.
Added a Babel macro exporting Trans, Plural, and Select for using ICU-format components in JSX.
Added react.defaultTransParent to configure a parent element for Trans, including for backwards-compatible wrapping.
Added a configurable parent element for the Trans component.
Set react.useSuspense to false on i18next.init to avoid using Suspense.
Added reportNS to I18NextProvider to report used namespaces.
Universal apps and server-side rendering are supported.
Trans supports an option to unescape HTML.
An option lets developers change the name of the t function.
The Trans component accepts a context prop.
The Trans component accepts ns to override the namespace supplied by a render prop or HOC.
Added tOptions to Trans to support ICU.
TranslationProps includes the useSuspense option.
The Plural component in macros has a values field.
Added Trans for translating nested components, including interpolation, as one translatable string.
Added i18next.options.react.transEmptyNodeValue to set a default fallback value for empty nodes and allow the i18next fallback flow.
Added translate.setDefaults to override default translate HOC options, including translateFuncName.
Added the Translation render prop for use with hooks.
The translate HOC now passes down tReady so applications can show a placeholder while translations load instead of returning null.
A custom unescape function can be added.
Added the usePureComponent option.
useSSR adds namespaces to the i18next initialization options.
useSuspense can be enabled or disabled at hook or component level.
The hook accepts an i18n instance, allowing callers to wrap it with a useContext-enabled hook.
UseTranslationOptions includes the useSuspense configuration property.
The wait option delays initial rendering until translations are loaded.
Added a context-consuming HOC that adds i18n and t to component props without the extra options of withNamespaces.
The withTranslation HOC supports the keyPrefix option.
The HOC exposes the wrapped component as a WrappedComponent property.
The translate wrapper exposes a WrappedComponent property.
Performance 3
The ESM package metadata now declares sideEffects: false, allowing bundlers to remove unused exports and reduce bundle size.
No longer unsubscribes and resubscribes i18n listeners on every render, reducing churn for frequently re-rendering mounted components.
Redundant re-rendering in I18nextProvider is avoided.
Behavior and default changes 23
IcuTrans and IcuTransWithoutContext now infer the literal i18nKey, so props that depend on the key are checked against that key rather than all namespace keys.
With i18next's parseInterpolation set to 'icu' or 'mf2', values on IcuTrans and IcuTransWithoutContext are typed from the message of i18nKey; other settings retain Record<string, any>.
When enabled, the default unescape now converts and   to U+00A0, preserving no-break spacing in text.
The selector-form keyPrefix overload is now available when enableSelector is 'strict', so selector-based key prefixes no longer resolve to the legacy signature.
The Trans values prop now requires only interpolation variables for the specific i18nKey, rather than all variables in the namespace.
Namespace loading moves to did mount.
Non-React static properties are hoisted onto the wrapper.
Hooks bind reportNS to the i18n instance, making namespace reporting per request.
Trans supports named interpolation elements supplied as an object in the components prop, including self-closing tags.
Trans can interpolate self-closing tags supplied through the components prop.
Trans allows br, strong, and i tags in translations.
Trans parses before interpolating.
Trans uses count from the values object when supplied; otherwise it uses the prop.
The ICU Trans macro parses defaults as an alternative to children.
Trans allows p elements.
Interpolation values can be taken from content or from count and values props, and count is automatically replaced in the translation string.
Interpolated values no longer need extra pseudo tags in translation strings; existing strings with those tags continue to work.
Trans can be used without children and returns the translated string.
Translation now forwards the ready state.
Warnings for unmatched interpolation variables are conditional.
Translations are reloaded whenever the namespaces passed to useTranslation change.
withTranslation uses forwardRef.
withTranslation now forwards the ready state.
Tooling 2
TypeScript support for keyPrefix is type-safe, including deep key prefixes.
The context prop of Trans has TypeScript support.
Fixes and other changes 50
With useSuspense enabled, the hook checks the store after starting a namespace load and suspends only if the namespace is still missing, avoiding fallback flashes with synchronous backends.
With an inline selector keyPrefix, the cached t now keeps its identity while the resolved prefix stays the same, avoiding repeated effects and memo recalculations.
The cached t is no longer reused when the namespace or i18n instance changes on a mounted component.
Selector i18nKey values targeting a secondary namespace now resolve like t() when Trans receives a t with its own namespace and no explicit ns prop.
Empty paired component tags preserve a single valid React-element child supplied through a named component map, component array, or indexed JSX children, matching behavior for multiple children and self-closing tags.
The i18n object returned by useTranslation now refreshes when resolvedLanguage or languages changes, so components no longer receive a stale snapshot.
When i18nKey is not provided, IcuTrans now uses defaultTranslation as the key, preventing key-less ICU macro nodes from rendering an empty string.
The parser used by Trans fixes handling of literal < in text, multiline/CRLF attribute values, comments containing >, doctypes, and quote-aware brackets.
The development-mode check is guarded so runtimes without a process global stay silent instead of throwing.
The missing-i18next-instance warnings for useTranslation and Trans now explain props/context alternatives and duplicate react-i18next copies; the Trans warning points to initReactI18next.
The ns prop now accepts a single namespace from an array-typed Ns, allowing the described Trans usage to typecheck under TypeScript 7; the change also applies to TransSelectorProps and IcuTransWithoutContextProps.
The optional TypeScript peer dependency range now allows TypeScript 7, preventing an ERESOLVE peer conflict during npm install.
The Trans component now typechecks selector-function i18nKey values under enableSelector: 'strict'.
With multiple namespaces, selector calls using a secondary-namespace prefix now resolve correctly under the default nsMode; plain key lookups remain isolated to the primary namespace.
Indexed <N> placeholders nested inside a keep-tag are scoped to that tag’s original React children, correcting rendering while preserving the nodesToString format consumed by i18next-cli’s extractor.
Fixes child rendering when a kept HTML node wraps a non-keep React element.
Avoids the React warning that i18nIsDynamicList is not recognized on a DOM element.
Avoids passing an invalid prop to React.Fragment inside <Trans />.
Fixed cimode so it loads and becomes ready.
Passing i18n as a prop no longer triggers the required context type warning.
The provider supports passing defaultNS via a prop.
I18nextProvider supports the defaultNS prop.
useTranslation can replace the i18n instance in the provider.
Loaded namespaces are triggered only when the component is mounted.
Updating the ns prop on the I18n component now loads missing namespaces.
Support for nsMode values default and fallback was restored.
You can pass ready when i18next is not initialized yet if initialStore is set.
Added and removed i18next resource events are handled.
Trans children types explicitly support objects.
The components prop accepts const components.
Trans takes the namespace from the supplied t function.
Trans supports basic HTML nodes when checking arrays.
Trans supports nested components rendered from list.map, and i18nIsDynamicList produces a correct missing string.
Trans handles misleading overloaded empty elements in components.
Trans ignores null children.
Trans supports uppercase elements.
The Trans component correctly returns defaultValue.
The Trans component's TypeScript interface accepts React Native props.
The parent prop accepts ComponentType, and Trans accepts HTML props.
Trans accepts HTML props, and the parent prop type was fixed.
Trans correctly passes interpolation options supplied through the tOptions prop.
TypeScript definitions now make children optional in TransProps.
Basic HTML node support works with self-closing Trans components.
The React 15.2 update eliminates the Unknown Prop Warning.
Language changes trigger Suspense by listening to languageChanging; remove it from bindI18n to avoid suspending during a language change.
The translation function t is reset when the namespace changes.
The ready flag is false when the i18n instance has not been initialized.
The ready parameter is included in the Translation component's TypeScript definition.
The hook's return value can be destructured with object spread syntax.
Only pass forwardedRef to children if options.withRef is false.
react-i18next 1636 changes
Breaking changes 1
The peer dependency requirement is now >= 25.10.9 to provide type exports used by TransSelector.
Security 1
When a selector function cannot be resolved without an i18n instance, it returns an empty string instead of leaking the raw function reference.
Deprecations 1
A warning is emitted when t is called before ready with useSuspense: false.
New APIs and options 6
useTranslation accepts selector functions as keyPrefix with full type-safe key narrowing when enableSelector is enabled.
The i18nKey prop of <Trans> now accepts a SelectorKey.
Exports nodesToString with runtime and TypeScript typings to support i18next-cli.
Adds a configuration option to set default props for the Trans component, such as tOptions, shouldUnescape, and values.
The IcuTrans component is now exported.
Introduces the IcuTrans component.
Behavior and default changes 2
The values prop now infers interpolation variables from the translation string when custom types are configured.
The count prop is optional and can be inferred from children.
Tooling 1
TypeScript 6 is allowed as a peer dependency.
Fixes and other changes 24
The selector keyPrefix overload no longer matches when keyPrefix is absent, fixing defaultNS: false with an explicit ns option.
Merged TransSelector overloads into a single signature so typeof Trans remains extendable.
Fixed
<Trans>withenableSelector: truenot supporting multiple selectors for fallbacks.When init() hasn't been called before useSSR, it now logs a warning instead of throwing.
useSSR, getInitialProps and Translation no longer crash when no i18next instance is available; they log a clear warning instead.
Fixed overriding React component props not working.
Fixes handling of named tags with underscores in Trans.
Fixes type errors when you've declared a resources type.
Interpolated values in component props are unescaped before being passed to React, preventing double-escaped rendered output.
Fixes a runaway effect in useTranslation.
Avoids the "ref is not a prop" warning when a user ref is placed on an element inside <Trans>.
Improves useTranslation to fix "Maximum update depth exceeded" while still supporting the new react-compiler.
Avoids the “Uncaught TypeError: Cannot redefine property: __original” error.
Reverts a fix for inconsistent behavior: Trans sets defaultValue when the t call does not set the field.
Adds an i18n wrapper for compatibility with React Compiler and React.memo.
Fixes an issue where hyphened components break.
Fixes the Trans component breaking when its content includes a less-than sign.
Fixed a regression so bindI18nStore works correctly.
Attempts to address conditional calls to inner hooks that violate React's rules of hooks.
Fixes handling of spread props for inner components in Trans (icu).
Trans uses defaultValue from tOptions as a fallback when the t call does not set the field, making its behavior consistent with t.
Fixes detection of pre-transformation interpolation use, including number and date formatting.
Invalid identifiers are quoted in the props object.
Adds missing .js extensions to Icu imports.