Your English pluralization logic will break in Polish, Arabic, and Russian. Learn how ICU MessageFormat handles plurals, gender, numbers, and nested variables so your translated strings stay grammatical in every language you ship.
Every ICU construct you will actually use, with what it renders. The # inside a plural branch is replaced by the formatted number.
| Construct | Syntax | Renders as |
|---|---|---|
| Variable | Hello, {name}! |
Hello, Ana! |
| Plural | {count, plural, one {# file} other {# files}} |
1 file - 5 files |
| Exact match | {count, plural, =0 {No files} one {# file} other {# files}} |
No files |
| Select | {gender, select, female {She} male {He} other {They}} replied |
They replied |
| Ordinal | {n, selectordinal, one {#st} two {#nd} few {#rd} other {#th}} |
21st - 22nd - 23rd - 4th |
| Offset | {n, plural, offset:1 =0 {Nobody} =1 {{name}} one {{name} and # other} other {{name} and # others}} |
Ana and 2 others (n = 3) |
| Number | {price, number, ::currency/EUR} |
EUR 1,234.50 (en) - 1.234,50 EUR (de) |
| Date | {when, date, medium} |
Oct 13, 2026 |
| Rich text tag | You have <b>{count}</b> new messages |
You have 3 new messages |
| Escaping | '{literal}' and '' |
{literal} and ' |
Two rules hold in every message: a plural, select, or selectordinal must end with an other branch, and the translator writes the whole sentence inside each branch. The sections below explain each construct and the mistakes that break them.
Here is a line of code that exists in thousands of production codebases right now:
const label = count === 1 ? "1 item" : `${count} items`;It works perfectly. In English. The moment you translate it, it quietly becomes wrong in most of the world's languages, and nobody on your team will notice because nobody on your team reads Polish.
English has two plural forms: singular and everything else. That is unusually simple. According to the Unicode CLDR plural rules, languages fall into six possible plural categories -- zero, one, two, few, many, and other -- and each language uses a different subset.
| Language | Plural categories | Notes |
|---|---|---|
| Japanese, Korean, Chinese, Vietnamese | 1 | other only: same form for 0, 1, 2, 100 |
| English, German, Dutch, Turkish | 2 | one / other |
| Spanish, Italian | 3 | one / many / other: many covers exact millions (1 millón de usuarios) |
| French, Portuguese (BR) | 3 | one / many / other: 0 and 1 share one; many covers exact millions |
| Czech, Slovak | 4 | one / few / many / other: many is for decimals |
| Polish, Russian, Ukrainian | 4 | one / few / many / other |
| Arabic | 6 | zero / one / two / few / many / other |
Russian is a good illustration of why a ternary cannot save you. The word for "file" changes based on the last digit of the number: 1 файл, 2 файла, 5 файлов, 21 файл, 22 файла, 25 файлов. There is no way to express that with count === 1. There is also no way to express it by adding a second key called items_plural, which is the workaround most teams reach for next.
ICU MessageFormat is a string syntax, originally from the International Components for Unicode project, that moves grammatical decisions out of your code and into the translation string itself. It is supported by next-intl, react-intl / FormatJS, i18next (via the ICU plugin), Android, iOS, Java, and most translation management platforms. If you are still choosing a React library, our next-intl vs react-i18next comparison covers how each one handles ICU.
The basic ICU syntax is a placeholder in curly braces: {argument} for a plain value, or {argument, type, options} where the type is plural, select, selectordinal, number, date, or time. The same message in ICU, stored in an ordinary JSON translation file, looks like this:
{
"fileCount": "{count, plural, one {# file} other {# files}}"
}And the Polish translator, without touching your code, writes:
{
"fileCount": "{count, plural, one {# plik} few {# pliki} many {# plików} other {# pliku}}"
}Your component stays identical in both cases:
t("fileCount", { count: files.length })
That is the whole idea. The code passes data. The translation decides grammar. The # is a placeholder for the number, already formatted for the locale -- so a German user sees 1.234 Dateien and an American sees 1,234 files without you writing a single formatting branch.
The basic case -- a variable dropped into a sentence:
"greeting": "Welcome back, {name}!"
This already buys you something important: the translator controls where {name} goes. In Japanese, the name comes before the greeting. If you had written t("welcome") + " " + name, the translator would have been stuck.
"notifications": "{count, plural,
=0 {No new notifications}
one {# new notification}
other {# new notifications}
}"
Note the difference between =0 and zero. The =0 form is an exact match -- it fires whenever the value is literally 0, in any language. The zero category is a grammatical category used by languages like Arabic and Latvian, and it may not fire for the number 0 at all in a language that does not have it. Use =0 for "empty state" copy and leave the named categories for grammar.
For gender agreement and any other branching that is not numeric:
"invited": "{gender, select,
male {He invited you to {project}}
female {She invited you to {project}}
other {They invited you to {project}}
}"
This matters more than English developers expect. In Spanish, French, Russian, Hebrew, and Arabic, adjectives and past participles agree with gender. A message like "You are subscribed" has two different forms in Russian depending on who is reading it. If your product knows the user's gender, expose it as a select argument. If it does not, that is a real product decision -- tell your translators so they can pick a neutral phrasing instead of guessing.
"rank": "You finished {place, selectordinal,
one {#st} two {#nd} few {#rd} other {#th}
} in the leaderboard"Ordinals follow their own rules that are unrelated to plural rules -- 1st, 2nd, 3rd, 4th, 21st, 22nd. Hardcoding a suffix table is a classic source of "22th" bugs.
These are the CLDR categories each language uses, with example numbers that land in each one. Cardinal rules drive plural; ordinal rules drive selectordinal. Your translation for a locale needs a branch for every category that locale uses, and nothing else.
| Language | Cardinal (plural) | Ordinal (selectordinal) |
|---|---|---|
| English | one (1) - other (0, 2, 3) | one (1st, 21st) - two (2nd, 22nd) - few (3rd, 23rd) - other (4th) |
| German, Dutch | one (1) - other (0, 2, 3) | other |
| Spanish, Italian | one (1) - many (1,000,000) - other (0, 2, 3) | Spanish: other - Italian: many (8, 11, 80) - other |
| French | one (0, 1, 1.5) - many (1,000,000) - other (2, 3) | one (1er) - other |
| Portuguese | one (0, 1, 1.5) - many (1,000,000) - other (2, 3) | other |
| Russian, Ukrainian | one (1, 21, 31) - few (2-4, 22) - many (0, 5-20) - other (1.5) | Russian: other - Ukrainian: few (3, 23) - other |
| Polish | one (1) - few (2-4, 22) - many (0, 5-21) - other (1.5) | other |
| Czech, Slovak | one (1) - few (2-4) - many (1.5) - other (0, 5, 6) | other |
| Arabic | zero (0) - one (1) - two (2) - few (3-10) - many (11-99) - other (100, 101) | other |
| Hebrew | one (1) - two (2) - other (0, 3, 4) | other |
| Hindi | one (0, 1) - other (2, 3) | one (1) - two (2, 3) - few (4) - many (6) - other |
| Latvian | zero (0, 10-20) - one (1, 21, 31) - other (2-9) | other |
| Welsh | zero (0) - one (1) - two (2) - few (3) - many (6) - other (4, 5, 7) | zero - one - two - few - many - other |
| Japanese, Chinese, Korean, Turkish | Turkish: one (1) - other - others: other only | other |
Two details catch people out. French and Portuguese put 0 in one, so "0 fichier" is singular. Spanish, French, Italian, and Portuguese now have a many category for exact millions ("1 millón de usuarios"), so a translation with only one and other will fall back to other there.
Rules change between CLDR releases, so check against the runtime your users actually have instead of a table:
new Intl.PluralRules("pl").resolvedOptions().pluralCategories;
// ["few", "many", "one", "other"]
new Intl.PluralRules("en", { type: "ordinal" }).select(22);
// "two" -> 22nd
ICU also wraps the Intl formatting APIs, so you can keep formatting inside the message where the translator can see it in context:
"invoice": "Your invoice for {amount, number, ::currency/USD} is due {date, date, medium}"
The rule to internalize: pass raw values, never pre-formatted strings. If you call amount.toFixed(2) before handing the value to your translation layer, you have permanently locked every locale into American decimal separators. Pass the Number. Pass the Date. Let the formatter decide. For formatting outside of messages, see our guide to the JavaScript Intl API.
Real interface copy has links and bold spans in the middle of sentences. The wrong instinct is to split the sentence into three keys -- prefix, link text, suffix -- and concatenate. That produces unreadable translation files and breaks in any language with different word order.
Instead, keep the sentence whole and pass the markup as a function:
// message
"terms": "By continuing you accept our <link>Terms of Service</link>."
// component
t.rich("terms", {
link: (chunks) => <a href="/terms">{chunks}</a>,
})The translator sees one coherent sentence and can move the link anywhere inside it. Your JSX stays in your code where it belongs.
You can also nest constructs. This is legal and occasionally necessary:
"shared": "{count, plural,
one {{gender, select,
female {She shared # file}
other {They shared # file}
}}
other {{gender, select,
female {She shared # files}
other {They shared # files}
}}
}"
It is also where readability dies. If a message needs two levels of nesting, that is usually a signal to split it into two separate UI strings instead.
t("deleted") + " " + count + " " + t("items") is unfixable by a translator. One key, one sentence.other branch. It is the required fallback. A message without it throws at runtime in strict formatters.<b> tags invite XSS through translation files and break when a translator mangles a tag. Use rich-text callbacks.other or reorder the braces, producing a message that fails to parse. Validate ICU syntax in CI.Because ICU messages are strings, a broken one is not a compile error -- it is a runtime crash on a page only your Polish users visit. Worth adding to your pipeline:
{count} is a silent content bugother branchA pseudo-localization pass complements these checks: it exercises every message in a fake locale and exposes concatenated sentences and hardcoded strings before real translators see them.
Most strings in a typical app are static labels with no variables. Those do not need ICU and wrapping them in it adds nothing. ICU earns its complexity specifically where a message contains a count, a name, a date, a currency, or a gendered reference -- which in practice is a minority of your keys, and the source of most of your localization bugs.
ICU MessageFormat is a string syntax that lets a single translation key express plural rules, gender agreement, number formatting, and conditional text. It moves grammatical decisions out of application code and into the translation string, so each locale can supply its own plural categories and word order.
ICU uses the Unicode CLDR plural categories zero, one, two, few, many, and other. Each language uses its own subset: English uses one and other, Polish and Russian use one, few, many, and other, Arabic uses all six, and Japanese uses only other. The other branch is required in every plural message.
=0 is an exact match that fires whenever the value is literally zero, in any language, and is used for empty-state copy. zero is a grammatical plural category used by languages such as Arabic and Latvian, and it may not fire for the number 0 in languages that lack that category.
next-intl and react-intl (FormatJS) support ICU natively. i18next supports it through the i18next-icu plugin. ICU is also supported on Android, iOS, Java, and most translation management platforms.
No. Raw HTML in translation files invites XSS and breaks when a translator mangles a tag. Use tag placeholders with a rich-text callback so the markup stays in your components while the translator keeps control of the full sentence.
Pluralization is grammar, and grammar belongs to the language, not to your if statement. ICU MessageFormat exists so that a translator who has never seen your codebase can produce a correct Polish sentence without asking you to ship new code. Adopt it for every message containing a variable, validate the syntax in CI, and pass raw numbers and dates rather than formatted strings.
Once ICU messages are in place, keeping every locale in sync as your source strings change becomes the next bottleneck -- which is exactly the part Babelize automates, detecting new and changed keys and generating ICU-valid translations across your locale files through a Git-native workflow. See the Babelize ICU documentation for how messages are validated.
--- - [All articles](https://www.babelize.co/blogs)