#localization #embed #fluent #macro #gettext

i18n-embed

Traits and macros to conveniently embed localization assets into your application binary or library in order to localize it at runtime

45 releases

0.14.1 Sep 27, 2023
0.13.9 May 16, 2023
0.13.8 Jan 14, 2023
0.13.4 Feb 23, 2022
0.6.0 May 20, 2020

#10 in Internationalization (i18n)

Download history 7007/week @ 2023-11-26 6337/week @ 2023-12-03 6739/week @ 2023-12-10 6642/week @ 2023-12-17 4500/week @ 2023-12-24 4284/week @ 2023-12-31 7832/week @ 2024-01-07 9462/week @ 2024-01-14 6863/week @ 2024-01-21 8806/week @ 2024-01-28 7984/week @ 2024-02-04 9002/week @ 2024-02-11 9349/week @ 2024-02-18 7312/week @ 2024-02-25 7234/week @ 2024-03-03 3654/week @ 2024-03-10

28,798 downloads per month
Used in 50 crates (19 directly)

MIT license

86KB
1K SLoC

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

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
  • 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 = "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):

# (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 Localizations;

fn main() {
    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, &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.

Dependencies

~2–12MB
~104K SLoC