bevy_fluent

Understanding the hierarchy of Fluent assets in bevy_fluent:

• Localization: A fallback chain of Fluent bundles.
• Bundle asset: An abstraction for presentation Fluent bundles, using the .ftl.ron extension.
• Resource asset: The atomic unit of disk storage for Fluent, using the .ftl extension. It contains a set of messages.
• Message: The basic atomic translation unit, identified by a unique Identifier.
• Content: The formatted Pattern resulting from a Request for a message, term, variant, or attribute.

Understanding the hierarchy of localization in bevy_fluent:

• Localization: A fallback chain of FluentBundles.
• BundleAsset: An abstraction for Fluent bundles, represented by .ftl.ron files.
• ResourceAsset: An abstraction for a single FluentResource, represented by .ftl files. This is the atomic unit of storage on disk.
• Message: An atomic unit of translation within a resource, identified by a unique Identifier.
• Content: The final formatted string resulting from a Request applied to a message's pattern (which may contain terms, variants, or attributes).

You can load Fluent assets using the standard Bevy AssetServer or the AssetServerExt trait for pattern matching.

• Use asset_server.load to load a specific .ftl.ron file.
• Use asset_server.load_glob (from bevy_fluent::exts::bevy::AssetServerExt) to load multiple assets matching a glob pattern.

Note that .ftl.ron files represent BundleAssets, which are abstractions for Fluent bundles.

// Load a single bundle asset
let handle = asset_server.load("locales/ru-RU/main.ftl.ron");

// Load all bundle assets matching a pattern
use bevy_fluent::exts::bevy::AssetServerExt;
let handles = asset_server.load_glob("locales/**/main.ftl.ron")?;

You can load Fluent assets into your Bevy project using the standard AssetServer.

To load a specific bundle asset, use the .load() method with a path ending in .ftl.ron. To load multiple assets at once (for example, all locales), use the load_glob method provided by the AssetServerExt trait.

File Extensions

• Bundle assets: Use .ftl.ron (represents a Fluent bundle fallback chain).
• Resource assets: Use .ftl (represents an atomic Fluent resource).

// Load a single bundle asset
let handle = asset_server.load("locales/en-US/main.ftl.ron");

// Load all assets matching a glob pattern using AssetServerExt
use bevy_fluent::exts::bevy::AssetServerExt;
let handles = asset_server.load_glob("locales/**/main.ftl.ron")?;

Before attempting to use localization assets, ensure they have finished loading by checking their load state via the AssetServer.

You can check the state of a single handle or a group of handles (e.g., from a glob load).

// Check a single handle
if let LoadState::Loaded = asset_server.get_load_state(handle) {
    // Assets are ready
}

// Check a group of handles
if let LoadState::Loaded = asset_server.get_group_load_state(handles) {
    // All assets in the group are ready
}

When using bevy_fluent, you must ensure that your version of the bevy engine is compatible with the version of bevy_fluent you are using. Refer to the compatibility matrix below to select the correct versions for your project:

To enable Fluent file loading in your Bevy application, add the FluentPlugin to your app. This plugin registers the necessary asset loaders and initializes the core asset types: ResourceAsset and BundleAsset.

use bevy::prelude::*;
use bevy_fluent::FluentPlugin;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(FluentPlugin)
        .run();
}

To simplify imports, you can use the prelude module which exports the most commonly used types and plugins for localization. This includes BundleAsset, FluentPlugin, Locale, Localization, and LocalizationBuilder.

use bevy_fluent::prelude::*;

To ensure your localization assets are ready before use, you can check their loading state using AssetServer methods:

• get_load_state(handle): Checks the status of a single asset handle.
• get_group_load_state(handles): Checks the status of a collection of asset handles.

// Check a single asset
if let LoadState::Loaded = asset_server.get_load_state(handle) {
    ...
}

// Check multiple assets
if let LoadState::Loaded = asset_server.get_group_load_state(handles) {
    ...
}

Once assets are loaded, you can retrieve the actual translated text (content) using the .content() method. This can be called on either a single BundleAsset or the entire Localization fallback chain.

Both methods take an identifier (the message ID) and return the formatted content.

// Request from a specific bundle asset
let hello_world = bundle_asset.content("hello-world")?;

// Request from the localization fallback chain
let hello_world = localization.content("hello-world")?;

Use LocalizationBuilder to create a Localization object from a set of loaded asset handles. This Localization object represents a fallback chain of Fluent bundles, allowing you to manage multiple locales and their fallback logic.

let localization = localization_builder.build(handles);