Module l10n 

Localization service, sources and other types.

Localized text is declared using the l10n! macro, it provides a read-only text variable that automatically updates to be best localized text available given the current loaded localization and the app language.

use zng::prelude::*;

let click_count = var(0u32);
Window! {
    title = l10n!("window-title", "Window Title");
    child = Button! {
        on_click = hn!(click_count, |_| click_count.set(click_count.get() + 1));
        child = Text!(l10n!("click-count", "Clicked {$n} times", n = click_count.clone()));
    };
}

In the example above declares two localization messages, “window.title” and “btn.click_count”, if these messages are localized for the current language the localized text is used, otherwise the provided fallback is used.

The L10N service can be used to set the app language and load localization resources. The example below sets the language to en-US and loads localization from a directory using L10N.load_dir.

use zng::prelude::*;

APP.defaults().run_window(async {
    // start loading localization resources
    L10N.load_dir(zng::env::res("l10n"));
    // set the app language, by default is the system language
    L10N.app_lang().set(lang!("en-US"));
    // preload the localization resources for a language
    L10N.wait_first(lang!("en-US")).await;

    Window! {
        // ..
    }
});

The service also supports embedded localization resources in the .tar and .tar.gz formats using L10N.load_tar, see the localize example for more details. You can also implement more container formats using L10N.load.

Fluent

The localization files are in the Fluent format. Fluent empowers translators to script things like plural forms, for this reason a localization file should be provided even for the same language the l10n! fallback text is written in.

click-count = {$n ->
    [one] Clicked {$n} time
    *[other] Clicked {$n} times
}

The example above demonstrates a localized message that provides plural alternatives for the English language.

Scraper

The cargo zng l10n tool can be used to generate a Fluent file from source code, the Fluent file can be used as a template for translators, it will include the fallback text and comments written close the key declaration.

use zng::prelude::*;

// l10n-### This standalone comment is added to the scraped template file.

let click_count = var(0u32);
Window! {
    title = l10n!("window-title", "Window Title");
    child = Button! {
        on_click = hn!(click_count, |_| click_count.set(click_count.get() + 1));
        // l10n-# This comment is added to the `"click-count"` entry.
        child = Text!(l10n!("click-count", "Clicked {$n} times", n = click_count.clone()));
    };
}

When the example above is scrapped it generates:

### This standalone comment is added to all scraped template files.

# This comment is added to the `"click-count"` entry.
click-count = Clicked {$n} times

See the l10n! documentation for a full explanation of how the Scraper converts comments and the l10n! calls into Fluent files.

Commands

Commands metadata can be localized and scrapped, to enable this set l10n!: on the command! declarations.

If the first metadata is l10n!: the command init will attempt to localize the other string metadata. The cargo zng l10n command line tool scraps commands that set this special metadata.

command! {
    pub static FOO_CMD = {
        l10n!: true,
        name: "Foo!",
        info: "Does the foo thing",
    };
}

The example above will be scrapped as:

FOO_CMD =
    .name = Foo!
    .info = Does the foo thing.

The l10n!: meta can also be set to a localization file name:

command! {
    pub static FOO_CMD = {
        l10n!: "file",
        name: "Foo!",
    };
}

The example above is scrapped to {l10n-dir}/{lang}/file.ftl files.

Limitations

Interpolation is not supported in command localization strings.

The l10n!: value must be a textual literal, that is, it can be only a string literal or a bool literal, and it cannot be inside a macro expansion.

Full API

See zng_ext_l10n for the full localization API.

Macros

l10n

Gets a variable that localizes and formats the text in a widget context.

lang

Compile-time validated Lang value.

Structs

L10N

Localization service.

L10nDir

Represents localization resources synchronized from files in a directory.

L10nMessageBuilder

Localized message variable builder.

L10nTar

Represents localization resources loaded from a .tar or .tar.gz container.

Lang

Identifies the language, region and script of text.

LangFilePath

Localization resource file path in the localization directory.

LangMap

Represents a map of Lang keys that can be partially matched.

LangResource

Handle to a localization resource.

LangResources

Handle to multiple localization resources.

Langs

List of languages, in priority order.

NilL10nSource

Localization source that is never available.

SwapL10nSource

Represents localization source that can swap the actual source without disconnecting variables taken on resources.

Enums

L10nArgument

Represents an argument value for a localization message.

LangResourceStatus

Status of a localization resource.

Statics

LANG_VAR

Language of text in a widget context.

Traits

L10nSource

Represents a localization data source.