cushy

Module localization

source
Expand description

Localization allows user interfaces to be presented in the user’s native locale (language and region).

Localization in Cushy is powered by Fluent. Fluent offers a variety of features that solve many common localization problems. If you think your application might benefit from having multiple languages, it might save a lot of time to build the application with localization in mind.

Thankfully, localization in Cushy is fairly straightforward. Wherever you want to display a localizable message, use the Localize type or the localize! macro:

use cushy::localization::Localize;
use cushy::localize;

let message = Localize::new("hello-world");
let message = localize!("hello-world");

Regardless of which style you prefer, message now contains a localizable message. When the application is running, wherever message is used, the message will be looked up in the current locale.

Localization messages are resolved through the application’s Cushy instance. Cushy::localizations() returns the global Localizations collection, which Localizations can be added to. Consider this simple example:

use cushy::localization::Localization;
use cushy::{localize, Open, PendingApp};

#[cushy::main]
fn main(app: &mut PendingApp) -> cushy::Result {
    app.cushy()
        .localizations()
        .add_default(Localization::for_language("en-US", "hello = Hello World!").unwrap());
    app.cushy()
        .localizations()
        .add_default(Localization::for_language("es-MX", "hello = ¡Hola Mundo!").unwrap());
    app.cushy()
        .localizations()
        .add_default(Localization::for_language("fr-FR", "hello = Bonjour monde!").unwrap());

    localize!("hello").open(app)?;

    Ok(())
}

Additionally, Fluent supports providing arguments to localization messages:

use cushy::localization::Localization;
use cushy::{localize, Open, PendingApp};

#[cushy::main]
fn main(app: &mut PendingApp) -> cushy::Result {
    app.cushy()
        .localizations()
        .add_default(Localization::for_language("en-US", "hello-user = Hello {$name}!").unwrap());
    app.cushy()
        .localizations()
        .add_default(Localization::for_language("es-MX", "hello-user = ¡Hola {$name}!").unwrap());
    app.cushy()
        .localizations()
        .add_default(Localization::for_language("fr-FR", "hello-user = Bonjour {$name}!").unwrap());

    localize!("hello", "user" => "Ecton").open(app)?;

    Ok(())
}

§Locale Fallback Behavior

Cushy attempts to find an exact match between the current locale and a loaded Localization. If an exact match is not found, [fluent_langneg] is used to try to find a fallback locale. If the message being localized cannot be found in either of these locales, the message is looked up in the default locale.

Cushy has the concept of a default locale. There is no default locale until either Localizations::add_default or Localizations::set_default_locale are executed. Once a default locale is established, any messages that cannot be found in the current locale or a fallback locale will be localized using the default locale as a final effort.

Using the default locale can be convenient, but it can also make it harder to visually notice when a message is missing from a particular locale. When relying on third parties to provide localizations, it can be beneficial to ensure that a valid message is always shown even if a localized message has not been provided yet.

Structs§

  • Localization
    A localization for a specific locale.
  • Localizations
    A collection of localizations to apply to a Cushy application.
  • Localize
    The primary of defining localized message

Enums§

  • Locale
    A locale (language and region)

Traits§