Plurals, Genders, and Variables: ICU MessageFormat for Developers

TL;DR: ICU MessageFormat is a translation string syntax that puts plural rules, gender, and variables inside one message, such as {count, plural, one {# item} other {# items}}. Your code passes raw values; each locale's translation picks its own CLDR plural categories (zero, one, two, few, many, other), so Polish gets four forms, Arabic six, and Japanese one.

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.

ICU MessageFormat Syntax Cheat Sheet

Every ICU construct you will actually use, with what it renders. The # inside a plural branch is replaced by the formatted number.

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.

The Bug That Ships in Almost Every App

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.

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.

What ICU MessageFormat Actually Is

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 count picks a CLDR plural category per locale, and the category picks the branch. The same code works for English, Polish and Arabic.

The Four Constructs Worth Knowing

1. Simple arguments

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.

2. plural

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

3. select

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.

4. selectordinal

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

ICU Plural Rules by Language

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.

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

Numbers, Dates, and Currency Inside Messages

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.

Nesting and Rich Text

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}
  }}
}"

Nesting select inside plural multiplies the branches: two levels mean four full sentences to translate.

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.

Mistakes That Show Up in Code Review

• Concatenating translated fragments. t("deleted") + " " + count + " " + t("items") is unfixable by a translator. One key, one sentence.
• Reusing a key in two places. "Open" as a button and "Open" as a status are the same word in English and different words in German. Key by meaning, not by string.
• Omitting the other branch. It is the required fallback. A message without it throws at runtime in strict formatters.
• Putting HTML in the message string. Raw <b> tags invite XSS through translation files and break when a translator mangles a tag. Use rich-text callbacks.
• Translating the ICU syntax itself. A machine translator with no ICU awareness will happily translate the literal word other or reorder the braces, producing a message that fails to parse. Validate ICU syntax in CI.

Validating ICU 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:

• Parse every message in every locale with the FormatJS parser and fail the build on syntax errors
• Check that the set of variables in each translation matches the source message — a missing {count} is a silent content bug
• Assert that every plural message includes an other branch
• Snapshot-render a few numbers (0, 1, 2, 5, 21, 101) per locale and eyeball the output once

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

babelize check covers the first two from the command line: npx @babelize/cli check reports broken ICU and plural forms and lost placeholders in every locale file. It only reads files, so it needs no account and no network access.

When You Do Not Need ICU

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.

FAQ

What is ICU MessageFormat?

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.

What are the ICU plural rules?

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.

What is the difference between =0 and zero in an ICU plural?

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

Which i18n libraries support ICU MessageFormat?

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.

Should I put HTML inside my ICU messages?

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.

The Short Version

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.

Written with AI assistance and reviewed by the Babelize team. Every formatted output was checked with intl-messageformat.

Originally published on the Babelize blog. Disclosure: Babelize is our product, an AI localization tool for Next.js, React and Vue apps: it generates and syncs your JSON locale files from your repo.