std::phrase
Phrases: text a person reads, declared once in the program’s source
language and translated in catalogs. A phrase declaration names a
phrase, its typed parameters and its MessageFormat 2 text:
pub phrase cart_items(count: Int) ` .input {$count :integer} .match $count one {{{$count} item in your cart}} * {{{$count} items in your cart}} `
Each translation is an entry of a catalog, a TOML file per locale beside
the declaring file under [i18n].catalogs, which the compiler checks
against the declaration: every listed locale has one, it uses only the
parameters, its plural arms are the ones the locale’s rules need, and it
was translated from the current text. The declaration is a function that
returns a Phrase, which holds which phrase and its arguments and is
formatted in a locale later, with Phrase.format.
A noun declaration names a thing a phrase talks about, in the source
language, as a Noun:
pub noun book `.input {$count :integer} .match $count one {{book}} * {{books}}`
Its translation in each catalog gives its grammatical gender, where
the language has genders, and a form per grammatical case. A phrase
writes it with :nomi:noun and chooses words that agree with it with
:nomi:gender, and the compiler checks that every noun has each form a
phrase asks for and every phrase an arm for each gender the program’s
nouns have.
A translation can choose its words by the day of the week of a Date
with :nomi:weekday, whose keys are monday to sunday. It only
chooses: a placeholder that writes it is an error, and a .match that
names one day names all seven. Polish says “on Wednesday” as “w środę”,
the preposition “w” and then the weekday, but writes “we” before
“wtorek” (Tuesday), since “w wtorek” is hard to say:
[ships_on] source = '''Ships {$date :datetime weekday=long month=long day=numeric}''' text = ''' .local $day = {$date :nomi:weekday} .match $day monday {{Wysyłka w poniedziałek, {$date :datetime month=long day=numeric}}} tuesday {{Wysyłka we wtorek, {$date :datetime month=long day=numeric}}} wednesday {{Wysyłka w środę, {$date :datetime month=long day=numeric}}} thursday {{Wysyłka w czwartek, {$date :datetime month=long day=numeric}}} friday {{Wysyłka w piątek, {$date :datetime month=long day=numeric}}} saturday {{Wysyłka w sobotę, {$date :datetime month=long day=numeric}}} sunday {{Wysyłka w niedzielę, {$date :datetime month=long day=numeric}}} * {{Wysyłka: {$date :datetime weekday=long month=long day=numeric}}} '''
October 20, 2026 is a Tuesday, so it reads “Wysyłka we wtorek, 20 października”, and the next day “Wysyłka w środę, 21 października”.
Import with import std::phrase.
Exports
Section titled “Exports”Catalogs
Section titled “Catalogs”Each translation is an entry in a catalog, a TOML file per locale for each
declaring file, under the directory [i18n].catalogs names
(where the files go). An entry is a table named
by the phrase, holding text, the translation, and source, the source
text it was translated from:
# locales/pl/cart.toml [cart_items] source = ''' .input {$count :integer} .match $count one {{{$count} item in your cart}} * {{{$count} items in your cart}} ''' text = ''' .input {$count :integer} .match $count one {{{$count} produkt w koszyku}} few {{{$count} produkty w koszyku}} many {{{$count} produktów w koszyku}} * {{{$count} produktu w koszyku}} '''
A catalog holds comments, tables with bare or quoted names, and the two
keys as strings of any TOML kind; ''' strings need no escaping of MF2’s
braces. [i18n] names the locales: locales must each have every
phrase, and partial_locales may leave any out.
Functions in a text
Section titled “Functions in a text”A text formats with the stable MF2 functions, the draft date and time
ones, and four of Nomi’s own in MF2’s nomi: namespace. The compiler
checks each placeholder’s parameter type and options against this table:
| Function | Parameter type | Options |
|---|---|---|
:integer | Int | select, useGrouping, minimumIntegerDigits |
:number, :percent | Int, Float, Decimal | those, minimumFractionDigits, maximumFractionDigits |
:string | String, an enum whose variants carry nothing | none |
:currency | Money (std::money) | currencyDisplay (symbol, narrowSymbol, code, name) |
:date | Date, NaiveDateTime, DateTime | style (full, long, medium when left out, short) |
:time | Time, NaiveDateTime, DateTime | style (short when left out) |
:datetime | Date, Time, NaiveDateTime, DateTime | dateStyle, timeStyle, or the fields weekday, era, year, month, day, hour, minute, second, fractionalSecondDigits, with hourCycle |
:nomi:noun | Noun | case (a case of the locale’s language, nominative when left out), count (a whole number or an Int parameter, 1 when left out) |
:nomi:gender | Noun | none |
:nomi:list | List<String> | none |
:nomi:weekday | Date (std::calendar) | none |
selectisplural(the default),ordinalorexact;useGroupingisauto,always,neverormin2.:currencywrites an amount asMoney.formatdoes.:dateand:timewrite a value at a style, and:datetimeat itsdateStyleandtimeStyleor by the fields its options name, as a skeleton (weekday=long month=long day=numericisMMMMEEEEd;hour=numericisj, whichhourCyclemakeshorH); with neither, it writes the date atmediumand the time atshort. A field the value lacks is an error at the option,en: `hour` names a time of day, and `$day` is a `Date`, which has none, and so are styles beside fields. None of these selects:en: `:date` writes a calendar value and selects nothing, whose help points to:nomi:weekday.:nomi:listwrites the list asString.join_listdoes in the locale, and selects by its length as a plural selector of anIntdoes.:nomi:weekdayonly selects, by the date’s day of the week. Its keys aremondaythroughsunday, and a selector that names one day needs all seven. A placeholder that writes it isen: `:nomi:weekday` selects by the day of the week and writes nothing.
Formatting
Section titled “Formatting”Phrase.format writes the text of the requested locale when the program
has one, else that of the nearest locale on its CLDR fallback chain that
has one, else the source text, so an unlisted locale shows the source.
Numbers are written with the requested locale’s symbols and patterns, and
plural categories are its rules’, from the CLDR data the program carries.
In a right-to-left locale each placeholder is wrapped in Unicode isolates
(U+2068 and U+2069), as MF2 recommends. Each phrase’s texts are stored in
the function it declares, so a program carries the texts of the phrases
it reaches and no others.
Plural categories are selected by the reader’s locale’s rules when the
text is a translation into its language (pt’s text read in pt-PT
selects by pt-PT’s rules), and by the text’s own language’s otherwise,
since its arms are keyed by that language’s categories (an unlisted fr
reads the English text by English rules). A noun is written in the locale
of the phrase’s text: its entry there, or the nearest listed ancestor’s,
else its source form.
Two pseudo-locales need no catalog: Locale"en-XA" writes the source
text accented, bracketed and about a third longer ([3 îţéɱš îñ ýöûŕ çåŕţ one two]), and Locale"ar-XB" writes it mirrored right to left, so
text that was not declared as a phrase stands out and layouts are tried
at another length and direction.
struct Phrase
Section titled “struct Phrase”struct Phrase
opaque — construction surface is private to its defining module
A phrase with its arguments, in no locale yet: what a phrase
declaration’s function returns. Libraries hand one to whoever knows the
reader’s locale, which formats it with Phrase.format. Two phrases are
equal when they are the same declaration with equal arguments.
Phrase.format
Section titled “Phrase.format”fn format(phrase: Phrase, locale: Locale, catalogs: List<Catalog> = []) -> String
type function on Phrase
The phrase’s text in locale: the translation the program’s
catalogs give for it, or for the nearest locale it falls back to,
or the declaration’s own text, with the arguments formatted as the
locale writes them. en-XA and ar-XB are pseudo-locales: the
source text accented, padded and bracketed, and mirrored right to
left, for finding text a program does not translate.
catalogs are catalogs loaded while the program runs
(Catalog.load). At each locale of the fallback chain the first of
them for that locale with an entry for the phrase gives its text,
before the program’s own; a phrase none of them translates keeps
its compiled text, as does one whose entry Catalog.load rejected. A
phrase that is an argument of this one is formatted with the same
catalogs.
Phrase.localize
Section titled “Phrase.localize”impl Localize for Phrase
fn localize(phrase: Phrase, locale: Locale) -> String
impl Localize.localize
A phrase formats in a locale as Phrase.format does, so a phrase
that is the argument of another is formatted in the same locale.
Phrase.inspect
Section titled “Phrase.inspect”impl Debug for Phrase
fn inspect(phrase: Phrase) -> String
impl Debug.inspect
The phrase’s name and its arguments.
Phrase.equal
Section titled “Phrase.equal”impl Equatable for Phrase
fn equal(a: Phrase, b: Phrase) -> Bool
impl Equatable.equal
struct Noun
Section titled “struct Noun”struct Noun
opaque — construction surface is private to its defining module
A thing a phrase talks about, such as a product category: what a
noun declaration names. It holds the noun’s forms in each locale and
its gender where the language has genders, which a phrase reads with
:nomi:noun and :nomi:gender. A Noun is made only by a declaration,
so the compiler knows every noun of a program and holds every phrase to
them; a name read at run time, such as a product’s title from a
database, is a String, which a phrase writes with {$title} but
cannot agree with. Two nouns are equal when they are the same
declaration.
A noun’s entry in a catalog gives the source it was translated from,
its gender where the language’s nouns have one, and a form per
grammatical case, each MessageFormat 2 text over $count. The genders
and cases a language has come from CLDR. Polish splits the masculine
three ways, personal for people, animate for animals and inanimate
for things such as a laptop, beside feminine and neuter, and has
seven cases. The nominative is the plain form, “książka” (book), and
the genitive is the form after “brak” (no … left), “Brak książek”. A
form that never changes, such as “etui” (phone case), is plain text with
no .match. English has no genders and no cases, so an English noun
has only the declaration’s text.
[book] source = '''.input {$count :integer} .match $count one {{book}} * {{books}}''' gender = "feminine" nominative = '''.input {$count :integer} .match $count one {{książka}} few {{książki}} many {{książek}} * {{książki}}''' genitive = '''.input {$count :integer} .match $count one {{książki}} few {{książek}} many {{książek}} * {{książki}}''' [phone_case] source = '''.input {$count :integer} .match $count one {{phone case}} * {{phone cases}}''' gender = "neuter" nominative = '''etui''' genitive = '''etui'''
A phrase writes a noun with {$product :nomi:noun}: case= picks the
form and count= how many, so {$product :nomi:noun case=genitive count=5} is “książek”. .input {$product :nomi:gender} lets .match
choose a variant by the noun’s gender, as “Twoja książka została
wysłana” and “Twoje etui zostało wysłane” need.
A phrase can be given any noun the program declares, so the compiler
holds every noun to every phrase, in each locale: every noun has a
gender the language has; every noun has each form some phrase asks
for, so adding a phrase that writes case=genitive means every Polish
noun needs a genitive; and a .match on gender has a variant for every
gender the program’s nouns have. Declaring a personal noun such as
“kurier” (courier) anywhere in the program makes a phrase that matches
on gender without a personal variant an error:
pl: `has_shipped` has no `personal` arm; the noun `staff.courier` is personal in Polish.
The editor shows a noun’s gender and forms on hover, completes genders
and cases in a catalog, and adds a form a noun lacks as a quick fix.
Noun.equal
Section titled “Noun.equal”impl Equatable for Noun
fn equal(a: Noun, b: Noun) -> Bool
impl Equatable.equal
Noun.inspect
Section titled “Noun.inspect”impl Debug for Noun
fn inspect(noun: Noun) -> String
impl Debug.inspect
The noun’s qualified name, shop.book.
Noun.localize
Section titled “Noun.localize”impl Localize for Noun
fn localize(noun: Noun, locale: Locale) -> String
impl Localize.localize
The noun’s nominative for one thing in locale, or in the nearest
locale its catalogs translate it into, else the source’s: what a
placeholder with no function writes.
struct Catalog
Section titled “struct Catalog”struct Catalog
opaque — construction surface is private to its defining module
Translations loaded while the program runs, for one locale: a catalog a
translation service serves, say, so that a fixed translation needs no
new build. Phrase.format reads them before the program’s own
catalogs. Those stay the source of truth: a loaded catalog only
translates the phrases and nouns the program has, into a locale it
lists.
Catalog.load
Section titled “Catalog.load”fn load(text: String, locale: Locale) -> (Catalog, List<Rejected>)
type function on Catalog
The catalog text holds for locale, and each entry it rejects.
text is a catalog’s TOML, as the program’s own catalogs are
written, with each table naming a phrase or noun by its file:
[cart.cart_items], holding its source and text. The table names
its file because one loaded catalog can hold the phrases of every
file, where each of the program’s own catalogs holds one file’s.
Each entry is checked against the program’s compiled phrases and
nouns as the compiler checks a catalog: it names a phrase or noun
the program uses (`cart.ghost` is not a phrase or noun the program uses), in a locale [i18n] lists other than the source
locale; its keys are a phrase’s or a noun’s; it records the
declaration’s current text as its source, so a stale entry is
rejected in every locale; its text is valid MessageFormat 2 that
reads only the phrase’s parameters, with the types, plural arms and
enum arms its signature and the locale’s rules need; and its nouns
and phrases agree with the program’s in that locale (a loaded noun
has every form a phrase there asks for, and a loaded phrase an arm
for every gender a noun there has). A rejected entry is never used:
its phrase keeps its compiled text, so a bad translation never
reaches a reader. Each rejection gives the first problem the compiler
would report about the entry, without the locale it starts with: a
Polish entry with no few variant is rejected with the reason
`cart_items` has no `few` arm; 2, 3 and 4 select `few` in Polish.
Completeness is not asked: a catalog may translate one phrase.
The checks read the declarations’ types as the compiler resolved them, which the program carries for each phrase it reaches, so an entry for a phrase the program never formats is rejected as one it does not use. Each catalog is checked against the compiled program, not against the other catalogs a call is handed.
Hand the catalog to Phrase.format as catalogs; a fixed
translation then needs no new build:
fn refresh(text: String) -> Catalog (catalog, rejected) = Catalog.load(text, Locale"pl") Iter.each(rejected, fn r -> io.print("${r.locale} ${r.key}: ${r.reason}")) catalog end fn badge(catalog: Catalog) -> String cart.cart_items(3) |> Phrase.format(Locale"pl", catalogs: [catalog]) end
Catalog.locale
Section titled “Catalog.locale”fn locale(catalog: Catalog) -> Locale
type function on Catalog
The locale the catalog translates into.
Catalog.inspect
Section titled “Catalog.inspect”impl Debug for Catalog
fn inspect(value: Catalog) -> String
impl Debug.inspect
struct Rejected
Section titled “struct Rejected”struct Rejected key: String locale: Locale reason: String end
An entry Catalog.load refused: its table’s name as the catalog writes
it (cart.cart_items, or "" for a problem outside any table), the
catalog’s locale, and why, in the words the compiler uses for the same
problem in a catalog it reads.
Rejected.inspect
Section titled “Rejected.inspect”impl Debug for Rejected
fn inspect(value: Rejected) -> String
impl Debug.inspect
Rejected.equal
Section titled “Rejected.equal”impl Equatable for Rejected
fn equal(a: Rejected, b: Rejected) -> Bool
impl Equatable.equal