Crate es_fluent_manager_bevy

Expand description

§es-fluent-manager-bevy

Seamless Bevy integration for es-fluent.

This plugin connects es-fluent’s type-safe localization with Bevy’s ECS and Asset system. It allows you to use standard #[derive(EsFluent)] types as components that automatically update when the game’s language changes.

`es-fluent-manager-bevy`	`bevy`
crates.io
`0.18.x`	`0.18.x`
`0.17.x`	`0.17.x`

§Features

Asset Loading: Loads .ftl files via Bevy’s AssetServer.
Hot Reloading: Supports hot-reloading of translations during development.
Reactive UI: The FluentText component automatically refreshes text when the locale changes.
Global Hook: Integrates with es-fluent’s global state.

§Quick Start

§1. Setup

Add the plugin to your App and define your I18n module:

use bevy::prelude::*;
use es_fluent_manager_bevy::I18nPlugin;
use unic_langid::langid;

// a i18n.toml file must exist in the root of the crate
es_fluent_manager_bevy::define_i18n_module!();

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        // Initialize with default language
        .add_plugins(I18nPlugin::with_language(langid!("en-US")))
        .run();
}

§2. Using in UI

Use the FluentText component wrapper for any type that implements ToFluentString (which #[derive(EsFluent)] provides).

use es_fluent::EsFluent;
use es_fluent_manager_bevy::FluentText;

#[derive(EsFluent, Clone, Component)]
pub enum UiMessage {
    StartGame,
    Settings,
}

fn spawn_menu(mut commands: Commands) {
    commands.spawn((
        // This text will automatically update if language changes
        FluentText::new(UiMessage::StartGame),
        Text::new(""),
    ));
}

§3. Registering Components

For FluentText to work, you must register the specific inner type with the app so the plugin knows to update it:

app.register_fluent_text::<UiMessage>();

§es-fluent-lang integration

If your type contains fields that use es_fluent_lang (for the Languages enum), you must implement RefreshForLocale and use register_fluent_text_from_locale instead:

use es_fluent_manager_bevy::RefreshForLocale;

#[derive(EsFluent, Clone, Component)]
pub enum UiMessage {
    LanguageHint { current_language: Languages },
}

impl RefreshForLocale for UiMessage {
    fn refresh_for_locale(&mut self, lang: &unic_langid::LanguageIdentifier) {
        match self {
            UiMessage::LanguageHint { current_language } => {
                *current_language = Languages::from(lang);
            }
        }
    }
}

// Register with:
app.register_fluent_text_from_locale::<UiMessage>();

Re-exports§

pub use bevy;
pub use inventory;
pub use unic_langid;
pub use components::*;
pub use plugin::*;
pub use systems::*;

Modules§

components
plugin
systems

Macros§

define_i18n_module: Defines a Bevy i18n module.
langid

Structs§

CurrentLanguageId: A Bevy resource that holds the currently active LanguageIdentifier.
EsFluentBevyPlugin: A plugin that initializes the es-fluent Bevy integration.
FtlAsset: A Bevy asset representing a Fluent Translation List (.ftl) file.
FtlAssetLoader: An AssetLoader for loading .ftl files as FtlAssets.
I18nAssets: A Bevy resource that manages the loading of FtlAssets.
I18nBundle: A Bevy resource containing the FluentBundle for each loaded language.
I18nResource: The main resource for handling localization.
LocaleChangeEvent: A Bevy Message sent to request a change of the current locale.
LocaleChangedEvent: A Bevy Message sent after the current locale has been successfully changed.

Traits§

BevyFluentTextRegistration: Trait for auto-registering FluentText systems with Bevy.
FluentDisplay: This trait is similar to std::fmt::Display, but it is used for formatting types that can be displayed in a Fluent message.
FluentTextRegistration: An extension trait for App to simplify the registration of FluentText components.
FromLocale: A trait for types that can be constructed from a LanguageIdentifier.
RefreshForLocale: A trait for types that can be updated in place when the locale changes.
ToFluentString: This trait is automatically implemented for any type that implements FluentDisplay.

Functions§

localize: A convenience function for localizing a message by its ID.
primary_language: Returns the primary language subtag from a LanguageIdentifier.
update_values_on_locale_change: A Bevy system that listens for LocaleChangedEvents and updates components that implement RefreshForLocale.

Derive Macros§

BevyFluentText: Registers a type for use with FluentText<T> in Bevy.