Localization#

An app that speaks several languages needs more than a dictionary. "1 item" and "2 items" differ in English; Polish has four forms, Arabic six, and Japanese one. A message with a name in it is a method with a parameter, not a string with a hole. And when the user switches language, every piece of text on screen has to follow.

leptoskit handles this the way Flutter's gen_l10n does. Your messages live in one ARB file per locale, and leptoskit l10n writes src/l10n.rs from them: a Messages trait with one method per message, typed by the message's placeholders, implemented once per locale. A component reads its text through a reactive handle, so this is all a translated, pluralised, re-rendering label takes:

let l10n = use_l10n();
view! {
	<Text>{move || l10n.cart_items(count.get())}</Text>
}

A message that does not exist, a placeholder that is missing, or a number passed where a name belongs is a compile error, not a blank label in production. The module is ordinary Rust, so the same code runs on web, iOS, Android, macOS, Windows, Linux, and HarmonyOS (experimental); only where the user's preferred locales come from differs per platform, and that is covered below.

my_app/
├── leptoskit.toml          [l10n]
├── locales/
│   ├── en.arb              the template: every message, with its placeholders
│   ├── pt-BR.arb           a translation; messages it leaves out fall back to en
│   └── ar.arb
└── src/
    ├── lib.rs              mod l10n;
    └── l10n.rs             generated, committed

examples/postcard is a complete app built this way: a postcard in English, Polish, Arabic laid out right to left, Japanese, and a half-translated Brazilian Portuguese, with a gauge that shows the plural form each language picks for the same number.

Set up translations#

[dependencies]
leptoskit_l10n = "0.1"

[features]
web = ["leptoskit/web", "leptoskit_l10n/web"]

[l10n]
dir = "locales" # the ARB files, one per locale
output = "src/l10n.rs" # the generated module
template = "en" # the locale whose file defines every message

{
	"@@locale": "en",
	"appTitle": "Field Notes",
	"greeting": "Hello, {name}!",
	"@greeting": {
		"description": "Shown at the top of the home screen.",
		"placeholders": {
			"name": { "type": "String", "example": "Ana" }
		}
	},
	"cartItems": "{count, plural, =0 {Your cart is empty} one {# item in your cart} other {# items in your cart}}",
	"@cartItems": {
		"placeholders": {
			"count": { "type": "int" }
		}
	},
	"pronoun": "{gender, select, female {she} male {he} other {they}}"
}

leptoskit l10n

wrote src/l10n.rs
   en     en.arb     template, 4 messages
   pt-BR  pt-BR.arb  3 of 4 translated; missing pronoun
   appTitle   app_title() -> &'static str
   cartItems  cart_items(count: i64) -> String
   greeting   greeting(name: &str) -> String
   pronoun    pronoun(gender: &str) -> String

mod l10n;

leptoskit l10n --check

use leptoskit::prelude::*;
use leptoskit_l10n::Locale;

use crate::l10n::L10n;

#[component]
pub fn App(preferred: Vec<Locale>) -> impl IntoView {
	L10n::new(&preferred).provide();
	view! { <Home /> }
}

let preferred = leptoskit_l10n::browser_locales();

use leptoskit_l10n::accept_language;

let preferred = use_context::<http::request::Parts>()
	.and_then(|parts| {
		let header = parts.headers.get(http::header::ACCEPT_LANGUAGE)?;
		Some(accept_language(header.to_str().ok()?))
	})
	.unwrap_or_default();

use leptoskit_l10n::Locale;
use leptoskit_plugin_localization::guest::Localization;

let snapshot = Localization::new()?.snapshot().await?;
let preferred: Vec<Locale> = snapshot
	.locales
	.iter()
	.filter_map(|locale| Locale::new(&locale.tag).ok())
	.collect();

use leptoskit::prelude::*;

use crate::l10n::use_l10n;

#[component]
pub fn Cart(count: RwSignal<i64>) -> impl IntoView {
	let l10n = use_l10n();
	view! {
		<View class="gap-2 p-4">
			<Text class="text-2xl font-bold">{move || l10n.app_title()}</Text>
			<Text>{move || l10n.greeting("Ana")}</Text>
			<Text>{move || l10n.cart_items(count.get())}</Text>
		</View>
	}
}

use leptoskit::prelude::*;

use crate::l10n::use_l10n;

#[component]
pub fn LanguageMenu() -> impl IntoView {
	let l10n = use_l10n();
	view! {
		<View class="flex-row gap-2">
			{l10n
				.supported_locales()
				.iter()
				.map(|locale| {
					let tag = locale.to_string();
					let choice = locale.clone();
					view! {
						<Button on:press=move || l10n.set_locale(&choice)>{tag}</Button>
					}
				})
				.collect::<Vec<_>>()}
		</View>
	}
}

Writing messages#

A message is text with placeholders, plurals, and selects, in the subset of ICU MessageFormat that ARB files use.

Placeholders#

{name} in a message becomes a parameter. Its type comes from the template's @key entry, or from how the message uses it:

The description of an @key entry becomes the method's documentation, above the message's text. Other keys there, such as example, are for translators and translation tools; leptoskit leaves them alone. Parameters follow the order in which the template first uses them.

Plurals#

{count, plural, ...} picks a form by the number's CLDR plural category in the message's language. Name the forms the language has, zero, one, two, few, many, and always other; a number whose category has no form takes other. =0, =1, and so on match an exact number first, and # is the number itself. An exact number must fit the placeholder's type: up to 9223372036854775807 for an int, and up to 9007199254740992 (2^53) for a num, past which a float can no longer tell neighbouring whole numbers apart.

"cartItems": "{count, plural, =0 {Your cart is empty} one {# item in your cart} other {# items in your cart}}"

The template's one and other are English's two forms. A Polish translation writes one, few, many, and other, and gets each at the right numbers, because the generated code asks the rules of the translation's own locale, not the template's:

"cartItems": "{count, plural, =0 {Koszyk jest pusty} one {# przedmiot w koszyku} few {# przedmioty w koszyku} many {# przedmiotów w koszyku} other {# przedmiotu w koszyku}}"

The rules are CLDR's, for every language it covers; pt-BR uses the pt rules while pt-PT has its own. Floats count by their shortest decimal form, so 1.0 is one in English and 1.5 is other.

Selects#

{gender, select, ...} picks a form by a word. Name the words the message distinguishes, and always other, for every value the message does not name. A select's placeholder is a &str.

"pronoun": "{gender, select, female {she} male {he} other {they}}"

Plurals and selects nest: {who, select, you {You have {count, plural, one {# message} other {# messages}}} other {{who} has {count, plural, one {# message} other {# messages}}}} is one message with two parameters.

Quoting#

Quoting follows ICU. '' is an apostrophe. A ' before { or } quotes literal text up to the next ', so '{' is a brace; inside a plural, where # is the number, '#' is a hash. Any other ' is itself: don't needs no care, and outside a plural '#' stays as written.

Quoting something that reads as a placeholder, such as '{name}', is an error, because it is easy to mean the opposite. Write ''{name}'' for the placeholder between apostrophes, or quote each brace, '{'name'}', for the text {name}.

Keys and methods#

cartItems becomes cart_items; URLLabel becomes url_label. Messages are listed by method name in the module, so appTitle and URLLabel sit where app_title and url_label sort.

A key is an error, reported with its file and line, when its method would be:

• a Rust keyword, such as type or gen, or not a Rust name at all, such as x²;
• the same method as another key's, such as helloWorld and hello_world;
• a method the handle has itself: locale, set_locale, supported_locales, messages, and provide, and the clone, clone_from, clone_into, to_owned, into, and try_into every type has. l10n.locale() calls the handle's method, so a message named locale could never be read.

Adding a language#

Add locales/<tag>.arb, named after the locale's language tag: pt-BR.arb, zh-Hant.arb, ar.arb, ca-ES-valencia.arb. The tag names a language, and optionally a script, a region, and variants, as BCP 47 writes them; @@locale inside the file is checked against the name, and two files with the same tag, such as pt-BR.arb and pt_BR.arb, are an error. Translate the messages you have, and leave out the ones you do not: an untranslated message falls back to the template's text, and leptoskit l10n lists what each file is missing, so a translation can land in pieces without a blank label anywhere.

Every translation must use the template's placeholders, each in a way its type allows: a count stays a number, and a translation cannot invent {surprise}. A key that the template does not have is an error, so a message is always added to the template first.

How a locale is chosen#

L10n::new and set_locale resolve the user's preferences in a way based on Flutter's basicLocaleListResolution. For each preferred locale in turn, they look for a supported locale with the same tag; then one with the same language and script; then one with the same language and region; and last one with the same language alone. For a language written in more than one script, a tag without one gets the script CLDR expects for its region, so zh-TW matches zh-Hant and zh-CN matches zh-Hans. A language-only match is held back only while the next preferred locale has the same language, since that one might match a region exactly: [en-GB, en-US] picks en-US from [en, en-US]. When several supported locales match at one step, the one with the user's region goes first, then one without a region, which stands in for the whole language, so pt-PT gets pt from [pt-BR, pt]. When nothing matches, the template serves. leptoskit_l10n::negotiate is this step on its own, for code that wants to show the user what it chose.

Flutter chooses differently in four cases:

What the generated module holds#

src/l10n.rs is ordinary Rust, formatted by your own rustfmt like any other file: formatting is not a change, so leptoskit l10n --check stays green after leptoskit format.

/// One method per message in `locales/en.arb`, typed by its placeholders.
pub trait Messages: Send + Sync {
	/// `Field Notes`
	fn app_title(&self) -> &'static str;
	/// `{count, plural, =0 {Your cart is empty} one {# item in your cart} other {# items in your cart}}`
	fn cart_items(&self, count: i64) -> String;
	/// Shown at the top of the home screen.
	///
	/// `Hello, {name}!`
	fn greeting(&self, name: &str) -> String;
	/// `{gender, select, female {she} male {he} other {they}}`
	fn pronoun(&self, gender: &str) -> String;
}

/// The `pt-BR` messages, from `locales/pt-BR.arb`. Messages it leaves out
/// fall back to `En`: `pronoun`.
pub struct PtBr;

/// The plural rules of `pt-BR`.
static PT_BR_PLURALS: LazyLock<PluralRules> =
	LazyLock::new(|| PluralRules::for_locale(&Locale::new("pt-BR").unwrap()));

impl Messages for PtBr {
	fn app_title(&self) -> &'static str {
		"Notas de Campo"
	}

	fn cart_items(&self, count: i64) -> String {
		if count == 0 {
			"Seu carrinho está vazio".to_owned()
		} else if PT_BR_PLURALS.category(count) == PluralCategory::One {
			format!("{count} item no carrinho")
		} else {
			format!("{count} itens no carrinho")
		}
	}

	fn greeting(&self, name: &str) -> String {
		format!("Olá, {name}!")
	}

	fn pronoun(&self, gender: &str) -> String {
		En.pronoun(gender)
	}
}

Alongside these, the module declares L10n, the handle for this app's messages; use_l10n, which returns the one an ancestor provided; and AppTranslations, which tells the runtime which locale has which messages. Every locale has its own struct and messages, so ca-ES-valencia.arb and ca-ES.arb can sit side by side. leptoskit never overwrites an l10n.rs it did not write.

Coming from Flutter#

Most ARB files work as they are. Check these when you bring one over:

• Apostrophes. Flutter treats ' as plain text unless use-escaping: true is set in l10n.yaml, which is off by default. leptoskit always quotes the way ICU does, and the way Flutter does with use-escaping on. "Delete '{name}'?" shows the name between apostrophes in a default Flutter project; here it is an error that names both fixes, and "Delete ''{name}''?" gives the Flutter output. A doubled '' is one apostrophe here, and two in a default Flutter project. A lone apostrophe, as in don't, means the same everywhere.
• Choosing a locale. The resolution is based on Flutter's, and differs in the four cases above.
• Placeholder types. DateTime and Flutter's number formats are not supported yet; see below.

What is not here yet#

• Layout direction does not pass from a parent to its children. To lay a right-to-left language such as Arabic out right to left, set Direction::Rtl on every element of the screen; examples/postcard does it with one function over the tree. Native sliders keep filling from the left.
• Placeholders are strings and numbers. Dates, times, currencies, and formatted numbers are not typed or formatted; format them in Rust and pass the text as a String placeholder. # writes the number plainly, without grouping separators.
• Plurals are cardinal. Ordinal forms (1st, 2nd) and offset: are rejected with an error that says so.
• The locale is not saved or carried from server to client for you. Pass the same preferences on both sides, as the server and browser tabs above do, and store a user's own choice with the storage of your choice.