bevy-fluent
Use when adding localization to a Bevy 0.20 app with `es-fluent-manager-bevy` 0.21, defining typed messages with `#[derive(EsFluent)]`, wrapping UI text in `FluentText<T>`, auto-registering locale updates with `#[derive(BevyFluentText)]`, or switching locales via `LocaleChangeMessage` / `LocaleChangedMessage`. Covers `I18nPlugin`, `RequestedLanguageId`, `ActiveLanguageId`, `i18n.toml` config, and hot-reload of `.ftl` assets.
How do I install this agent skill?
npx skills add https://github.com/chrisgliddon/bevy-skills --skill bevy-fluentIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides comprehensive documentation and code patterns for implementing i18n in Bevy 0.20 apps using the es-fluent library. It covers setup, CLI usage, and reactive UI components. No security risks were found.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Bevy 0.20 — Localization (es-fluent)
When to use this skill
- Adding Fluent-based i18n to a Bevy app (
es-fluent-manager-bevy = "0.21", which depends onbevy = "0.20.1"). - Defining typed UI messages with
#[derive(EsFluent)]and#[derive(BevyFluentText)]. - Wrapping a UI text entity with
FluentText<T>for automatic locale-driven refresh. - Switching locales at runtime via
LocaleChangeMessage; confirming viaLocaleChangedMessage. - Reading the requested / active locale from
RequestedLanguageId/ActiveLanguageId.
Canonical pattern — 5-file minimum shape
Cargo.toml:
[dependencies]
bevy = "0.20"
es-fluent = "0.21" # `derive` is a default feature
es-fluent-manager-bevy = "0.21" # `macros` + `file_watcher` are default features
unic-langid = "0.9"
i18n.toml (crate root, read at compile time):
fallback_language = "en"
assets_dir = "assets/locales"
src/i18n.rs:
es_fluent_manager_bevy::define_i18n_module!();
src/lib.rs — message types must live here (see Gotchas):
use bevy::prelude::*;
use es_fluent::EsFluent;
use es_fluent_manager_bevy::{
BevyFluentText, FluentText, I18nPlugin, LocaleChangeMessage, 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 the sibling Text (and into child Text entities).
commands.spawn((FluentText::new(UiMessage::StartGame), Text::new("")));
}
pub fn switch_locale_on_keypress(
keys: Res<ButtonInput<KeyCode>>,
requested: Res<RequestedLanguageId>,
mut locale_messages: MessageWriter<LocaleChangeMessage>,
) {
if keys.just_pressed(KeyCode::KeyL) {
let next = if requested.0.to_string() == "en" { langid!("fr") } else { langid!("en") };
locale_messages.write(LocaleChangeMessage(next));
}
}
src/main.rs — thin binary entry point:
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();
}
Replace my_game with your package name (hyphens become underscores). The full
walkthrough — lib-vs-binary rationale, package-name placeholder, pure-binary
workarounds — is in references/lib-target-layout.md.
Topics
| Topic | Reference |
|---|---|
Why types must live in the lib target; cargo es-fluent generate invisibility footgun; full layout | references/lib-target-layout.md |
BevyFluentText derive vs FluentText<T> component; trait bounds; Text::new("") | references/components.md |
LocaleChangeMessage (request) vs LocaleChangedMessage (confirmation); RequestedLanguageId; ActiveLanguageId | references/locale-events.md |
i18n.toml schema, assets_dir, I18nPluginConfig runtime override | references/i18n-toml.md |
generate, watch, check, clean, sync, tree, fmt, status, doctor, add-locale | references/cli.md |
rustc 1.99+ requirement; rust-toolchain.toml pin; failure modes on older toolchains | references/toolchain.md |
Gotchas
-
Version matrix.
es-fluent-manager-bevy 0.21.xrequiresbevy ^0.20.1and rustc 1.99.0.20.xtargets Bevy 0.19;0.18.xtargets Bevy 0.18. Pin the crate line to your Bevy line. See references/toolchain.md. -
Message types were renamed in 0.21.
LocaleChangeEvent→LocaleChangeMessage,LocaleChangedEvent→LocaleChangedMessage. Both are BevyMessages: useMessageWriter/MessageReader, neverEventWriter. Stale 0.18-era snippets fail with "cannot find typeLocaleChangeEvent". See references/locale-events.md. -
cargo es-fluent generateonly sees the lib target. Message enums declared only insrc/main.rsare invisible to the CLI and produce empty.ftloutput with no error. See references/lib-target-layout.md. -
Tno longer needsComponent(0.21).FluentText<T: FluentMessage>is the component; registration requiresT: FluentMessage + Send + Sync + 'static. The 0.18ToFluentString + Clone + Componentbound is gone. Keeping#[derive(Component)]onTis harmless. See references/components.md. -
Bevy-side text API changed underneath (0.19/0.20).
FluentTextwrites intoText; styling still comes from a siblingTextFont { font: FontSource, font_size: FontSize::Px(..), .. }.font_size: 24.0andfont: handlewithout.into()do not compile. Seebevy-ui. -
BevyI18nandActiveLanguageIdare exported in 0.21. The 0.18 workaround of querying bundles directly is no longer needed; use theBevyI18nsystem param for imperative lookups.
See also
bevy-ui—FluentText<T>sits next toText,TextFont,Node, andui_widgets::Button.bevy-migration-0-19-to-0-20— Bevy-side changes you hit while bumping the crate pair.bevy-ecs-components—#[derive(Component)]patterns for custom text wrappers.bevy-assets— howAssetServerloads.ftlfiles; relevant for hot-reload (file_watcherfeature).
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/chrisgliddon/bevy-skills/bevy-fluent">View bevy-fluent on skillZs</a>