#embed #macro #i18n #gettext #fluent

i18n-embed

Traits and macros to conveniently embed the output of cargo-i18n into your application binary in order to localize it at runtime

26 releases (8 breaking)

new 0.9.3 Oct 23, 2020
0.8.6 Oct 17, 2020
0.6.0 May 20, 2020

#12 in Build Utils

Download history 77/week @ 2020-07-02 117/week @ 2020-07-09 23/week @ 2020-07-16 94/week @ 2020-07-23 5/week @ 2020-07-30 20/week @ 2020-08-06 41/week @ 2020-08-13 78/week @ 2020-08-20 244/week @ 2020-08-27 140/week @ 2020-09-03 37/week @ 2020-09-10 43/week @ 2020-09-17 101/week @ 2020-09-24 118/week @ 2020-10-01 186/week @ 2020-10-08 341/week @ 2020-10-15

492 downloads per month
Used in 3 crates

MIT license

67KB
879 lines

i18n-embed crates.io badge docs.rs badge license badge github actions badge

This library contains traits and macros to conveniently embed the output of cargo-i18n into your application binary in order to localize it at runtime.

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
  • 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:

[dependencies]
i18n-embed = { version = "0.8", features = ["fluent-system", "desktop-requester"]}
rust-embed = "5"
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):

# (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:

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

Then you can instantiate your language loader and language requester:

use i18n_embed::{DesktopLanguageRequester, fluent::{
    FluentLanguageLoader, fluent_language_loader
}};
use rust_embed::RustEmbed;

#[derive(RustEmbed)]
#[folder = "i18n"] // path to the compiled localization resources
struct Translations;

fn main() {
    let translations = Translations {};
    let language_loader: FluentLanguageLoader = fluent_language_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, &translations, &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.

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

Dependencies

~1.7–5MB
~79K SLoC