bevy-fluent

Bevy 0.19 — 本地化（es-fluent）

何时使用此技能

• 为 Bevy 应用添加基于 Fluent 的 i18n（es-fluent-manager-bevy = "0.19.2"）。
• 使用 #[derive(EsFluent)] 和 #[derive(BevyFluentText)] 定义类型化 UI 消息。
• 使用 FluentText<T> 包装 UI 文本实体，实现由区域设置驱动的自动刷新。
• 通过 LocaleChangeEvent 在运行时切换区域设置。
• 从 RequestedLanguageId 读取当前区域设置。

标准模式 — 至少包含 5 个文件

Cargo.toml：

[dependencies]
bevy                   = "0.19"
es-fluent              = { version = "0.18.1", features = ["derive"] }
es-fluent-manager-bevy = { version = "0.19.2", features = ["macros"] }
unic-langid            = "0.9"

i18n.toml（crate 根目录，在编译时读取）：

fallback_language = "en"
assets_dir = "assets/locales"

src/i18n.rs：

es_fluent_manager_bevy::define_i18n_module!();

src/lib.rs — 消息类型必须定义在此处（参见注意事项）：

use bevy::prelude::*;
use es_fluent::EsFluent;
use es_fluent_manager_bevy::{
    BevyFluentText, FluentText, I18nPlugin, LocaleChangeEvent, RequestedLanguageId,
};
use unic_langid::langid;

pub mod i18n;

#[derive(BevyFluentText, Clone, EsFluent)]
#[fluent(namespace = "ui")]
pub enum UiMessage { StartGame, Settings, QuitGame }

pub fn build_i18n_plugin() -> I18nPlugin {
    I18nPlugin::with_language(langid!("en"))
}

pub fn setup_ui(mut commands: Commands) {
    commands.spawn(Camera2d);
    // FluentText<T> writes translations into a sibling Text component.
    commands.spawn((FluentText::new(UiMessage::StartGame), Text::new("")));
}

pub fn switch_locale_on_keypress(
    keys: Res<ButtonInput<KeyCode>>,
    requested: Res<RequestedLanguageId>,
    mut locale_events: MessageWriter<LocaleChangeEvent>,
) {
    if keys.just_pressed(KeyCode::KeyL) {
        let next = if requested.0.to_string() == "en" { langid!("fr") } else { langid!("en") };
        locale_events.write(LocaleChangeEvent(next));
    }
}

src/main.rs — 精简的二进制入口：

use bevy::prelude::*;
use my_game::{build_i18n_plugin, setup_ui, switch_locale_on_keypress};

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(build_i18n_plugin())
        .add_systems(Startup, setup_ui)
        .add_systems(Update, switch_locale_on_keypress)
        .run();
}

将 my_game 替换为你的包名（连字符会转换为下划线）。完整指南——包括采用 lib 而非二进制文件的原因、包名占位符，以及纯二进制 crate 的变通方案——请参见 references/lib-target-layout.md。

主题

主题	参考
类型必须定义在 lib 目标中的原因；cargo es-fluent generate 不可见的陷阱；完整布局	references/lib-target-layout.md
BevyFluentText derive 与 FluentText<T> 组件；Text::new("")	references/components.md
LocaleChangeEvent（请求）与 LocaleChangedEvent（确认）；RequestedLanguageId；Messages 与 Events	references/locale-events.md
i18n.toml 完整架构、assets_dir、I18nPluginConfig 运行时覆盖	references/i18n-toml.md
generate、watch、check、clean、sync、tree、format — 开发与 CI 工作流	references/cli.md
rustc 1.96+ 要求；rust-toolchain.toml 固定版本；旧工具链上的失败模式	references/toolchain.md

注意事项

1. cargo es-fluent generate 只会扫描 lib 目标。 仅在 src/main.rs 中声明的消息枚举对 CLI 不可见，会生成空的 .ftl 输出且不报错。将所有派生自 BevyFluentText / EsFluent 的类型移至 src/lib.rs（或从该文件可访问的模块）。参见 references/lib-target-layout.md。

2. BevyFluentText 是 derive 宏；FluentText<T> 才是组件。 derive 会通过 inventory 注册刷新系统。你需要在 UI 实体上生成的是该组件。在 0.19.2 中，消息类型需要满足 FluentMessage + Clone + Send + Sync + 'static；它本身不会派生 Component。参见 references/components.md。

3. rustc 最低版本为 1.96。 较旧的工具链会出现晦涩的 trait 解析错误，且不会提及版本要求。使用 rust-toolchain.toml 固定版本（[toolchain] / channel = "1.96"）。参见 references/toolchain.md。

4. Events 就是 Messages。 使用 MessageWriter<LocaleChangeEvent> 和 MessageReader<LocaleChangedEvent>——不要使用 EventWriter/EventReader （在 Bevy 0.17 中已重命名）。参见 references/locale-events.md。

另请参阅

• bevy-ui — FluentText<T> 与 Text、Node 和 Button 搭配使用。
• bevy-ecs-components — FluentText<T> 所需的 #[derive(Component)] 模式。
• bevy-assets — Bevy 的 AssetServer 如何加载 .ftl 文件；与热重载相关。