i18n-embed

Traits and macros to conveniently embed localization assets into your application binary or library in order to localize it at runtime. Works in unison with cargo-i18n.

Currently this library depends on rust-embed to perform the actual embedding of the language files. This may change in the future to make the library more convenient to use.

Changelog

Optional Features

The i18n-embed crate has the following optional Cargo features:

• fluent-system
  • Enable support for the fluent localization system via the FluentLanguageLoader.
• gettext-system
  • Enable support for the gettext localization system using the tr macro and the gettext crate via the GettextLanguageLoader.
• desktop-requester
  • Enables a convenience implementation of LanguageRequester trait called DesktopLanguageRequester for the desktop platform (windows, mac, linux),which makes use of the locale_config crate for resolving the current system locale.
• web-sys-requester
  • Enables a convenience implementation of LanguageRequester trait called WebLanguageRequester which makes use of the web-sys crate for resolving the language being requested by the user's web browser in a WASM context.

Example

The following is a minimal example for how localize your binary using this library using the fluent localization system.

First you need to compile i18n-embed in your Cargo.toml with the fluent-system and desktop-requester features enabled:

toml [dependencies] i18n-embed = { version = "VERSION", features = ["fluent-system", "desktop-requester"]} rust-embed = "6" unic-langid = "0.9"

Set up a minimal i18n.toml in your crate root to use with cargo-i18n (see cargo i18n for more information on the configuration file format):

```toml

(Required) The language identifier of the language used in the

source code for gettext system, and the primary fallback language

(for which all strings must be present) when using the fluent

system.

fallback_language = "en-GB"

Use the fluent localization system.

[fluent]

(Required) The path to the assets directory.

The paths inside the assets directory should be structured like so:

assets_dir/{language}/{domain}.ftl

assets_dir = "i18n" ```

Next, you want to create your localization resources, per language fluent files. language needs to conform to the Unicode Language Identifier standard, and will be parsed via the unic_langid crate.

The directory structure should look like so:

txt my_crate/ Cargo.toml i18n.toml src/ i18n/ {language}/ {domain}.ftl

Then you can instantiate your language loader and language requester:

```rust use i18nembed::{DesktopLanguageRequester, fluent::{ FluentLanguageLoader, fluentlanguageloader }}; use rustembed::RustEmbed;

[derive(RustEmbed)]

[folder = "i18n"] // path to the compiled localization resources

struct Localizations;

fn main() { let languageloader: FluentLanguageLoader = fluentlanguage_loader!();

// Use the language requester for the desktop platform (linux, windows, mac).
// There is also a requester available for the web-sys WASM platform called
// WebLanguageRequester, or you can implement your own.
let requested_languages = DesktopLanguageRequester::requested_languages();
let _result = i18n_embed::select(
    &language_loader, &Localizations, &requested_languages);

// continue on with your application

} ```

To access localizations, you can use FluentLanguageLoader's methods directly, or, for added compile-time checks/safety, you can use the fl!() macro. Having an i18n.toml configuration file enables you to do the following:

• Use the cargo i18n tool to perform validity checks (not yet implemented).
• Integrate with a code-base using the gettext localization system.
• Use the fluent::fluent_language_loader!() macro to pull the configuration in at compile time to create the fluent::FluentLanguageLoader.
• Use the fl!() macro to have added compile-time safety when accessing messages.

Example projects can be found in examples.

For more explained examples, see the documentation for i18n-embed.