i18n

The message and translation layer of CX's internationalization surface. Build, merge, and inspect message catalogs that map a key to per-locale ICU MessageFormat strings; resolve a key for a target locale through a fallback chain; and evaluate MessageFormat templates with interpolation, CLDR plurals, select, selectordinal, nested forms, and typed args. A locale's CLDR plural category for a number is also exposed. Depends one-way on cx-stdlib/locale for all number, date, and currency formatting; locale arguments are BCP 47 tags.

i18n:catalog-from-map

[$i18n:catalog-from-map] -> element — Build a catalog element from a map of key to per-locale MessageFormat strings.

            [?lib 'cx-stdlib/i18n']
[$i18n:catalog-locales [$i18n:catalog-from-map {"greeting": {"en": "Hello, {name}!", "fr": "Bonjour, {name} !"}}]]
          
            ('en', 'fr')

i18n:load-catalog

[$i18n:load-catalog] -> element — Read a catalog from its on-disk CX-document form; requires the read capability.

            [?lib 'cx-stdlib/i18n']
[$i18n:load-catalog "conformance/data/i18n/messages.cx"]
          
            cx-err:CXER0271

i18n:catalog-merge

[$i18n:catalog-merge] -> element — Merge catalogs left-to-right, last-writer-wins.

            [?lib 'cx-stdlib/i18n']
[$i18n:message [$i18n:catalog-merge [$i18n:catalog-from-map {"k": {"en": "A"}}] [$i18n:catalog-from-map {"k": {"en": "B"}}]] "k" "en" {}]
          
            B

i18n:catalog-merge-seq

[$i18n:catalog-merge-seq] -> element — Merge a runtime-assembled sequence of catalogs, last-writer-wins.

            [?lib 'cx-stdlib/i18n']
[$i18n:message [$i18n:catalog-merge-seq ([$i18n:catalog-from-map {"k": {"en": "A"}}], [$i18n:catalog-from-map {"k": {"en": "B"}}])] "k" "en" {}]
          
            B

i18n:catalog-locales

[$i18n:catalog-locales] -> [sequence string] — List the distinct locales present across a catalog's entries.

            [?lib 'cx-stdlib/i18n']
[$i18n:catalog-locales [$i18n:catalog-from-map {"greeting": {"en": "Hello, {name}!", "fr": "Bonjour, {name} !"}}]]
          
            ('en', 'fr')

i18n:catalog-keys

[$i18n:catalog-keys] -> [sequence string] — List the message keys defined in a catalog.

            [?lib 'cx-stdlib/i18n']
[$i18n:catalog-keys [$i18n:catalog-from-map {"greeting": {"en": "Hello, {name}!"}, "farewell": {"en": "Bye, {name}!"}}]]
          
            ('greeting', 'farewell')

i18n:message

[$i18n:message] -> string — Resolve a key for a locale through the fallback chain and evaluate it against args; raises on an unknown key.

            [?lib 'cx-stdlib/i18n']
[$i18n:message [$i18n:catalog-from-map {"default": "en", "greeting": {"en": "Hello, {name}!"}}] "greeting" "de" {"name": "Ada"}]
          
            Hello, Ada!

i18n:message-or

[$i18n:message-or] -> string — Like message, but evaluate the fallback string instead of raising on an unknown key.

            [?lib 'cx-stdlib/i18n']
[$i18n:message-or [$i18n:catalog-from-map {"greeting": {"en": "Hi"}}] "missing.key" "en" {"name": "Ada"} "Hello, {name}!"]
          
            Hello, Ada!

i18n:format-message

[$i18n:format-message] -> string — Evaluate a MessageFormat string against args for a locale, with no catalog.

            [?lib 'cx-stdlib/i18n']
[$i18n:format-message "{count, plural, =0 {no items} one {# item} other {# items}}" "en" {"count": 0}]
          
            no items

i18n:plural-category

[$i18n:plural-category] -> atom — Return the CLDR cardinal plural category for a number in a locale.

            [?lib 'cx-stdlib/i18n']
[$i18n:plural-category 1 "en"]
          
            :one

i18n:plural-category-ordinal

[$i18n:plural-category-ordinal] -> atom — Return the CLDR ordinal plural category for a number in a locale.

            [?lib 'cx-stdlib/i18n']
[$i18n:plural-category-ordinal 1 "en"]
          
            :one