Skip to content

std::locale

Locales: which language, script and region text is for. A Locale holds a canonical BCP 47 tag such as pt-BR or zh-Hant-HK, Unicode extensions included (en-US-u-nu-latn). Write a fixed one as a typed literal, Locale"pt-BR", which is checked when the program is checked; parse text with Locale.parse, and read a POSIX value such as LANG with Locale.from_posix. Nothing reads a locale implicitly (How code gets a locale). Locale.fallbacks gives the chain locale data is looked up along, by CLDR’s parent locales, and Locale.negotiate picks the best of the locales a program offers for the ones a reader asked for.

A program carries the CLDR data of the locales its nomi.toml lists under [i18n].locales, or of every locale when it lists none, and nomi build keeps only the parts of that data the program uses. Numbers, plurals and lists add under a kilobyte per locale, and dates about 3 KB more. Money adds 10 to 18 KB, since it carries the symbol and name of every currency in use. Sorting adds the order every language starts from, about 265 KB, and a few hundred bytes for most locales (27 KB for Japanese). The Chinese and Korean orders are 160 to 250 KB each, so a program carries them only when it lists zh or ko; without them, Chinese and Korean sort in the basic order.

std::locale is one of a family of modules. std::plural provides CLDR’s plural rules. Int, Float, Decimal and String format and parse numbers and join lists for a locale (std::int, std::strings), std::currency and std::money provide Currency and Money, std::collation orders text, the calendar types and Duration format and parse dates, times and lengths of time, std::localize holds the Localize interface and the parse error, and std::phrase holds the Phrase a phrase declaration returns. All the locale data comes from one pinned CLDR release, 48.2. Which locales a program carries is set in nomi.toml’s [i18n] table.

Import with import std::locale.

Nothing reads a locale implicitly. A function whose output depends on one takes it as an argument, and an application keeps the current one in an application field, by convention named locale. A library cannot read application fields, so it takes the Locale it needs. A locale is not a Context value. An application’s boot reads the reader’s locale, here from LANG:

pub struct App
    locale: Locale
end

pub fn boot(startup: Startup) -> Result<App, String>
    locale =
        Map.get(startup.env, "LANG")
        |> Maybe.flat_map(fn value -> Locale.from_posix(value) |> Result.to_maybe())
        |> Maybe.with_default(Locale"en")

    Ok(App{locale:})
end

A test group pins the locale through its boot, or overrides it with a with line in setup.

type Locale String

opaque — construction surface is private to its defining module

A locale: a canonical BCP 47 language tag, Unicode extensions included (en-US-u-nu-latn).

It is an opaque type: values come from parsing, and parsing canonicalizes, so two spellings of one locale are equal: EN-us is en-US, and the deprecated iw is he. Locale is Equatable and Hashable, so it is a map key, and it is not Comparable. Display gives the tag; Debug gives the literal that builds it.

assert Display.to_string(Locale"pt-BR") == "pt-BR"
assert Locale.parse("EN-us") == Ok(Locale"en-US")
assert Locale"iw" == Locale"he"
assert Debug.inspect(Locale"zh-Hant-HK") == "Locale\"zh-Hant-HK\""
fn parse(tag: String) -> Result<Locale, Error>

type function on Locale

Parse a BCP 47 tag into its canonical Locale. Case is normalized (EN-us is en-US, zh-hant-hk is zh-Hant-HK), deprecated subtags are replaced (iw is he, in is id, sh is sr-Latn), and Unicode extensions are kept. A failure is an Error: Empty; Underscore {suggestion:} for a POSIX spelling such as pt_BR, whose suggestion is pt-BR (use Locale.from_posix for those); Malformed {text:} for text that is not a well-formed tag; UnknownSubtag {subtag:} for a well-formed tag with an unregistered subtag (xx).

assert Locale.parse("zh-hant-hk") == Ok(Locale"zh-Hant-HK")
assert Locale.parse("in") == Ok(Locale"id")
assert Locale.parse("sh") == Ok(Locale"sr-Latn")
assert Locale.parse("pt_BR") == Err(Error.Underscore{suggestion: "pt-BR"})
assert Locale.parse("") == Err(Error.Empty)
assert Locale.parse("en--US") == Err(Error.Malformed{text: "en--US"})
assert Locale.parse("xx") == Err(Error.UnknownSubtag{subtag: "xx"})
fn from_posix(value: String) -> Result<Locale, Error>

type function on Locale

Read a POSIX locale value, as LANG and LC_ALL hold it (language[_territory][.codeset][@modifier]). The codeset is dropped; @latin, @cyrillic and @devanagari become the script and @valencia the variant, and any other modifier (@euro) is dropped. C and POSIX, with or without a codeset, name no language, so they are und.

assert Locale.from_posix("pl_PL.UTF-8") == Ok(Locale"pl-PL")
assert Locale.from_posix("en_US@euro") == Ok(Locale"en-US")
assert Locale.from_posix("sr_RS@latin") == Ok(Locale"sr-Latn-RS")
assert Locale.from_posix("C") == Ok(Locale"und")
assert Locale.from_posix("POSIX") == Ok(Locale"und")
assert Locale.from_posix("C.UTF-8") == Ok(Locale"und")
fn language(locale: Locale) -> String

type function on Locale

The language subtag, und when the tag names none.

assert Locale.language(Locale"zh-Hant-HK") == "zh"
fn script(locale: Locale) -> Maybe<String>

type function on Locale

The script subtag the tag spells, if any. It never guesses a likely one.

assert Locale.script(Locale"zh-Hant-HK") == Maybe.Some("Hant")
assert Locale.script(Locale"pt-BR") == Maybe.None
fn region(locale: Locale) -> Maybe<String>

type function on Locale

The region subtag the tag spells, if any. It never guesses a likely one.

assert Locale.region(Locale"es-419") == Maybe.Some("419")
assert Locale.region(Locale"pl") == Maybe.None
fn fallbacks(locale: Locale) -> List<Locale>

type function on Locale

The chain locale data is looked up along, nearest first: the locale itself, the locale without its extensions when it has any, then its ancestors by CLDR’s parent locales, root (und) excluded.

A parent is the one CLDR’s parentLocales names, else the tag with its last subtag removed, so a parent is not always the shorter tag: es-MX goes to es-419 before es, en-GB and en-150 to en-001 before en, and pt-AO to pt-PT. Two rules refine truncation. A tag with a region and no script, whose region implies a different script than the language’s own, inherits from the language with that script (zh-TW goes to zh-Hant). A language-and-script tag whose script is not the language’s likely one has root as its parent (ru-Latn has no ancestor). So zh-Hant-HK never reaches zh.

assert Locale.fallbacks(Locale"es-MX") == [Locale"es-MX", Locale"es-419", Locale"es"]
assert Locale.fallbacks(Locale"en-150") == [Locale"en-150", Locale"en-001", Locale"en"]
assert Locale.fallbacks(Locale"pt-AO") == [Locale"pt-AO", Locale"pt-PT", Locale"pt"]
assert Locale.fallbacks(Locale"pt-BR") == [Locale"pt-BR", Locale"pt"]
assert Locale.fallbacks(Locale"zh-Hant-HK") == [Locale"zh-Hant-HK", Locale"zh-Hant"]
assert Locale.fallbacks(Locale"zh-TW") == [Locale"zh-TW", Locale"zh-Hant"]
assert Locale.fallbacks(Locale"ru-Latn") == [Locale"ru-Latn"]

assert Locale.fallbacks(Locale"de-CH-u-nu-latn") == [
    Locale"de-CH-u-nu-latn",
    Locale"de-CH",
    Locale"de",
]
fn negotiate(requested: List<Locale>, available: List<Locale>, default: Locale) -> Locale

type function on Locale

The locale in available that best serves a reader who asked for requested, in order of preference, by CLDR language matching; or default when none is close enough. A web framework parses Accept-Language into requested.

available = [Locale"en", Locale"pl", Locale"es"]
assert Locale.negotiate([Locale"pl-PL"], available, Locale"en") == Locale"pl"
assert Locale.negotiate([Locale"de", Locale"es-MX"], available, Locale"en") == Locale"es"
assert Locale.negotiate([Locale"ja"], available, Locale"en") == Locale"en"
fn available() -> List<Locale>

type function on Locale

The locales the program carries CLDR data for: those its nomi.toml lists under [i18n].locales, in that order, or every locale CLDR has data for when it lists none. A locale outside them still formats, as its nearest listed parent, else as the source locale ([i18n].source_locale) when the program lists it, else as CLDR’s root.

assert Iter.contains(Locale.available(), Locale"pl")
fn loaded() -> List<Locale>

type function on Locale

The locales whose data the program has now: Locale.available(), less those a browser build keeps in locale files that Locale.load has not loaded yet. Anywhere but a browser build that is every available locale.

assert Locale.loaded() == Locale.available()
fn load(locale: Locale) -> Result<Unit, LoadError>

type function on Locale

Make locale ready to format in. A site may offer many locales while each visitor reads one, so a browser build (nomi build --web) compiles only the locales [i18n].web_embedded names into app.wasm, the source locale unless it says otherwise, and keeps each other listed locale in a file beside it: locales/pl.nomil holds Polish numbers, dates and lists and the Polish translations. load fetches the files of the locales on locale’s fallback chain that are not loaded yet, and the calling task waits until they arrive or fail; the program runs in a worker, so the rest of the page keeps working. A file another build wrote, such as one a browser cached from the last deploy, is refused, since its text may not fit the new program. Anywhere else the program carries every listed locale, and load returns Ok(Unit) at once, as it does for a locale already loaded or one the program does not list.

# nomi.toml
[i18n]
locales = ["en", "pl", "de"]
web_embedded = ["en"]

Until its file is loaded, a locale formats as its nearest loaded ancestor, else as the source locale, with the source text and the source locale’s numbers and dates: a safety net, not a way to show a page. Load the reader’s locale before formatting in it, so a page is never half in one language:

fn choose_language(locale: Locale) -> Result<Unit, LoadError>
    Locale.load(locale)?
    with App.locale = locale
    render_page()
    Ok(Unit)
end
assert Locale.load(Locale"pl") == Ok(Unit)

impl Literal for Locale

fn from_fragments(fragments: List<Fragment<String>>) -> Result<Locale, Error>

impl Literal.from_fragments

Locale"pt-BR" is the locale Locale.parse gives for its text. A literal without slots is checked when the program is checked, so a malformed tag is a compile error at the literal, worded by Error’s Display: typed literal Locale"pt_BR" is invalid: a locale tag separates subtags with `-`, not `_`: write `pt-BR` (Locale.from_posix reads a POSIX value).

In a program that lists its locales ([i18n].locales and partial_locales), a literal whose locale’s fallback chain reaches none of them is a compile error too, since the program would never format in it: with en and de listed, typed literal Locale"fr": `fr` is not one of this program's locales (`en`, `de` in nomi.toml's [i18n]): add it there, or format in one of them. Locale"de-CH" is valid there, as is any literal in a program that lists no locales. A locale the program only compares or negotiates is parsed while it runs (Locale.parse("fr")), which no check refuses.

impl Display for Locale

fn to_string(locale: Locale) -> String

impl Display.to_string

The canonical BCP 47 tag.

impl Debug for Locale

fn inspect(locale: Locale) -> String

impl Debug.inspect

The typed literal that builds the locale.

impl Equatable for Locale

fn equal(a: Locale, b: Locale) -> Bool

impl Equatable.equal

impl Hashable for Locale

fn hash(value: Locale) -> Int

impl Hashable.hash

enum Error
    Empty
    Underscore { suggestion: String }
    Malformed { text: String }
    UnknownSubtag { subtag: String }
end

Why text is not a locale tag.

Variants

  • Empty

    The text is empty.

  • Underscore

    The text separates subtags with _, as a POSIX value does. suggestion is the tag written with -.

  • Malformed

    text is not a well-formed BCP 47 tag.

  • UnknownSubtag

    The tag is well-formed, but subtag is not a registered subtag.

impl Display for Error

fn to_string(e: Error) -> String

impl Display.to_string

What is wrong, as a compile error at a Locale"…" literal shows it.

assert Display.to_string(
    Error.Underscore{suggestion: "pt-BR"}
) == "a locale tag separates subtags with `-`, not `_`: write `pt-BR` (Locale.from_posix reads a POSIX value)"

assert Display.to_string(Error.UnknownSubtag{subtag: "xx"})
    == "`xx` is not a known language, script or region subtag"

impl Debug for Error

fn inspect(value: Error) -> String

impl Debug.inspect

impl Equatable for Error

fn equal(a: Error, b: Error) -> Bool

impl Equatable.equal

enum LoadError
    Unreachable { locale: Locale, reason: String }
    Unreadable { locale: Locale, reason: String }
end

Why Locale.load could not make a locale ready. locale is the locale whose file it is: the one asked for, or an ancestor on its fallback chain.

Variants

  • Unreachable

    The file could not be fetched: the network failed, or the host does not serve it.

  • Unreadable

    The file arrived and is not one this program can read: another build wrote it, as a browser may cache from the last deploy, or it is not a locale file.

impl Display for LoadError

fn to_string(e: LoadError) -> String

impl Display.to_string

What failed, naming the locale.

assert Display.to_string(LoadError.Unreachable{locale: Locale"pl", reason: "HTTP 404"})
    == "the locale file of pl could not be fetched: HTTP 404"

impl Debug for LoadError

fn inspect(value: LoadError) -> String

impl Debug.inspect

impl Equatable for LoadError

fn equal(a: LoadError, b: LoadError) -> Bool

impl Equatable.equal