ICU MessageFormat is a syntax for writing translatable messages that contain variables, plurals and language-specific variations in one string, so every language can express them correctly. Instead of building sentences in code, developers write a single message such as {count, plural, one {# file} other {# files}}, and translators adapt it to the plural rules of their own language. This guide explains the syntax, the plural categories and how to translate ICU messages safely.
Why ICU MessageFormat Exists
English has two plural forms: one and other. Many languages have more. Polish and Russian use several forms depending on the number, and Arabic uses six. Code like count + " files" or if (count == 1) cannot handle this. ICU MessageFormat moves the logic into the message, where each language can define its own forms. It is part of the ICU libraries described in the ICU user guide and relies on plural rules from the Unicode CLDR.
ICU MessageFormat Syntax
| Element | Example | Purpose |
|---|---|---|
| Simple argument | Hello, {name}! |
Inserts a variable |
| Plural | {count, plural, one {# item} other {# items}} |
Chooses a form based on a number |
| Exact match | {count, plural, =0 {No items} other {# items}} |
Special text for a specific number |
| Select | {gender, select, female {She} male {He} other {They}} |
Chooses text by a keyword |
| Ordinal | {pos, selectordinal, one {#st} two {#nd} few {#rd} other {#th}} |
Ordinal numbers such as 1st, 2nd |
| Number and date | {price, number, currency}, {d, date, short} |
Locale-aware formatting |
The # symbol inside a plural branch is replaced with the formatted number.
CLDR Plural Categories
ICU uses six plural categories: zero, one, two, few, many and other. Every language uses other, but most use only some of the categories. English uses one and other; Russian uses one, few, many and other; Arabic uses all six. The rules for each language are published in the Unicode CLDR plural rules charts.
Where ICU MessageFormat Is Used
- JavaScript: FormatJS and react-intl, and i18next with an ICU plugin.
- Angular: ICU expressions in templates, extracted to XLIFF. See our Angular i18n guide.
- Java and C/C++: the ICU4J and ICU4C libraries.
- Flutter: ARB files use ICU syntax for plurals and selects.
- Android: the
android.icupackage exposes ICU APIs.
Unicode has also published MessageFormat 2.0, a newer syntax designed to be easier to read and extend. Most production apps still use the classic ICU syntax described here.
How to Translate ICU Messages
- Translate only the text inside the braces. Keywords such as
plural,select,oneandotherstay in English. - Keep variable names unchanged.
{name}must stay{name}. - Add or remove plural branches to match the target language, for example add
fewandmanyfor Polish. - Always keep the other branch. It is required.
- Check the braces. One missing brace breaks the whole message.
Common ICU Mistakes
- Translating keywords or variable names.
- Copying the English plural branches without adding the forms the language needs.
- Nesting too many selects and plurals in one message, which confuses translators.
- Concatenating ICU messages in code instead of writing full sentences.
- Skipping tests with numbers like 0, 1, 2, 5, 11 and 21, which trigger different forms.
Translate ICU Messages With WordBeam
WordBeam imports resource files that contain ICU messages, such as JSON and XLIFF, and keeps placeholders and syntax protected in the CAT editor. QA checks flag missing or changed placeholders before export, and translation memory reuses approved messages across releases. Explore WordBeam for UI translations or start a free 14-day trial.
Frequently Asked Questions
What does ICU stand for?
ICU stands for International Components for Unicode, a set of open-source libraries for internationalization maintained by the Unicode Consortium.
How many plural forms are there in ICU?
There are six categories: zero, one, two, few, many and other. Each language uses a subset of them.
Should translators change the plural keywords?
No. Keywords stay in English, but translators add or remove branches to match their language's plural rules.