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.
Exports
Section titled “Exports”How code gets a locale
Section titled “How code gets a 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
Section titled “type Locale”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\""
Locale.parse
Section titled “Locale.parse”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"})
Locale.from_posix
Section titled “Locale.from_posix”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")
Locale.language
Section titled “Locale.language”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"
Locale.script
Section titled “Locale.script”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
Locale.region
Section titled “Locale.region”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
Locale.fallbacks
Section titled “Locale.fallbacks”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",
]
Locale.negotiate
Section titled “Locale.negotiate”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"
Locale.available
Section titled “Locale.available”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")
Locale.loaded
Section titled “Locale.loaded”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()
Locale.load
Section titled “Locale.load”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)
Locale.from_fragments
Section titled “Locale.from_fragments”impl Literal for Locale
fn from_fragments(fragments: List<Fragment<String>>) -> Result<Locale, Error>
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.
Locale.to_string
Section titled “Locale.to_string”impl Display for Locale
fn to_string(locale: Locale) -> String
impl Display.to_string
The canonical BCP 47 tag.
Locale.inspect
Section titled “Locale.inspect”impl Debug for Locale
fn inspect(locale: Locale) -> String
impl Debug.inspect
The typed literal that builds the locale.
Locale.equal
Section titled “Locale.equal”impl Equatable for Locale
fn equal(a: Locale, b: Locale) -> Bool
impl Equatable.equal
Locale.hash
Section titled “Locale.hash”impl Hashable for Locale
fn hash(value: Locale) -> Int
impl Hashable.hash
enum Error
Section titled “enum Error”enum Error Empty Underscore { suggestion: String } Malformed { text: String } UnknownSubtag { subtag: String } end
Why text is not a locale tag.
Variants
-
EmptyThe text is empty.
-
UnderscoreThe text separates subtags with
_, as a POSIX value does.suggestionis the tag written with-. -
Malformedtextis not a well-formed BCP 47 tag. -
UnknownSubtagThe tag is well-formed, but
subtagis not a registered subtag.
Error.to_string
Section titled “Error.to_string”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"
Error.inspect
Section titled “Error.inspect”impl Debug for Error
fn inspect(value: Error) -> String
impl Debug.inspect
Error.equal
Section titled “Error.equal”impl Equatable for Error
fn equal(a: Error, b: Error) -> Bool
impl Equatable.equal
enum LoadError
Section titled “enum LoadError”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
-
UnreachableThe file could not be fetched: the network failed, or the host does not serve it.
-
UnreadableThe 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.
LoadError.to_string
Section titled “LoadError.to_string”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"
LoadError.inspect
Section titled “LoadError.inspect”impl Debug for LoadError
fn inspect(value: LoadError) -> String
impl Debug.inspect
LoadError.equal
Section titled “LoadError.equal”impl Equatable for LoadError
fn equal(a: LoadError, b: LoadError) -> Bool
impl Equatable.equal