Search documentation

Search all pages, headings and text, in the current package or topic or in all documentation.

Translations

Keys, interpolation, CLDR plurals, missing keys and the typed translation contract.

@workspace/active-i18n 1.1.0Developmentunreleased, in development in Foundationbaseline ce081dc3

Interpolation, plurals and a missing keyClient

Hello Ada

2 new messages

inbox.archived

count = 2

Missing keys reported: inbox.archived

Keys#

A key is a dot path whose first segment is the namespace: inbox.messages reads the messages value of the inbox tree. A dictionary for one language is LocaleTranslations, an object keyed by namespace.

Interpolation#

{{name}} is replaced with String(value). count is always interpolated when it is a number.

TypeScript
t('inbox.greeting', {name: 'Ada'}); // 'Hello Ada'

Plurals#

A plural value is an object whose own keys are all CLDR categories: zero, one, two, few, many, other. With a numeric count, zero is used for 0 when present, otherwise the category Intl.PluralRules gives for the language, otherwise other. Arabic uses all six categories; the example above shows them as you change the count.

Missing keys and failures#

  • A missing key returns the raw key and calls onMissingKey({key, locale}) once.
  • An invalid path, a value that is not a string or a failed plural selection returns the raw key and calls onWarning; an exception returns the raw key and calls onError.
  • Callback messages are stable English sentences; key and locale travel in meta.
TypeScript
const t = createTranslateFunction(dictionary, 'nl', {  onMissingKey: ({key, locale}) => report(`missing ${locale}:${key}`),});

Typed keys#

TranslationCapability<PlainKey, Params> is generic. A resource package of your application can instantiate it with a generated union of its keys and the variables each key needs; a component library keeps the untyped TranslateFunction and receives the host's translator.

Names from CLDR#

getLanguageName, getStandaloneLanguageName, getCurrencyName, getCurrencyOptions and getRegionName read Intl.DisplayNames in the display language, with your own labels as a fallback where the runtime has no name.

This page as Markdown