cargo-i18n

To embed Fluent localization into your application, follow these steps:

1. Add i18n-embed with fluent-system and a requester feature (e.g., desktop-requester) to your Cargo.toml.
2. Create an i18n.toml file in your crate root.
3. Define a struct using #[derive(RustEmbed)] pointing to your assets directory.
4. Use the fluent_language_loader!() macro to instantiate the loader.
5. Use i18n_embed::select to resolve the requested languages against your embedded localizations.

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() {
    // Create the loader using the macro which pulls config from i18n.toml
    let language_loader: FluentLanguageLoader = fluent_language_loader!();

    // Resolve the system's requested languages
    let requested_languages = DesktopLanguageRequester::requested_languages();
    
    // Select the appropriate localizations
    let _result = i18n_embed::select(
        &language_loader, &Localizations, &requested_languages);

    // continue on with your application
}

To use i18n-embed-fl for compile-time checked Fluent localization, you must configure an i18n.toml file in your crate root and organize your Fluent files in a specific directory structure.

1. Configure i18n.toml

Create an i18n.toml file in your crate root with the following required keys:

• fallback_language: The language identifier used as the primary fallback (e.g., "en-GB").
• [fluent] assets_dir: The path to your localization assets.

2. Organize Assets

Your assets directory must follow this structure: assets_dir/{language}/{domain}.ftl

Note: The {domain} should be the Rust path of your crate, using underscores (_) instead of hyphens (-).

3. Implementation Example

Use fluent_language_loader! to initialize the loader and the fl! macro from i18n-embed-fl to retrieve messages with compile-time validation of both the message ID and the arguments.

# i18n.toml
fallback_language = "en-GB"

[fluent]
assets_dir = "i18n"

use i18n_embed::{
    fluent::{fluent_language_loader, FluentLanguageLoader},
    LanguageLoader,
};
use i18n_embed_fl::fl;
use rust_embed::RustEmbed;

#[derive(RustEmbed)]
#[folder = "i18n/"]
struct Localizations;

let loader: FluentLanguageLoader = fluent_language_loader!();
loader
    .load_languages(&Localizations, &[loader.fallback_language().clone()])
    .unwrap();

// The fl! macro performs compile-time checks for the ID and arguments
assert_eq!(
    "Hello \u{2068}Bob 23\u{2069}!",
    fl!(loader, "hello-arg", name = format!("Bob {}", 23))
)

The LanguageRequester trait is used by I18nAssets to determine which languages are currently being requested by the system or environment. It allows you to register Localizer instances as listeners that will automatically update via their select() method whenever the requested languages change.

Key capabilities include:

• Adding Listeners: You can add listeners using add_listener (for Weak<dyn Localizer>, which are automatically removed when the underlying Arc is dropped) or add_listener_ref (for &'a dyn Localizer, which are permanent).
• Polling: The poll() method checks the current system/environment language and notifies all registered listeners.
• Overrides: You can use set_language_override to force a specific unic_langid::LanguageIdentifier regardless of the system settings.
• Introspection: You can query requested_languages(), available_languages(), and current_languages() to see what the system wants, what is available, and what is currently loaded across different domains.