Handle plurals, dates and numbers

Let the locale select grammar and formatting while the application keeps control of values, units, and time zones.

An item count contains two decisions: what number the application means, and how the reader's language expresses that quantity. Dates and money have the same separation. Keep values structured until rendering so grammar, separators, currency, and time zone can be chosen deliberately.

These examples use @lingo.dev/react. Native resource systems use their own message syntax and generators; ICU-like notation does not make all runtimes interchangeable.

Give the formatter a complete message #

Inside a component under LingoProvider, use the numeric count with a plural message:

tsx
const l = useLingo();

const label = l.plural(
  count,
  { one: "# item", other: "# items" },
  { context: "Number of items in the shopping cart" },
);

Import useLingo from @lingo.dev/react; count is the application's numeric value. The runtime constructs an ICU message and formats the catalog's translation using the current locale. one and other are grammatical categories. Concatenating a translated noun after a formatted number would lose that selection and the ability to change word order.

The plural helper builds named CLDR categories; it does not include exact-number branches such as =0. For a product-specific zero message, use the text path with an explicit ICU expression:

ts
l.text("{count, plural, =0 {No items} one {# item} other {# items}}", {
  context: "Cart count with a distinct empty state",
  values: { count },
});

Target languages can require more categories than English. Inspect the translated message and exercise the forms its locale selects instead of forcing every language into the source's branches. Plurals and selects documents the supported forms and extraction behavior.

For a semantic alternative, use stable selector values:

ts
l.select(role, {
  admin: "Manage team settings",
  member: "View team settings",
  other: "View settings",
}, { context: "Settings action for the user's team role" });

The application supplies role. Translate the branch messages while retaining admin, member, and the required other fallback. An unknown value uses other.

Treat ordinal position as different from cardinal quantity #

An ordinal describes a position. Use the text path's complex ICU formatter for a message such as:

ts
l.text("You finished {position, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}", {
  context: "Participant's finishing position in a competition",
  values: { position },
});

The suffixes belong to the English source, not to a universal rule. A target translation must express the position in its own language. Supplying values enables formatting on the text path; generated declarations check the call contract but do not validate every nested ICU branch.

Keep currency and percentage units explicit #

Use numeric amounts with the corresponding currency code:

ts
const price = l.currency(1234.5, "EUR");
const discount = l.percent(0.15);

The first call formats euros; it does not convert another currency into euros. The second represents fifteen percent because its input is a fraction. Supplying 15 would mean a different quantity. When inserting these formatted strings into a sentence, pass them through named values rather than building a new source string.

The formatting helpers also cover numbers, units, lists, and other Intl-backed values. Check each helper's defaults and supported options. Locale-aware formatting does not translate every custom unit label, and invalid options can still fail.

Choose the date's meaning and display time zone #

A timestamp represents an instant; a calendar date can represent a day without a time zone. Do not turn a date-only deadline into a midnight instant unless that conversion matches the product's meaning.

For an instant, specify the intended display zone:

ts
const instant = new Date("2026-01-02T00:30:00Z");

const date = l.date(instant, { timeZone: "UTC" });
const time = l.time(instant, { timeZone: "UTC" });

These helpers use the active locale for presentation and UTC for the displayed zone. The underlying standard APIs can also be used directly:

ts
new Intl.NumberFormat("de-DE", {
  style: "currency", currency: "EUR",
}).format(1234.5);

new Intl.DateTimeFormat("en-US", {
  dateStyle: "medium", timeZone: "UTC",
}).format(new Date("2026-01-02T00:30:00Z"));

Keep rich messages within their supported grammar #

l.rich maps named tags to React components and interpolates simple placeholders. It does not use l.text's complex ICU formatter. A sentence such as “Read our <link>delivery policy</link> for {region}” fits that path when code supplies the link renderer and region value. Adding a plural or ordinal inside it does not gain ICU support.

Keep interaction definitions in code and choose a supported message design when rich structure and grammar overlap. Unknown tags remain literal text, and same-name nesting has limited pairing behavior. See Rich interactive messages.

Check the cases where meaning changes #

Exercise counts of 0, 1, 2, a larger number, and a decimal if the product permits it. For English ordinals, include 1, 2, 3, 11, 12, 13, and 21; use locale-specific expected wording for targets. Test an unknown selector, negative amounts where meaningful, and the same instant in two time zones near midnight.

Load actual target catalogs for these checks. A missing or empty translation can fall back to the source, so plausible output alone does not establish target coverage. Compare the rendered values with the intended quantity, date, and message, then review the language itself.