Plurals and selects
Render complete grammatical alternatives for quantities and application states, with explicit fallback forms.
“1 file is ready” and “2 files are ready” change more than a noun. Other languages make different distinctions. Give the runtime complete alternatives so the selected language can express the whole message correctly.
Choose a form from a quantity #
import { createLingo } from "@lingo.dev/react";
const l = createLingo("en");
const message = l.plural(
2,
{
one: "# file is ready for {name}.",
other: "# files are ready for {name}.",
},
{ context: "Files ready for download", values: { name: "Ana" } },
);This source-language example returns 2 files are ready for Ana. In a translated catalog, the active locale's cardinal rules select the form. The category one is a grammatical category, not a universal test for the integer 1.
plural(count: number, forms: PluralForms, options) requires an other form. The optional categories are zero, one, two, few, and many. Options require context and accept an additional string/number values map. # displays the count; the helper supplies the count argument itself and overrides any count in that map.
The helper builds an ICU message in zero, one, two, few, many, other order. Extraction uses the same builder, so changing the order of properties does not change identity. Changing a form or its context can. Keep forms literal for extraction.
Choose a form from an application value #
Use select for an exact categorical choice:
const action = l.select(
"member",
{
admin: "Manage the team",
member: "View your work",
other: "Open your account",
},
{ context: "Primary navigation action for the signed-in account role" },
);With the l above, this returns View your work. An unknown role uses other. Keep application codes such as admin separate from translated display labels, so a language change does not change the selected state.
select(value: string, forms: SelectForms, options: { context: string }): string requires other, sorts form keys alphabetically when building its ICU source, and supplies the value argument. This helper has no additional values option.
Express exact counts and ordinals with ICU text #
The plural helper exposes cardinal categories. For an exact =0 alternative, use the raw ICU example. For an ordinal, use a literal l.text message:
const position = l.text(
"{position, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}",
{
context: "Finishing position in a ranked result, using English source suffixes",
values: { position: 2 },
},
);The English result is 2nd. A target template needs the target language's expression; translating the surrounding interface does not make English suffixes appropriate elsewhere.
Test zero, one, and representative categories for each target language, plus an unknown select value. Generated message constraints narrow text and rich; the plural and select helpers keep their own forms/options types. Inspect their extracted ICU representations and render the cases to verify the actual grammar paths.