react-i18next shows the wrong plural form for a count, or prints the key instead of the text
t('item', { count: 5 }) returns the singular textShort answer
i18next picks a plural from the count option and looks for keys ending in _one, _other and so on. Wrong plural text means one of four things: no count was passed, the key files still use the pre-v21 format, the runtime has no Intl.PluralRules, or the language needs more forms than the file defines.
Fix it fast
1Find out which cause you have
Look at the key names in the translation files. Suffixes such as _one and _other are the current format; a bare key plus a key ending in _plural belongs to the old one.
grep -rnE '"item(_[a-z0-9]+)?"' public/locales src/locales locales 2>/dev/null2Match what you see, then jump to its fix
- 1
The raw key shows up on screen instead of the sentenceThe count option is missing or has another nameFix - 2
i18next is version 21 or newer, and the files hold a bare key together with a key ending in _pluralThe translation files are still in the format used before i18next 21Fix - 3
The app runs on React Native with Hermes, or another runtime without the Intl plural API, and plurals fail for languages other than EnglishThe runtime has no Intl.PluralRulesFix - 4
Arabic or another language with more than two forms: some counts show the generic plural text where a different form should appearThe language has more plural forms than the file definesFix
- 1
What does the error look like?
t('item', { count: 5 }) returns the singular textt('item') prints the key item instead of a translated sentence
Cause 1 of 4
The count option is missing or has another name
1Check
The variable must be named exactly count. When the keys only exist with plural suffixes, a call without count does not fall back to the bare key.
grep -rn "t('item'" app components src 2>/dev/null2Fix
Pass the number as count in every call that uses plural keys, and keep the count in the sentence with the interpolation placeholder.
// en/translation.json
{
"item_one": "{{count}} item",
"item_other": "{{count}} items"
}
// component
t('item', { count: items.length })3Verify
The same call with 1 and with 5 returns the two forms.
node --input-type=module -e "import i18next from 'i18next'; await i18next.init({ lng: 'en', resources: { en: { translation: { item_one: '{{count}} item', item_other: '{{count}} items' } } } }); console.log(i18next.t('item', { count: 1 }), '|', i18next.t('item', { count: 5 }))"Confirmed by i18next.com
Cause 2 of 4
The translation files are still in the format used before i18next 21
1Check
Version 21 introduced a new JSON format with suffixes that follow the Intl API. The option that kept the old format working, compatibilityJSON: 'v3', only existed up to version 23, and version 24 removed the old formats altogether.
npm ls i18next
grep -rnE '"[A-Za-z0-9_.-]+_(plural|[0-5])"' public/locales 2>/dev/null2Fix
Convert the files with the official converter, or rename by hand: the bare key becomes key_one and key_plural becomes key_other. For languages with more forms the numeric suffixes become zero, one, two, few, many and other.
npx i18next-v4-format-converter -i ./public/locales -o ./public/locales-v4
// before
"item": "{{count}} item", "item_plural": "{{count}} items"
// after
"item_one": "{{count}} item", "item_other": "{{count}} items"3Verify
No old suffix is left in the converted folder, and t returns the singular for 1 and the plural for 5.
grep -rn "_plural" public/locales-v4 | wc -l # prints 0Confirmed by github.com
Cause 3 of 4
The runtime has no Intl.PluralRules
1Check
i18next gets its plural rules from Intl.PluralRules. The Hermes engine does not implement it. Since version 24 there is no fallback, so without it only English-style _one and _other forms resolve.
console.log(typeof Intl !== 'undefined' && typeof Intl.PluralRules)2Fix
Add a polyfill and import it before i18next is initialised.
npm install intl-pluralrules
// first line of the entry file, before i18next.init
import 'intl-pluralrules'3Verify
Log typeof Intl.PluralRules again; it now prints function, and non-English plurals resolve.
console.log(typeof Intl.PluralRules)Confirmed by i18next.com
Cause 4 of 4
The language has more plural forms than the file defines
1Check
English needs two forms, but other languages use more. Arabic, for example, has zero, one, two, few, many and other. When a form is missing from the file, i18next 27.1 and newer try key_form, then the bare key, then key_other.
node -e "console.log(new Intl.PluralRules('ar').resolvedOptions().pluralCategories)"2Fix
Add one key for every category your language uses, as listed by the check above.
// ar/translation.json
{
"file_zero": "{{count}} ...",
"file_one": "{{count}} ...",
"file_two": "{{count}} ...",
"file_few": "{{count}} ...",
"file_many": "{{count}} ...",
"file_other": "{{count}} ..."
}3Verify
Call t with 0, 1, 2, 3, 11 and 100 and compare each result with the form you expect.
# call t('file', { count }) for each number in your testConfirmed by i18next.com
How do I stop it coming back?
- Write every plural key as a pair or set with suffixes, and always call it with count.
- After upgrading i18next across a major version, read the migration guide and re-check the translation files.
- In React Native, load the Intl.PluralRules polyfill before i18next.
- Ask the translator for every plural category of each language, not only singular and plural.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
next-intl logs MISSING_MESSAGE and shows the key instead of text
The page shows Home.title instead of the translated text
MISSING_MESSAGE means next-intl asked for a key it cannot find in the messages it was given.
4 causes, each with a fixWeb apps
ESLint says an element in a list is missing its key prop
react/jsx-key
react/jsx-key fires when an element returned from map, Array.from or an array literal has no key.
3 causes, each with a fixWeb apps
There is no tailwind.config.js after installing Tailwind 4 and HeroUI in Next.js
HeroUI components render unstyled
Nothing is broken: Tailwind CSS 4 is configured in CSS and no longer creates tailwind.config.js.
3 causes, each with a fixWeb apps
useSession throws because there is no SessionProvider above it
[next-auth]: `useSession` must be wrapped in a <SessionProvider />
useSession reads the session from React Context, and SessionProvider is what creates that context.
3 causes, each with a fixWeb apps
next/link throws React.Children.only on its children
Error: React.Children.only expected to receive a single React element child.
React.Children.only accepts exactly one React element and throws for anything else, including an array with one item.
3 causes, each with a fixWeb apps
Hydration failed after adding next-themes dark mode
Console reports a server and client mismatch on the html element
next-themes changes the html element and knows the theme only in the browser, so server HTML and client HTML differ.
3 causes, each with a fix