Module vizia::localization

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(
    "en-US".parse().unwrap(),
    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 fluent file can be found for the specified locale, then a fallback fluent file is used from the list of available files.

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

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 two methods for referencing a variable. The arg_const(...) method allows a keyed value to be inserted into the translation.

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

While the arg(...) method allows a keyed lens to be used, binding the fluent variable to a piece of application data, and updating when that data changes.

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

Structs

• Localized
  A type which formats a localized message with any number of named arguments.

Traits

• ToStringLocalized