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.messageas stable English; never localize JSON fields. - Stderr human path (
--format text|markdown, progress, doctor prose): localized viaLocaleafter resolution at process start. - Technical logs (
tracing): English only.
§Resolution precedence
- Explicit CLI
--lang/ configlang(fail-closed) - OS locale via
sys_locale::get_locale(soft-fallback) - 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-embedresource bundlesunic-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.