How-to

Website

Web app

Desktop / phone

Translate a site

Show a site in the reader's language: one file of messages per locale, t("key") wherever text goes, and a switch that changes the language on the spot, right to left included. To start a new project this way, see Start a project translated. This program has a language picker in its navigation bar and a home page whose heading, count and button are translated. It reads the translation files that Set up the translation files shows:

Needs: the i18n setting and the translation files that Set up the translation files shows. The code is a whole project's app and home page, and declares type User, as the starter does: paste it into a new project, replacing src/App.wf and src/pages/Home.wf.

wf

type User { name: String } app { state chosen = locale Navbar { Navbar.Brand { Link("i18n", to: "/") } Navbar.Links { Link(t("nav.home"), to: "/") Link(t("nav.about"), to: "/about") } Navbar.Actions { Select(bind: chosen, label: t("nav.language")) { on change { setLocale(chosen) } Select.Option("English", value: "en") Select.Option("العربية", value: "ar") Select.Option("Español", value: "es") } } } Router } page Home(path: "/", title: "Home", description: "The home page.") { state user = User(name: "Sam") state items: [String] = ["a", "b", "c"] Heading(t("welcome", { name: user.name })).h1 Text(t("items", { count: items.length })) Button(t("actions.save")).primary Text("Locale: {locale}, direction: {dir}") if locale == "ar" { Text("النسخة العربية") } } page About(path: "/about", title: "About", description: "About the site.") { Heading(t("nav.about")).h1 }

How it works

Set up the translation files

List the site's locales in webfluent.app.json under i18n. default_locale names the language the site is written in, and dir the directory that holds the files:

json

{ "i18n": { "default_locale": "en", "locales": ["en", "ar", "es"], "dir": "src/translations" } }

Then put one file per locale in that directory — en.json, ar.json, es.json. Each is a flat map of keys to messages; by convention a key has dots in it to group related messages. This is src/translations/en.json:

json

{ "nav.home": "Home", "nav.about": "About", "nav.language": "Language", "welcome": "Welcome, {name}!", "items.one": "{count} item", "items.other": "{count} items", "actions.save": "Save" }

And this is src/translations/ar.json, with the six plural forms Arabic uses:

json

{ "nav.home": "الرئيسية", "nav.about": "حول", "nav.language": "اللغة", "welcome": "أهلاً، {name}!", "items.zero": "لا عناصر", "items.one": "عنصر واحد", "items.two": "عنصران", "items.few": "{count} عناصر", "items.many": "{count} عنصراً", "items.other": "{count} عنصر", "actions.save": "حفظ" }

And src/translations/es.json. Spanish has a third form, many, for a round million and more (1 000 000 de elementos):

json

{ "nav.home": "Inicio", "nav.about": "Acerca de", "nav.language": "Idioma", "welcome": "¡Bienvenido, {name}!", "items.one": "{count} elemento", "items.many": "{count} de elementos", "items.other": "{count} elementos", "actions.save": "Guardar" }

A locale with no file, and a key one locale has and another lacks, are build warnings (I03). At run time a key missing from the reader's locale falls back to the default locale's message, and only then to the key itself.

Translate text with t()

To show a message in the reader's language, call t("key") wherever a string goes, as Home does above. Pass a map as the second argument to fill placeholders and to pick a plural form.

In English the home page reads Welcome, Sam!, 3 items and a Save button; in Arabic, أهلاً، Sam!, 3 عناصر and حفظ.

How t() behaves:

  • It follows the locale. t("key") is the message for the current locale, and every call is evaluated again when the locale changes.
  • It fills placeholders. t("key", { name: value }) replaces each {name} in the message with the map's value.
  • A count picks the plural form. The form comes from the locale's CLDR plural rules, which the browser's Intl.PluralRules follows too: Arabic has zero, one, two, few, many and other; English has one and other; Japanese has only other. A count of exactly 0 uses key.zero wherever the file has one, in any language, so English can say "No files" rather than "0 files". Without the form it wants, t() falls back to key.other, then to key.
  • A key's forms all come from one language — the reader's, when its file has the key at all, otherwise the default locale's. It never mixes one form from each.
  • The pre-rendered page is already translated. The build resolves t for the default locale when it pre-renders a page, by the same rules, so the HTML is in the default language, its counts in that language's forms.

Warning

Never build a sentence from pieces (t("greeting") + name). Word order differs between languages. Put a placeholder in the message, so a translator can move it.

Switch the locale

To let the reader change language, call setLocale(code). The app above puts a language picker in the navigation bar, and Home shows the current locale and direction.

locale is the current locale's code, and dir is "ltr" or "rtl". An app block may declare state as a page does, as chosen is above. It starts as locale, so a reader who chose Arabic on an earlier visit finds العربية already selected.

On a switch, the runtime sets <html lang> and <html dir>. A locale is right to left when its language is: Arabic, Hebrew, Persian, Urdu, Pashto, Sindhi, Central Kurdish, Uyghur, Yiddish, Dhivehi, Kashmiri, Syriac, Aramaic and N'Ko — with any region, so ar-EG is too. A site whose default locale is one of them is written <html lang="ar" dir="rtl"> from the start, before any script runs.

meta.lang may name a region of the default locale's language (en-GB for en); otherwise the default locale is the page's language.

The built-ins use logical CSS properties (margin-inline-start, not margin-left), so their layouts mirror with no work on your side. Use logical properties in your own style { } blocks too.

Choose the locale a page opens in

A page opens in default_locale, with two exceptions:

  1. The address names a locale. ?lang=<code>, for one of the configured locales, opens the page in it: /about?lang=ar is the Arabic page, for a link you share. It does not change the reader's kept choice. It is not an address a search engine indexes: its HTML, and its canonical link, are the default locale's, so the build lists no ?lang= address as an hreflang alternate. To have each language found, give it pages of its own (A page in its own language).
  2. The reader chose a locale before. setLocale(code) keeps the code in the reader's localStorage, under wf:locale, and every page loaded after that opens in it, on this visit and the next. Choosing default_locale again forgets it.

So a static site, which loads each page afresh, keeps the reader's language from page to page, and a language switch can be a pair of buttons:

wf

app { Navbar { Navbar.Brand { Link("i18n", to: "/") } Navbar.Actions { Button("English") { on click { setLocale("en") } } Button("العربية") { on click { setLocale("ar") } } } } Router }

The runtime does not guess from the browser's language. Nothing is kept until the reader chooses, so a first visit gets the ?lang= locale or the default, and a search engine's crawler the default. To start a first visit in the browser's language, keep whether the reader has chosen in a store with persist, and until they have, call setLocale(navigator.language.slice(0, 2)) from an effect in the app.

A static build pre-renders every page once, in the default locale; another locale is applied as the page loads. So a search engine indexes only the default locale's text. For each language to be found, give it pages of its own (A page in its own language).

Format numbers and dates for the locale

format and ago follow the current locale (Expressions). format(1234.5, .currency, "EUR") is €1,234.50 in en and 1.234,50 € in de; ago(date) says "il y a 3 jours" in fr. The pre-rendered page uses a table of the common locales' separators and currency symbols, and the live page uses the browser's Intl and corrects any difference.

To choose the digits a locale writes, add the Unicode extension to its code:

  • setLocale("ar-u-nu-arab") reads the ar table and writes format — a date pattern too, its AM/PM in the locale's words — ago and every count in Arabic-Indic digits (١١ ملفًا).
  • setLocale("ar-u-nu-latn") writes them in 0–9, whatever the browser's Arabic would pick.
  • Bare ar leaves the digits to the browser.

A count is prose, so it takes the locale's digits. Another number spliced into a message — a line number, a version — stays as it is. The document's lang is the language, ar, whatever digits the code names.

Translate long-form text

For a paragraph or a page of prose:

  • Under "literals": true, Markdown("…") written in place is words like any other text: its whole source, ** and all, is the key.
  • Text inside a .md page is not passed through t. Keep one Markdown file per locale, each with its own path, lang and translates in its front matter, or keep the text in the translation file under a key and render Markdown(t("about.body")).

Start a project translated

To begin a new project in several languages, pass --locales to wf init, with the default locale first:

bash

$ wf init my-app --locales en,ar

This works for the spa and static templates. The new project has:

  • the i18n config above, and meta.lang set to the default locale;
  • every visible string of the starter passed through t("…");
  • a language switch with one entry per locale;
  • a file for each locale in src/translations/. The default locale's holds the starter's English, which its pages and tests are written in. Arabic holds the starter's Arabic. Any other locale starts as a copy of the English, for you to translate.

Each locale is a language tag (en, ar, pt-BR). --locales ar,en makes Arabic the default, so the page is right to left from the first paint. From Rust, the same is webfluent::init::create_with(dir, name, &Options { template, locales }).

Check what each locale lacks

To see the translations as a table, run wf translations:

bash

$ wf translations $ wf translations --missing ar $ wf translations --unused $ wf translations --plurals
Check what each locale lacks
Command What it prints

wf translations

Each locale, the plural forms its rules use, and how many keys it lacks, a form it lacks, or a placeholder that differs from the default locale's

--missing ar

What Arabic lacks

--unused

The keys nothing names

--plurals

CLDR's plural rules: every locale's forms

--json

The whole table: each key with its message in every locale, and every place a t() names it

From Rust the table is webfluent::i18n::table (with the internals feature, outside semver), which can also write one message back into its file with every other byte as it was.

Checklist

  • Every visible string goes through t, including label:, placeholder: and aria-label: values.
  • No sentence is built from parts (t("x") + name); a placeholder lets a translator reorder it.
  • Every count has its plural forms, even in English, and a zero where "none" reads better as a sentence.
  • wf translations --missing <locale> lists nothing for any locale.
  • You have tried the site once in a right-to-left locale, and checked:
  • alignment, and icons that imply a direction (arrows);
  • any left or right in your own CSS;
  • a Latin code or figure inside Arabic text, which needs a left-to-right run of its own (direction: ltr; unicode-bidi: isolate) to keep its parts in order.
  • If each language should be found by search, each has pages of its own, with lang: and translates:, and wf check reports no R05.