i18next 27 and react-i18next 18: what changes and how to upgrade
On this page
Key takeaways
- i18next 27.0.0 and react-i18next 18.0.0 came out together on ; the current versions are 27.2.2 and 18.0.3 ().
- Four defaults change:
fallbackLngisfalse,returnEmptyStringisfalse, a language code without a region gets its canonical casing, and the types check interpolation variables. - A language code from a detector or
changeLanguage()that has the shape of markup or a path is refused, unless you configured it. - In react-i18next 18,
Transrenders values and entities as written and re-renders on a language change by itself. - Both need Node.js 22 or later; react-i18next 18 needs i18next 27 and React 18 or later.
Upgrade with your agent
Paste this into your agent (Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI, ...). The migration guides list every change with what to do, and your agent applies what concerns your code:
Upgrade this project to i18next 27 and react-i18next 18.
First read the two migration guides:
https://www.i18next.com/misc/migration-guide.md (section "v26.x.x to v27.0.0")
https://www.i18next.com/react/latest/migrating-v17-to-v18.md
Apply what concerns this code, run the tests and the build,
and list what you changed and why.
Without an agent, these options keep the behavior of v26 where an option exists, while you go through the changes:
i18next.init({
fallbackLng: 'dev', // 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
}
}
The four defaults
fallbackLng is false instead of ['dev']. Without a fallbackLng, i18next no longer asks the backend for
dev (with i18next-http-backend, /locales/dev/translation.json), and saveMissing sends missing keys for the current
language. Set fallbackLng to your main language.
returnEmptyString is false. An empty translation falls back like a missing one: to the fallback language, the
default value or the key. i18next-cli writes '' for keys not yet translated in the other languages; they now show the
fallback language instead of a blank. An explicit t('key', '') still returns ''. Where an empty string is meant to
show nothing, for example when your translation tool keeps empty strings on purpose, set returnEmptyString: true in
init() and in CustomTypeOptions.
Language codes without a region get their canonical casing, as codes with a region already did: 'EN' becomes
'en'. Only the casing changes; aliases such as iw or tl stay as they are, and so do codes that are not BCP 47
(en_US). cleanCode: false keeps codes exactly as they are and is deprecated.
The types check interpolation variables (strictInterpolationChecks): t() needs the options for a string with
variables, so a {{name}} cannot be left out of a call, and plural keys are checked too. A wrapper around t() is
typed with ParseKeysWithoutVariables; variables that interpolation.defaultVariables fills in are declared with
defaultVariables in CustomTypeOptions.
What else changes in i18next 27
- Each instance has its own logger and post-processors. An instance from
createInstance()no longer sees what the default instance registered, so calluse()on each instance; a clone (cloneInstance()) keeps its parent's. - Unsafe language codes are refused. A code that does not have the shape
isSafeLanguageCode()checks (letters, digits,-,_,@and., at most 128 characters) is refused unless it is listed insupportedLngs, afallbackLng,preloadorresources. Before, a detector could make"><img src=x onerror=alert(1)>the value ofi18next.language, which apps put into<html lang>. BCP 47, POSIX (sr@latin) and private-use codes (en-x-pirate) pass. - An object without
returnObjectscounts as a missing key:t()returns the default value or the key, instead of the sentence "key '…' returned an object instead of string." that ended up in the UI. /is no longer escaped:'$10/month'stays as it is instead of'$10/month'. Snapshots that contain/need an update.addResources()keeps numbers, booleans and objects, which it dropped before.createInstance(options)merges the defaults right away, sogetFixedT()no longer throws beforeinit().keySeparator: falsemeans flat keys only: a key is no longer split at the textfalse, and selectors work on the flat keys.
Removed: the dotted language in resource store calls (getResource('en.translation.key'); pass language, namespace
and key separately), the interpolation.*Escaped options (pass the delimiters as prefix, suffix, nestingPrefix
and nestingSuffix), the type compatibilityJSON, the option types of plugins, and the CommonJS root index.js.
What keeps working: backends and detectors without callbackApi (with a deprecation warning in debug mode), and the
writable isInitialized, which react-i18next 17's useSSR and the Pages Router of next-i18next rely on.
What changes in react-i18next 18
Transrenders values and entities as written. It always decodes HTML entities after parsing, asIcuTransdoes:Tom & Jerryno longer renders asTom & Jerry, and a date17/12/2025no longer as17/12/2025. Values still render as text, never as markup.shouldUnescapeis ignored and warns.TransandIcuTransre-render on a language change by themselves, likeuseTranslation; before, they waited for a parent to re-render.- The
reactoptions stay on their instance. A second instance no longer inherits the first one'suseSuspense: false; set them on every instance, or callsetDefaults()once. - The
i18nfromuseTranslationreads the instance, so afterawait i18n.changeLanguage('de')it saysde. A check likeprevProps.i18n.language !== this.props.i18n.languageno longer sees the change: compare the objects. useSSRandwithSSRcallhydrate(). Test mocks needhydrate, and mocks used withTransneedonandoff, sinceTransnow subscribes to events.Transworks in React Server Components. Areact-serverexport condition resolvesimport { Trans } from 'react-i18next'to the variant without context; pass the instance of the request asi18n.- Removed: the
react-i18next/icu.macroBabel macro (writeIcuTrans), and the AMD build. The UMD build no longer bundles i18next: 26.2 KB minified in 18.0.0, against 77.6 KB in 17.1.13. - Types: the
allowObjectInHTMLChildrenaugmentation is opt-in (import 'react-i18next/augment-react'), andI18nContextisundefinedoutside anI18nextProvider, as at runtime.
Support
Node.js 22 or later (CI runs 22, 24 and 26). The builds target ES2020: Chrome and Edge 80, Firefox 80, Safari 14.
TypeScript ^5 || ^6 || ^7, unchanged.
Since 27.0.0
- 27.1.0: when the plural form for
countis missing,t()uses the_otherform of the same language before the next fallback language, as CLDR does. - 27.1.2 and 27.1.3: language codes and namespaces from requests no longer grow a server's memory without end, and
a code named like an
Object.prototypeproperty no longer breaks loading. - 27.2.2 and 18.0.3 () are the current versions. Every change is in the changelogs of i18next and react-i18next.
FAQ
Can I upgrade i18next first and react-i18next later?
Yes. react-i18next 17.1.13 and later work with i18next 27. Apps on React 16 or 17 stay on react-i18next 17, since 18 needs React 18.
Does next-i18next work with i18next 27?
Yes: next-i18next 16.5.1 accepts i18next 23.7.13 and later, and its Pages Router keeps working because
isInitialized stays writable.