Skip to main content

Module i18n

Module i18n 

Source
Expand description

Human-facing messages for stderr prose (en / pt-BR).

§Product contract (agent-first)

  • Stdout (JSON envelopes, markdown data): always English technical content. Agents parse error.message as stable English; never localize JSON fields.
  • Stderr human path (--format text|markdown, progress, doctor prose): localized via Locale after resolution at process start.
  • Technical logs (tracing): English only.

§Resolution precedence

  1. Explicit CLI --lang / config lang (fail-closed)
  2. OS locale via sys_locale::get_locale (soft-fallback)
  3. Default en

Explicit tags accept only en / en-* and exact pt-BR (after BCP47-ish normalization). Bare pt and regional Portuguese other than pt-BR fail closed (exit 65). Soft system detection maps any pt primary language to Brazilian Portuguese messages (MVP has no pt-PT bundle).

§What step 2 actually reads

sys_locale::get_locale consults the host’s locale, which on Unix means LC_ALL, LC_MESSAGES and LANG. So LANG=pt_BR.UTF-8 does change stderr prose when no explicit tag is given — state it plainly rather than claim the process never touches the environment, because the read is real and merely delegated to a dependency where the policy gate cannot see it.

This belongs to the same category as NO_COLOR and TERM in crate::platform: it describes the user’s environment, the way isatty does, and carries no product configuration. The distinction that matters is the one this module already enforces — no product knob comes from the environment, and stdout stays English byte for byte whatever LANG says. An explicit --lang or the TOML lang key always outranks the host.

§Out of scope (OOS) for this one-shot CLI

Full Rules Rust i18n stacks are not product requirements here:

  • fluent / fluent-langneg / i18n-embed resource bundles
  • unic-langid (two fixed locales; lightweight normalize is enough)
  • Top-20 languages, Cargo i18n-* features, RTL/CJK/ICU calendars
  • Global OnceLock (locale is threaded as a value for testability)
  • Admin reload of language, Weblate/Crowdin pipelines
  • Windows console UTF-8 code-page bootstrap (no Windows-only deps)
  • Translating clap --help / about strings

Keep this module the single place for human stderr copy.

Enums§

Locale
Resolved UI locale for stderr prose.