locale

The primitives layer of CX's internationalization surface. Provides locale-aware string collation (Unicode Collation Algorithm with per-locale tailorings), number, date, time, and currency formatting, BCP 47 locale introspection, and locale-aware case mapping such as Turkish dotted-i and German sharp-s. Ships a CLDR-subset offline catalog as a zero-dependency fallback. Message catalogs, translation, and ICU MessageFormat live in the sibling module cx-stdlib/i18n, which depends one-way on this one; RTL bidi operations are deferred.

locale:collate

[$locale:collate] -> int — Compare two strings in a locale's sort order, returning -1, 0, or 1.

            [?lib 'cx-stdlib/locale']
[$locale:collate "a" "b" "en-US"]

-1

locale:collate-with-opts

[$locale:collate-with-opts] -> int — Compare two strings with collation options (strength, case-first, numeric, ignore-punctuation).

            [?lib 'cx-stdlib/locale']
[$locale:collate-with-opts "ä" "a" {locale: "de-DE", strength: "primary"}]

locale:collate-key

[$locale:collate-key] -> bytes — Produce a persistable UCA sort key whose byte order matches collate's ordering.

            [?lib 'cx-stdlib/locale']
[$locale:collate-key "abc" "@@bad-tag@@"]

            cx-err:CXER3501

locale:format-number

[$locale:format-number] -> string — Format a number per a locale's grouping and decimal conventions.

            [?lib 'cx-stdlib/locale']
[$locale:format-number 1234567.89 "en-US"]

            '1,234,567.89'

locale:format-number-with-opts

[$locale:format-number-with-opts] -> string — Format a number with options for fraction digits, grouping, and notation.

            [?lib 'cx-stdlib/locale']
[$locale:format-number-with-opts 1234567 {locale: "en-US", notation: "compact"}]

            '1.2M'

locale:parse-number-locale

[$locale:parse-number-locale] -> number — Parse a number from a string written in a locale's conventions.

            [?lib 'cx-stdlib/locale']
[$locale:parse-number-locale "1,234,567.89" "en-US"]

            1234567.89

locale:format-date

[$locale:format-date] -> string — Format a date for a locale using an ICU/LDML pattern.

            [?lib 'cx-stdlib/time']
[?lib 'cx-stdlib/locale']
[$locale:format-date [$time:parse-date "2026-05-26"] "fr-FR" "EEEE d MMMM yyyy"]

            'mardi 26 mai 2026'

locale:format-datetime

[$locale:format-datetime] -> string — Format a datetime for a locale using an ICU/LDML pattern.

            [?lib 'cx-stdlib/time']
[?lib 'cx-stdlib/locale']
[$locale:format-datetime [$time:parse-datetime "2026-05-26T14:30:00Z"] "en-US" "yyyy-MM-dd HH:mm:ss"]

            '2026-05-26 14:30:00'

locale:format-date-style

[$locale:format-date-style] -> string — Format a date in a locale's conventional short, medium, long, or full style.

            [?lib 'cx-stdlib/time']
[?lib 'cx-stdlib/locale']
[$locale:format-date-style [$time:parse-date "2026-05-26"] "en-US" :full]

            'Tuesday, May 26, 2026'

locale:parse-date-locale

[$locale:parse-date-locale] -> date — Parse a date from a string for a locale using an ICU/LDML pattern.

            [?lib 'cx-stdlib/locale']
[$locale:parse-date-locale "2026-05-26" "en-US" "yyyy-MM-dd"]

            '2026-05-26'

locale:format-currency

[$locale:format-currency] -> string — Format an amount as a currency for a locale, honoring ISO 4217 minor units.

            [?lib 'cx-stdlib/locale']
[$locale:format-currency 1234.56 "USD" "en-US"]

            '$1,234.56'

locale:currency-symbol

[$locale:currency-symbol] -> string — Return the symbol for a currency as written in a locale.

            [?lib 'cx-stdlib/locale']
[$locale:currency-symbol "USD" "en-US"]

'$'

locale:list-locales

[$locale:list-locales] -> [sequence string] — List the locale tags the module has data for.

            [?lib 'cx-stdlib/locale']
[$locale:is-supported [$first [$locale:list-locales]]]

            true

locale:is-supported

[$locale:is-supported] -> bool — Report whether a locale tag resolves to available data at any fallback level.

            [?lib 'cx-stdlib/locale']
[$locale:is-supported [$first [$locale:list-locales]]]

            true

locale:default-locale

[$locale:default-locale] -> string — Return the system's default locale from the environment.

            [?lib 'cx-stdlib/locale']
[$locale:is-supported [$locale:default-locale]]

            true

locale:locale-name

[$locale:locale-name] -> string — Render a locale's display name in a requested display locale.

            [?lib 'cx-stdlib/locale']
[$locale:locale-name "de-DE" "en-US"]

            'German (Germany)'

locale:language-of

[$locale:language-of] -> string — Extract the language subtag from a locale tag.

            [?lib 'cx-stdlib/locale']
[$locale:language-of "zh-Hans-CN"]

            'zh'

locale:country-of

[$locale:country-of] -> string — Extract the region/country subtag from a locale tag.

            [?lib 'cx-stdlib/locale']
[$locale:country-of "en-US"]

            'US'

locale:script-of

[$locale:script-of] -> string — Extract the script subtag from a locale tag.

            [?lib 'cx-stdlib/locale']
[$locale:script-of "zh-Hans-CN"]

            'Hans'

locale:text-direction

[$locale:text-direction] -> atom — Return a locale's writing direction as :ltr or :rtl.

            [?lib 'cx-stdlib/locale']
[$locale:text-direction "en-US"]

            :ltr

locale:upper-locale

[$locale:upper-locale] -> string — Uppercase a string under a locale's case rules.

            [?lib 'cx-stdlib/locale']
[$locale:upper-locale "i" "tr-TR"]

            'İ'

locale:lower-locale

[$locale:lower-locale] -> string — Lowercase a string under a locale's case rules.

            [?lib 'cx-stdlib/locale']
[$locale:lower-locale "I" "tr-TR"]

            'ı'

locale:title-locale

[$locale:title-locale] -> string — Title-case each word of a string under a locale's case rules.

            [?lib 'cx-stdlib/locale']
[$locale:title-locale "hello world" "en-US"]

            'Hello World'