es-fluent-cli

The official command-line tool for es-fluent.

This tool automatically manages your Fluent (.ftl) translation files by analyzing your Rust code. It finds types with #[derive(EsFluent)] and creates corresponding message entries, so you don't have to keep them in sync manually.

Installation

cargo install es-fluent-cli --locked

Commands

Ensure you have an i18n.toml in your crate root:

# Default fallback language (required)
fallback_language = "en-US"

# Path to FTL assets relative to the config file (required)
assets_dir = "assets/locales"

# Features to enable if the crate’s es-fluent derives are gated behind a feature (optional)
fluent_feature = ["my-feature"]

Generate

When you add new localizable structs or enums to your code, run:

cargo es-fluent generate

This will:

1. Scan your src/ directory.
2. Update i18n/en-US/{your_crate}.ftl.
   • New items: Added as new messages.
   • Changed items: Variables updated (e.g. if you added a field).
   • Existing translations: Preserved untouched.

Use --dry-run to preview changes without writing them. Use --force-run to bypass the staleness cache and force a rebuild.

Watch

Same as generate, but runs in watch mode, updating FTL files as you type:

cargo es-fluent watch

Check

To ensure all your translations are valid and no keys are missing:

cargo es-fluent check

Use --all to check all locales, not just the fallback language, --ignore <CRATE> to skip specific crates, --force-run to bypass the staleness cache.

Clean

Remove orphan keys and groups that are no longer present in your source code:

cargo es-fluent clean

Use --dry-run to preview changes without writing them. Use --all to clean all locales. Use --force-run to bypass the staleness cache.

Format

Standardize the formatting of your FTL files using fluent-syntax rules:

cargo es-fluent format

Use --dry-run to preview changes without writing them. Use --all to format all locales.

Sync

Propagate keys from your fallback language to other languages (e.g., from en-US to fr and de), creating placeholders for missing translations:

cargo es-fluent sync

Use --locale <LANG> to sync a specific locale, or --all to sync all locales, --dry-run to preview changes without writing them.