Reference · Translations

translations

translations(str | map, map | null=) -> null

What it does

Declares the program's translations, at the top of the program, for t and locale. A folder name reads <dir>/<locale>.json, one JSON object per locale, the locale named as en, pt-BR or zh-Hant; a map takes the text directly, { en: {...}, fr: {...} }. Nested maps become dotted keys (nav.home), and a map whose keys are plural forms (zero one two few many other, with other present) is one entry chosen by count. The default locale is the option { default: "en" }, else en when there is one, else the first locale by name; a key missing in a locale comes from it.

Examples

translations({    en: { nav: { home: "Home" }, items: { one: "{count} item", other: "{count} items" } },    fr: { nav: { home: "Accueil" }, items: { one: "{count} article", other: "{count} articles" } },})print(locale(), t("nav.home"), t("items", { count: 2 }))print(with_locale("fr", () => t("items", { count: 2 })))

en Home 2 items2 articles

translations("locales")                     // locales/en.json, locales/fr.json, locales/pt-BR.jsontranslations("locales", { default: "fr" })

Edge cases

• Without en and without a default given, the first locale is the default: the first written in a map, the first by name in a folder. The default's name is matched without regard to case.
• Calling it again replaces the translations; the last call counts.
• A plural map needs other; a map with one alone is nested keys (n.one), not a plural entry.
• A folder path is relative to the program's folder and must stay inside it. A file named with _ (fr_FR.json) is read as fr-FR, and a byte-order mark at a file's start, as Windows editors save one, is skipped.
• Plural forms are picked by CLDR 47's rules for the number as {count} shows it, the same on the server and in the browser (see t).
• It gives null.

translations({ fr: { a: "fr" }, de: { a: "de" } })print(locale())translations({ fr: { a: "fr" }, de: { a: "de" } }, { default: "FR" })print(locale(), t("a"))translations({ en: { n: { one: "one" } } })print(t("n", { count: 1 }), t("n.one"))print(translations({ en: { a: "b" } }))

frfr frn onenull

Errors

A bad declaration is a runtime error, not an error value: a locale name that is not one, a locale that is not a map, an entry that is not text or a map, plural forms that are not text, no locales at all, a default that is not among them, a folder that cannot be read or that leaves the program's folder.

translations({ english: { a: "b" } })

line 1: `translations`: "english" is not a locale name such as "en" or "pt-BR"

translations({ en: { a: 1 } })

line 1: `translations` (en): `a` must be text or a map, not int

translations({ en: { a: "b" } }, { default: "fr" })

line 1: `translations`: the default "fr" is not among the locales

translations("../locales")

line 1: `translations` needs a folder inside the program's, got "../locales"

Chaining

It is a declaration, not a value: call it once at the top of the program, before the routes. t, locale and with_locale then work in any function a request runs, and in components, which carry their locale's text to the browser.

translations("locales")locale_from((request) => request.query.lang)route GET / = <h1>{t("welcome")}</h1>

See also

t, locale, locale_from, with_locale

Edit this page on GitHub · every example's output was made by running it (tools/refcheck.mjs) · questions on Discord or r/quillo