bevy-fluent

Bevy 0.19 — ローカライズ（es-fluent）

このスキルを使用する場面

• Bevy アプリに Fluent ベースの i18n を追加する場合（es-fluent-manager-bevy = "0.19.2"）。
• #[derive(EsFluent)] と #[derive(BevyFluentText)] を使用して、型付き UI メッセージを定義する場合。
• UI テキストエンティティを FluentText<T> でラップして、ロケールに応じて自動更新する場合。
• 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（クレートルート。コンパイル時に読み込まれます）：

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 をパッケージ名に置き換えてください（ハイフンはアンダースコアになります）。ライブラリとバイナリを分ける理由、パッケージ名のプレースホルダー、バイナリのみのクレートでの回避策を含む詳しい手順は、 references/lib-target-layout.md を参照してください。

トピック

トピック	リファレンス
型をライブラリターゲットに配置する必要がある理由、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 が認識するのはライブラリターゲットだけです。 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 を derive するわけではありません。references/components.md を参照してください。

3. rustc 1.96 以降が必要です。 古いツールチェーンでは、バージョン要件に言及しない、分かりにくいトレイト解決エラーが発生します。rust-toolchain.toml（[toolchain] / channel = "1.96"）でバージョンを固定してください。references/toolchain.md を参照してください。

4. Events は Messages です。 EventWriter / EventReader（Bevy 0.17 で名称変更）ではなく、MessageWriter<LocaleChangeEvent> と MessageReader<LocaleChangedEvent> を使用してください。references/locale-events.md を参照してください。

関連項目

• bevy-ui — FluentText<T> は Text、Node、Button と併用します。
• bevy-ecs-components — FluentText<T> に必要な #[derive(Component)] のパターン。
• bevy-assets — Bevy の AssetServer が .ftl ファイルを読み込む方法。ホットリロードに関係します。