On this page
- Install both majors together
- React 18 or later
- Trans renders entities as text, whatever escapeValue is
- escapeValue guidance
- Trans and IcuTrans follow language changes on their own
- The i18n instance from useTranslation
- react options are per instance
- SSR: useSSR and withSSR
- Server Components can import from react-i18next
- TypeScript
- allowObjectInHTMLChildren needs an import
- I18nContext can be undefined
- ReactOptions
- Smaller changes
- icu.macro is removed
- UMD and AMD builds
- Package
- Tooling
Migrating v17 to v18
What changes when you move from react-i18next 17 to 18, with the fix for each change.
react-i18next 18 is released together with i18next 27. Most apps only need to update both packages and their test snapshots. The sections below list every change you may notice, with the one-line fix where there is one.
Install both majors together
react-i18next 18 needs i18next 27:
npm install i18next@27 react-i18next@18
i18next 27 changes some defaults (fallbackLng, returnEmptyString, / in escaped values, strict interpolation types). Read the i18next migration guide for those.
If you cannot move to react-i18next 18 yet: on i18next 27, use react-i18next 17.1.13 or later (it brings the types of the react init options), or 18.
React 18 or later
React 16 and 17 are no longer supported (for React Native, that means 0.69 or later). Apps on React 16 or 17 stay on react-i18next 17.
useSyncExternalStore now comes from React itself, so the use-sync-external-store package is no longer a dependency.
Trans renders entities as text, whatever escapeValue is
Trans used to show escaped values as entities with i18next's default escapeValue: true: a value Tom & Jerry rendered as Tom & Jerry, and a date 17/12/2025 as 17/12/2025. Unless you passed shouldUnescape, you had to set escapeValue: false to get readable text.
Now Trans always decodes the entities after it has parsed the translation, like IcuTrans already did, in text and in attribute values, both with react.unescape (the default decodes the common entities). Its output is the same for escapeValue: true and false:
- values render as text, never as markup (this part is in place since v17.1.10): to render markup, use
componentsor children, or{{- var}}in the translation for a value the translator may insert unescaped - a formatter that returns the key and options of a nested translation (
$t({{value, bytes}}), withbytesreturningbyte, { "count": 3 }) is escaped like any other value, so its"reaches the options as"and they no longer parse (this part is in place since v17.1.10, and plaint()does the same withescapeValue: true): write that placeholder as$t({{- value, bytes}}), as long as the formatter never puts user input into the options - entities in the translation itself (
&,<, , ...) render as their characters - the
shouldUnescapeprop andreact.transDefaultProps.shouldUnescapeare ignored. Remove them. In development and withdebug: true,Transwarns about them (codeDEPRECATED_OPTION).
What to do: update snapshot tests that contain &, /, < and similar inside Trans output, and remove shouldUnescape.
escapeValue guidance
Trans and IcuTrans no longer depend on interpolation.escapeValue. escapeValue: false is still fine for React apps, because React escapes the text it renders. Keep escapeValue: true if you put t() output into dangerouslySetInnerHTML or another HTML sink.
Trans and IcuTrans follow language changes on their own
Trans and IcuTrans now re-render on the same events as useTranslation: react.bindI18n (default languageChanged) and react.bindI18nStore. You no longer need a useTranslation() call or a changing key in a parent only to update them after changeLanguage().
- With a
tprop, the passedtstill decides the language: atfromgetFixedT('en')keeps rendering English. - They do not suspend or load anything on their own; that stays the job of
useTranslationand friends. TransWithoutContextandIcuTransWithoutContextuse no hooks and do not re-render on their own.- Test mocks of the instance need
onandoff(see SSR: useSSR and withSSR for all mock additions).
The i18n instance from useTranslation
The i18n returned by useTranslation (and passed by withTranslation and Translation) used to be a copy of the instance, taken when the language changed. A copy held across await i18n.changeLanguage('de') still reported the old language, and properties set on it never reached the instance.
It now forwards every read and write to the instance, so it always shows the current state. It is still a new object whenever the language changes, so dependency arrays, memo and the React Compiler notice the change as before, and i18n === i18next is still false.
Because an older object now reads the current language too, comparing the language of the previous i18n with the current one no longer sees a change.
What to do: compare the objects themselves, or keep the previous language yourself:
// before: never true in v18, both objects read the current language
componentDidUpdate(prevProps) {
if (prevProps.i18n.language !== this.props.i18n.language) this.reload();
}
// v18: a new object means the language state changed
componentDidUpdate(prevProps) {
if (prevProps.i18n !== this.props.i18n) this.reload();
}
The same goes for hooks: compare usePrevious(i18n) !== i18n, or keep the previous i18n.language in a ref.
react options are per instance
initReactI18next used to copy the react options of the instance it was registered on into module-wide defaults, so a second instance without react options inherited them (for example useSuspense: false). Now each instance uses its own react options on top of the defaults.
What to do: if you create several instances and only one sets react options, set them on every instance, or call setDefaults() once:
import { setDefaults } from 'react-i18next';
setDefaults({ useSuspense: false });
SSR: useSSR and withSSR
useSSR and withSSR keep their signatures. They now call i18next's hydrate(resources, lng) (since i18next 26.7) instead of writing the instance's internal flags.
What to do: only custom code that set isInitialized, initializedStoreOnce, initializedLanguageOnce or services.resourceStore.data itself should call i18n.hydrate(initialI18nStore, initialLanguage) instead. The flags are still writable in i18next 27, but deprecated.
Test mocks of the i18next instance need small additions:
onandoffwhereverTransorIcuTransrender with them, since both subscribe to events now (withbindI18nStoreset, alsostore.onandstore.off): a minimal mock like{ t, options, language }throwsi18n.on is not a function- a
hydratemethod where they are used withuseSSRorwithSSR oncewhere translations load beforeinit()has finished
Tests that use a real instance (i18next.createInstance()) need nothing.
Server Components can import from react-i18next
In a React Server Component, import { Trans } from 'react-i18next' used to fail with createContext is not a function. The package now has a react-server export condition (used by Next.js and other RSC bundlers) with what works without context and hooks:
TransandIcuTrans(the context-free variants),TransWithoutContextandIcuTransWithoutContextnodesToString,initReactI18next,setI18n/getI18n,setDefaults/getDefaults
Hooks, HOCs, Translation, I18nextProvider, I18nContext, useSSR, withSSR, composeInitialProps and getInitialProps stay client-only: importing them in a Server Component is a build error instead of a crash at runtime.
Without an i18n prop, the server Trans and IcuTrans use the global instance set by initReactI18next. That works for an app with a single instance. With an instance per request, pass that instance as i18n (t is optional). A t alone is not enough: a t from getFixedT carries no instance, so the options, formatting and the language for the values would still come from the global one. In development and with debug: true, they warn when i18n is missing (code GLOBAL_INSTANCE_ON_SERVER):
// app/[lng]/page.jsx (Server Component), here with next-i18next's getT from your server module
import { getT } from '@/i18n.server';
import { Trans } from 'react-i18next';
export default async function Page() {
const { t, i18n } = await getT('common');
return (
<Trans
t={t}
i18n={i18n}
i18nKey="welcome"
components={{ bold: <strong /> }}
/>
);
}
The react-i18next/TransWithoutContext and react-i18next/IcuTransWithoutContext entry points keep working.
TypeScript
allowObjectInHTMLChildren needs an import
react-i18next no longer changes React's HTMLAttributes['children'] type for every app. If you set allowObjectInHTMLChildren: true (to write objects like {{ name }} inside HTML elements nested in Trans), add one import next to that declaration:
// i18next.d.ts
import 'react-i18next/augment-react';
declare module 'i18next' {
interface CustomTypeOptions {
allowObjectInHTMLChildren: true;
// ...
}
}
With current @types/react, this augmentation needs skipLibCheck: true: @types/react declares children in DOMAttributes, and widening it in HTMLAttributes fails library checking with TS2430. Without allowObjectInHTMLChildren you need nothing; i18nIsDynamicList keeps working without the import.
I18nContext can be undefined
useContext(I18nContext) returns undefined outside an I18nextProvider, and its value also carries defaultNS. The type now says so: { i18n: i18n; defaultNS?: string | string[] } | undefined. Add a check or use useTranslation(). getI18n() keeps its type.
ReactOptions
The type of the react init options now comes from react-i18next: i18next 27 declares an empty ReactOptions interface and react-i18next fills it in. import type { ReactOptions } from 'i18next' keeps working, and ReactOptions can also be imported from react-i18next. A program that does not load react-i18next's types no longer checks the react options.
Smaller changes
useSSRaccepts its third argument{ i18n }anduseTranslationitsbindI18nStoreoption in the types, as at runtime.shouldUnescapeis marked@deprecated.- With i18next 27's
strictInterpolationChecks,t('key')needs the variables of the string.TransandIcuTranskeepvaluesoptional.
icu.macro is removed
The react-i18next/icu.macro Babel macro (deprecated since v17.0.21) and the placeholder exports date, time, number, select, plural and selectOrdinal of the main entry are removed. Write IcuTrans directly:
// before
import { Trans } from 'react-i18next/icu.macro';
<Trans i18nKey="welcome" values={{ name }}>
Welcome back, <strong>{name}</strong>!
</Trans>
// after
import { IcuTrans } from 'react-i18next';
<IcuTrans
i18nKey="welcome"
defaultTranslation="Welcome back, <0>{name}</0>!"
content={[{ type: 'strong' }]}
values={{ name }}
/>
Plurals and selects go into the ICU message, for example {count, plural, one {# message} other {# messages}}. You can remove babel-plugin-macros if nothing else uses it.
UMD and AMD builds
The UMD build (react-i18next.js, react-i18next.min.js, dist/umd/) no longer contains a copy of i18next: it uses the global i18next, so load i18next's UMD build first. It is also less than half the size.
<script src="https://unpkg.com/i18next@27/i18next.min.js"></script>
<script src="https://unpkg.com/react-i18next@18/react-i18next.min.js"></script>
The AMD build (dist/amd/) is removed. RequireJS and other AMD loaders can load the UMD file instead, with a module path for i18next.
Package
engines.nodeis>=22.- The build targets ES2020 syntax (optional chaining,
??), pinned instead of following browserslistdefaults. @babel/runtimeis no longer a dependency.
Tooling
- i18next-cli: update to the release published with i18next 27.
- next-i18next: its peers already allow both majors.
The full list of changes is in the CHANGELOG.