Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

react-i18next shows the wrong plural form for a count, or prints the key instead of the text

Errort('item', { count: 5 }) returns the singular text

Short 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.

  • Applies to i18next 24 and newer, react-i18next, Next.js 15, Next.js 16
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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/null
  2. 2Match what you see, then jump to its fix

    1. 1The raw key shows up on screen instead of the sentenceThe count option is missing or has another nameFix
    2. 2i18next 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. 3The 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. 4Arabic 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

What does the error look like?

  • t('item', { count: 5 }) returns the singular text
  • t('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/null

2Fix

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

Did this fix it?

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/null

2Fix

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 0

Confirmed by github.com

Did this fix it?

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

Did this fix it?

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 test

Confirmed by i18next.com

Did this fix it?

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:

Related fixes

Web 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 fix

Web 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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.