Skip to content

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.

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.

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:

FunctionParameter typeOptions
:integerIntselect, useGrouping, minimumIntegerDigits
:number, :percentInt, Float, Decimalthose, minimumFractionDigits, maximumFractionDigits
:stringString, an enum whose variants carry nothingnone
:currencyMoney (std::money)currencyDisplay (symbol, narrowSymbol, code, name)
:dateDate, NaiveDateTime, DateTimestyle (full, long, medium when left out, short)
:timeTime, NaiveDateTime, DateTimestyle (short when left out)
:datetimeDate, Time, NaiveDateTime, DateTimedateStyle, timeStyle, or the fields weekday, era, year, month, day, hour, minute, second, fractionalSecondDigits, with hourCycle
:nomi:nounNouncase (a case of the locale’s language, nominative when left out), count (a whole number or an Int parameter, 1 when left out)
:nomi:genderNounnone
:nomi:listList<String>none
:nomi:weekdayDate (std::calendar)none
  • select is plural (the default), ordinal or exact; useGrouping is auto, always, never or min2.
  • :currency writes an amount as Money.format does. :date and :time write a value at a style, and :datetime at its dateStyle and timeStyle or by the fields its options name, as a skeleton (weekday=long month=long day=numeric is MMMMEEEEd; hour=numeric is j, which hourCycle makes h or H); with neither, it writes the date at medium and the time at short. 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:list writes the list as String.join_list does in the locale, and selects by its length as a plural selector of an Int does.
  • :nomi:weekday only selects, by the date’s day of the week. Its keys are monday through sunday, and a selector that names one day needs all seven. A placeholder that writes it is en: `:nomi:weekday` selects by the day of the week and writes nothing.

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

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.

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.

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.

impl Debug for Phrase

fn inspect(phrase: Phrase) -> String

impl Debug.inspect

The phrase’s name and its arguments.

impl Equatable for Phrase

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

impl Equatable.equal

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.

impl Equatable for Noun

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

impl Equatable.equal

impl Debug for Noun

fn inspect(noun: Noun) -> String

impl Debug.inspect

The noun’s qualified name, shop.book.

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

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.

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
fn locale(catalog: Catalog) -> Locale

type function on Catalog

The locale the catalog translates into.

impl Debug for Catalog

fn inspect(value: Catalog) -> String

impl Debug.inspect

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.

impl Debug for Rejected

fn inspect(value: Rejected) -> String

impl Debug.inspect

impl Equatable for Rejected

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

impl Equatable.equal