Module localization

Expand description

Provides types for adapting an application to a particular language or regional peculiarities.

§Language Translation

Vizia provides the ability to dynamically translate text using fluent. Fluent provides a syntax for describing how text should be translated into different languages. The fluent syntax guide contains more information on the fluent syntax.

§Adding Fluent Files

Before text can be translated, one or more fluent files must be added to an application with the corresponding locale:

// Adds a fluent file to the application resource manager.
// This file is then used for translations to the corresponding locale.
cx.add_translation(
    langid!("en-US"),
    include_str!("resources/en-US/translation.ftl").to_owned(),
);

§Setting the Locale

The application will use the system locale by default, however an environment event can be used to set a custom locale. If no exact translation exists for the specified locale, vizia will negotiate the best available match and then fall back per message to the default translation bundle when needed.

// Sets the current locale to en-US, regardless of the system locale
cx.emit(EnvironmentEvent::SetLocale(langid!("en-US")));

§Diagnostics

Missing keys, missing attributes, and Fluent formatting issues are reported through the standard log backend at warn level. Configure your logger (for example with env_logger, tracing-log, or fern) to surface these messages.

§Basic Translation

Use the Localized type to specify a translation key to be used with fluent files. The key is then used to look up the corresponding translation.

Label::new(cx, Localized::new("hello-world"));

The markup in the loaded fluent (.ftl) files defines the translations for a particular key. The translation used depends on the application locale, which can be queried from Environment.

// en-US/hello.ftl
hello-world = Hello, world!

// fr/hello.ftl
hello-world = Bonjour, monde!

§Variables

Data from the application can be inserted into translated text using a placeable. The variable is enclosed in curly braces and prefixed with a $ symbol.

welcome = Welcome, { $user }!

The Localized type provides the arg(...) method for referencing a variable. It accepts either a plain value or a signal, binding the fluent variable to application data and updating when that data changes.

Label::new(cx, Localized::new("welcome").arg("user", "Jane"));

let user = Signal::new("Jane".to_string());

Label::new(cx, Localized::new("welcome").arg("user", user));

§Attributes

Messages can have named attributes that provide alternative translations. These are useful for UI elements that need multiple text values. Attributes must be preceded by a main message value:

file-dialog = File Dialog
    .title = Save File
    .save-button = Save

To reference an attribute, use the .attribute() method:

Label::new(cx, Localized::new("file-dialog").attribute("title"));

§Terms

Terms are special variables prefixed with a hyphen that can be referenced in other messages. They’re automatically available in all translations and are commonly used for product names or branding.

-brand = Vizia
welcome = Welcome to { -brand }!

Terms are automatically resolved when formatting, so no special configuration is needed when using them in messages.

§Message References

Messages can reference other messages to maintain consistency and reduce duplication:

menu-save = Save
help-menu-save = Click { menu-save } to save the file.

Message references are automatically resolved by the localization system and work seamlessly with the Localized type. This is useful for keeping certain translations consistent across the interface and making maintenance easier.

§Selectors and Plurals

Fluent selectors let you choose translations based on a variable value:

role-label = { $role ->
    [admin] You are signed in as an administrator.
   *[user] You are signed in as a user.
}
cart-summary = { $count ->
    [one] You have one item in your cart.
   *[other] You have { $count } items in your cart.
}

In Rust, pass the selector values with arg(...):

Label::new(cx, Localized::new("role-label").arg("role", "admin"));
Label::new(cx, Localized::new("cart-summary").arg("count", 3));

§Number Formatting

Numbers can be formatted in FTL with the built-in NUMBER function:

price = Your total is { NUMBER($amount) }

In Rust, pass numbers directly as arguments:

Label::new(cx, Localized::new("price").arg("amount", 99.99));

For more control, use the helper functions to specify decimal places:

Label::new(cx, Localized::new("price").arg("amount", number_with_fraction(99.99, 2)));

Or for percentages:

Label::new(cx, Localized::new("completion").arg("percent", percentage(0.75, 1)));

Currency symbols and symbol placement are best handled in translations today. Pre-format the numeric portion in Rust or upstream and let each locale decide where the symbol belongs:

# en-US
price-currency = Price: ${ $amount }

# fr
price-currency = Prix : { $amount } €

Label::new(cx, Localized::new("price-currency").arg("amount", "99.99"));

§Date Formatting

Dates can be formatted with locale-specific rules using the built-in DATETIME function in FTL. Pass chrono datetime values directly to arg() - the conversion to milliseconds is handled automatically:

let now = Utc::now();
Label::new(cx, Localized::new("event-date").arg("date", now));

Both timezone-aware and naive datetimes are supported:

Timezone-aware datetimes like DateTime<Utc> or DateTime<Local> work directly
Naive datetimes are automatically assumed to be in UTC

For custom formatting, you can use pre-formatted date strings:

let formatted_date = "April 13, 2026".to_string();
Label::new(cx, Localized::new("event-date").arg("date", formatted_date));

Structs§

FluentDateTime: Wrapper for chrono DateTime that automatically converts to Fluent’s expected millisecond format.
FluentNaiveDateTime: Wrapper for chrono NaiveDateTime that automatically converts to Fluent’s expected millisecond format.
Localized: A type which formats a localized message with any number of named arguments.

Traits§

ToStringLocalized: A trait for converting from Localized to a String via a translation using fluent.

Functions§

number_with_fraction: Helper function for formatting a number with decimal places for localized display.
percentage: Helper function for formatting a number as a percentage for localized display.