[−][src]Crate i18n_embed

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

The core trait for this library is I18nEmbed, which also has a derive macro to allow it to be easily implemented on a struct in your project.

This library makes use of rust-embed to perform the actual embedding of the language files, unfortunately using this currently requires you to manually add it as a dependency to your project and implement its trait on your struct in addition to I18nEmbed. At some point in the future this library may incorperate the embedding process into the I18nEmbed trait and remove this dependency. RustEmbed currently will not compile if the target folder path is invalid, so it is recommended to either run cargo i18n before building your project, or committing the compiled resources to ensure that the project can build without requiring cargo i18n.

Optional Features

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

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.

Examples

The following is an example for how to derive the required traits on structs, and localize your binary using this library:

use i18n_embed::{I18nEmbed, LanguageLoader, DesktopLanguageRequester};
use rust_embed::RustEmbed;

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

#[derive(LanguageLoader)]
struct MyLanguageLoader;

fn main() {
    let language_loader = MyLanguageLoader {};

    // 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 language_requester = DesktopLanguageRequester::new();
    Translations::select(&language_requester, &language_loader);
}

If you wish to create a localizable library using i18n-embed, you can follow this code pattern:

use i18n_embed::{LanguageRequester, I18nEmbed, LanguageLoader};
use rust_embed::RustEmbed;

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

#[derive(LanguageLoader)]
struct MyLanguageLoader;

/// Localize this library, and select the language using the provided
/// LanguageRequester.
pub fn localize<L: LanguageRequester>(language_requester: L) {
    let loader = MyLanguageLoader {};
    Translations::select(&language_requester, &loader);
}

People using this library can call localize() to perform the localization at runtime, and provide their own LanguageRequester specific to the platform they that they are targetting.

If you want to localize a sub-crate in your project, and want to extract strings from this sub-crate and store/embed them in one location in the parent crate, you can use the following pattern for the library:

use i18n_embed::{LanguageRequester, I18nEmbed, LanguageLoader};

#[derive(LanguageLoader)]
struct MyLanguageLoader;

/// Localize this library, and select the language using the 
/// provided I18nEmbed and LanguageRequester.
pub fn localize<E: I18nEmbed, L: LanguageRequester>(language_requester: L) {
    let loader = MyLanguageLoader {};
    E::select(&language_requester, &loader);
}

For the above example, you can enable the following options in the sub-crate's i18n.toml to ensure that the localization resources are extracted and merged with the parent crate's pot file:

# ...

[gettext]

# ...

# (Optional) If this crate is being localized as a subcrate, store the final
# localization artifacts (the module pot and mo files) with the parent crate's
# output. Currently crates which contain subcrates with duplicate names are not
# supported.
extract_to_parent = true

# (Optional) If a subcrate has extract_to_parent set to true, then merge the
# output pot file of that subcrate into this crate's pot file.
collate_extracted_subcrates = true

Re-exports

pub use unic_langid;

pub use tr;

pub use gettext;

Structs

DesktopLanguageRequester	A LanguageRequester for the desktop platform, supporting windows, linux and mac. It uses locale_config to select the language based on the system selected language.
WebLanguageRequester	A LanguageRequester for the `web-sys` web platform.

Traits

I18nEmbed	A trait to handle the embedding of software translations within the current binary, and the retrieval/loading of those translations at runtime.
LanguageLoader	A trait used by I18nEmbed to load a language file for the specified module path.
LanguageRequester	A trait used by I18nEmbed to ascertain which languages are being requested.

Functions

domain_from_module

Get the translation domain from the module path (first module in the module path).

Derive Macros

I18nEmbed	A procedural macro to implement the `I18nEmbed` trait on a struct.
LanguageLoader	A procedural macro to implement the `LanguageLoader` trait on a struct.