diff --git a/docs/src/l10n.md b/docs/src/l10n.md index ec9c1db03..d23a4e652 100644 --- a/docs/src/l10n.md +++ b/docs/src/l10n.md @@ -2,6 +2,15 @@ This guide explains how localization (L10n) is implemented in the **Rust-based coreutils project**, detailing the use of [Fluent](https://projectfluent.org/) files, runtime behavior, and developer integration. +## 🏗️ Architecture Overview + +**English locale files are embedded directly in the binary**, ensuring that English always works regardless of how the software is installed. Other language locale files are loaded from the filesystem at runtime. + +### Source Repository Structure + +- **Main repository**: Contains English (`en-US.ftl`) locale files embedded in binaries +- **Translation repository**: [uutils/coreutils-l10n](https://github.com/uutils/coreutils-l10n) contains all other language translations + --- ## 📁 Fluent File Layout @@ -15,8 +24,8 @@ Each utility has its own set of translation files under: Examples: ``` - src/uu/ls/locales/en-US.ftl - src/uu/ls/locales/fr-FR.ftl + src/uu/ls/locales/en-US.ftl # Embedded in binary + src/uu/ls/locales/fr-FR.ftl # Loaded from filesystem ``` These files follow Fluent syntax and contain localized message patterns. @@ -31,12 +40,11 @@ Localization must be explicitly initialized at runtime using: setup_localization(path) ``` - This is typically done: - In `src/bin/coreutils.rs` for **multi-call binaries** - In `src/uucore/src/lib.rs` for **single-call utilities** -The string parameter determines the lookup path for Fluent files. +The string parameter determines the lookup path for Fluent files. **English always works** because it's embedded, but other languages need their `.ftl` files to be available at runtime. --- @@ -155,9 +163,13 @@ In release mode, **paths are resolved relative to the executable**: ``` /locales// + /share/locales// + ~/.local/share/coreutils/locales// + ~/.cargo/share/coreutils/locales// + /usr/share/coreutils/locales// ``` -If both fallback paths fail, an error is returned during `setup_localization()`. +If external locale files aren't found, the system falls back to embedded English locales. --- @@ -184,3 +196,15 @@ Fluent default (disabled here): ``` "\u{2068}Alice\u{2069}" ``` + +--- + +## 🔧 Embedded English Locales + +English locale files are always embedded directly in the binary during the build process. This ensures that: + +- **English always works** regardless of installation method (e.g., `cargo install`) +- **No runtime dependency** on external `.ftl` files for English +- **Fallback behavior** when other language files are missing + +The embedded English locales are generated at build time and included in the binary, providing a reliable fallback while still supporting full localization for other languages when their `.ftl` files are available.