feat(cli): OS locale auto-detect + bump cli-3.5.0 (#61)

Closes the language-aware explore series started in 3.4.0. Adds the
final missing fallback: when a project has no .devtrail/config.yml,
devtrail explore / new / status now read \$LC_ALL / \$LANG and map a
POSIX locale (e.g. zh_CN.UTF-8, es_MX.UTF-8) onto the nearest supported
language. Existing projects with a config file are unaffected — an
explicit language: en is still treated as a deliberate user choice and
never overridden by env vars.

New utils::detect_os_locale + parse_posix_locale handle the parsing.
Traditional Chinese (zh_TW / zh_HK) returns None on purpose because
DevTrail only ships Simplified.

DevTrailConfig::resolve_language is now the single entry point used by
all three commands, so they agree on the effective language. Resolution
order: --lang > config.language (when file exists) > OS locale > "en".

Bumps version 3.4.1 → 3.5.0. CHANGELOG entry covers all three pendientes
shipped in this minor (translated TUI shell, live language switcher,
locale auto-detect). 6 docs updated: 3 README versioning tables and 3
CLI-REFERENCE.md (EN/ES/zh-CN) with the new resolution order and the L
keybind.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: montfort

CHANGELOG.md

@@ -7,6 +7,20 @@ and this project uses [independent versioning](README.md#versioning) for Framewo
 
 ---
 
+## CLI 3.5.0 — TUI i18n Polish: Translated Shell, Live Switcher, Locale Auto-Detect
+
+Three changes that complete the language-aware `devtrail explore` work started in 3.4.0. Together they make the TUI feel native to non-English users instead of just "translated docs inside an English shell."
+
+### Added (CLI)
+- **Translated TUI shell**: navigation tree group/subgroup labels, sort hints, status-bar key hints, notifications, and the `?` help popup all render in `es` and `zh-CN` when the active language is non-English. Untranslated strings fall back to English silently. New module `cli/src/tui/i18n_strings.rs` is the single lookup point — extending to a new locale is one entry per call site.
+- **Live language switcher**: press `L` inside `devtrail explore` to cycle the display language (`en → es → zh-CN → en`) without quitting. The doc index is rebuilt on the spot, the document body cache is dropped so the next open reads the localized file, and the status bar shows a translated notification (`Idioma: es`, `语言: zh-CN`). Documented in the help popup.
+- **OS locale auto-detection**: when a project has no `.devtrail/config.yml`, `devtrail explore` / `new` / `status` now read `$LC_ALL` / `$LANG` and map a POSIX locale (e.g., `zh_CN.UTF-8`, `es_MX.UTF-8`) to the nearest supported language. Existing projects with a config file are unaffected — an explicit `language: en` is still treated as a deliberate user choice and never overridden by env vars. Traditional Chinese (`zh_TW`, `zh_HK`) returns `None` because DevTrail only ships Simplified.
+
+### Changed (CLI)
+- New `DevTrailConfig::resolve_language(project_root)` is now the single entry point used by `explore`, `new`, and `status`, so all three commands agree on the effective language. Resolution order: `--lang` flag > `config.language` (when config file exists) > OS locale > `"en"`.
+
+---
+
 ## CLI 3.4.1 — Code-Block Background No Longer Fragments on Narrow Panels
 
 ### Fixed (CLI)

README.md

@@ -207,7 +207,7 @@ DevTrail uses independent version tags for each component:
 | Component | Tag prefix | Example | Includes |
 |-----------|-----------|---------|----------|
 | Framework | `fw-` | `fw-4.3.0` | Templates (12 types), governance, directives |
-| CLI | `cli-` | `cli-3.4.1` | The `devtrail` binary |
+| CLI | `cli-` | `cli-3.5.0` | The `devtrail` binary |
 
 Check installed versions with `devtrail status` or `devtrail about`.
 

cli/Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "devtrail-cli"
-version = "3.4.1"
+version = "3.5.0"
 edition = "2021"
 description = "CLI tool for DevTrail - Documentation Governance for AI-Assisted Development"
 license = "MIT"

cli/Cargo.toml

@@ -13,12 +13,11 @@ pub fn run(path: &str, lang_override: Option<&str>) -> Result<()> {
         }
     };
 
-    // Effective language: --lang flag > config.language > "en".
+    // Effective language: --lang flag > config.language (when config
+    // exists) > $LC_ALL / $LANG > "en".
     let language = match lang_override {
         Some(l) => l.to_string(),
-        None => DevTrailConfig::load(&resolved.path)
-            .map(|c| c.language)
-            .unwrap_or_else(|_| "en".to_string()),
+        None => DevTrailConfig::resolve_language(&resolved.path),
     };
 
     crate::tui::run(&resolved.path, resolved.is_fallback, &language)

cli/src/commands/explore.rs

@@ -15,7 +15,8 @@ pub fn run(path: &str, doc_type_arg: Option<&str>, title_arg: Option<&str>) -> R
     let devtrail_dir = target.join(".devtrail");
 
     let config = DevTrailConfig::load(&target).unwrap_or_default();
-    let lang = &config.language;
+    let resolved_language = DevTrailConfig::resolve_language(&target);
+    let lang = resolved_language.as_str();
     let china = config.has_region("china");
 
     // Select document type

cli/src/commands/new.rs

@@ -272,13 +272,10 @@ fn load_version(project_root: &std::path::Path) -> String {
 }
 
 fn load_language(project_root: &std::path::Path) -> String {
-    match DevTrailConfig::load(project_root) {
-        Ok(c) => c.language,
-        Err(_) => {
-            utils::warn("Could not read config.yml");
-            "unknown".to_string()
-        }
-    }
+    // Use the same resolver as `explore` / `new` so all three commands
+    // agree on the effective language (config when present, else OS locale,
+    // else "en").
+    DevTrailConfig::resolve_language(project_root)
 }
 
 fn count_documents(devtrail_dir: &std::path::Path) -> Vec<(&'static str, &'static str, usize)> {

cli/src/commands/status.rs

@@ -75,6 +75,30 @@ impl DevTrailConfig {
             .iter()
             .any(|r| r.eq_ignore_ascii_case(region))
     }
+
+    /// Resolve the effective display language for a project, applying all
+    /// fallbacks in order:
+    ///
+    /// 1. If `.devtrail/config.yml` exists on disk, the value of its
+    ///    `language` key (defaulting to `"en"` when the field is absent).
+    ///    A configured value — even the default `"en"` — is treated as an
+    ///    explicit choice and is never overridden by env vars.
+    /// 2. If no config file exists, parse `$LC_ALL` / `$LANG` and map it
+    ///    onto a supported locale (`en`, `es`, `zh-CN`).
+    /// 3. Final fallback: `"en"`.
+    ///
+    /// This is the single entry point used by `devtrail explore`,
+    /// `devtrail new`, and `devtrail status` so they all agree on which
+    /// language to use.
+    pub fn resolve_language(project_root: &Path) -> String {
+        let config_path = project_root.join(".devtrail/config.yml");
+        if config_path.exists() {
+            return Self::load(project_root)
+                .map(|c| c.language)
+                .unwrap_or_else(|_| default_language());
+        }
+        crate::utils::detect_os_locale().unwrap_or_else(default_language)
+    }
 }
 
 #[cfg(test)]
@@ -100,6 +124,53 @@ mod tests {
         assert!(cfg.has_region("global"));
         assert!(!cfg.has_region("eu"));
     }
+
+    #[test]
+    fn resolve_language_uses_config_value_when_present() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        let dt = tmp.path().join(".devtrail");
+        std::fs::create_dir_all(&dt).unwrap();
+        std::fs::write(dt.join("config.yml"), "language: zh-CN\n").unwrap();
+
+        // Even if $LANG is set to something else, the file's explicit
+        // value must win — config is treated as a deliberate user choice.
+        let prev = std::env::var("LANG").ok();
+        unsafe { std::env::set_var("LANG", "fr_FR.UTF-8"); }
+        let lang = DevTrailConfig::resolve_language(tmp.path());
+        if let Some(p) = prev {
+            unsafe { std::env::set_var("LANG", p); }
+        } else {
+            unsafe { std::env::remove_var("LANG"); }
+        }
+        assert_eq!(lang, "zh-CN");
+    }
+
+    #[test]
+    fn resolve_language_falls_back_to_default_when_no_config_no_env() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        // No .devtrail/config.yml in tmp.
+        // Clear env vars so the OS locale path can't return a real value.
+        let prev_all = std::env::var("LC_ALL").ok();
+        let prev_lang = std::env::var("LANG").ok();
+        unsafe {
+            std::env::remove_var("LC_ALL");
+            std::env::set_var("LANG", "C");
+        }
+        let lang = DevTrailConfig::resolve_language(tmp.path());
+        // Restore env.
+        unsafe {
+            if let Some(p) = prev_all {
+                std::env::set_var("LC_ALL", p);
+            }
+            if let Some(p) = prev_lang {
+                std::env::set_var("LANG", p);
+            } else {
+                std::env::remove_var("LANG");
+            }
+        }
+        // "C" maps to "en", so the result is "en".
+        assert_eq!(lang, "en");
+    }
 }
 
 /// Checksums tracking file for detecting user modifications

cli/src/config.rs

@@ -104,6 +104,40 @@ pub fn resolve_project_root(path: &str) -> Option<ResolvedPath> {
     None
 }
 
+/// Read `$LC_ALL` (preferred when set) or `$LANG` and map a POSIX locale
+/// string like `zh_CN.UTF-8` or `es_MX` to one of the languages DevTrail
+/// supports (`en`, `es`, `zh-CN`). Returns `None` when no env var is set
+/// or when the territory points at an unsupported variant (e.g.,
+/// Traditional Chinese in `zh_TW` / `zh_HK`). Callers fall back to `"en"`.
+pub fn detect_os_locale() -> Option<String> {
+    let raw = std::env::var("LC_ALL")
+        .ok()
+        .filter(|v| !v.is_empty())
+        .or_else(|| std::env::var("LANG").ok().filter(|v| !v.is_empty()))?;
+    parse_posix_locale(&raw)
+}
+
+/// Parse a POSIX locale string (e.g. `zh_CN.UTF-8`, `es`, `C`) and map it
+/// to a DevTrail-supported language code. Public for unit testing.
+pub fn parse_posix_locale(raw: &str) -> Option<String> {
+    // Strip charset (`.UTF-8`) and modifier (`@euro`) suffixes first.
+    let trimmed = raw.split('.').next()?.split('@').next()?;
+    if trimmed.is_empty() {
+        return None;
+    }
+    let mut parts = trimmed.splitn(2, '_');
+    let lang = parts.next()?;
+    let territory = parts.next();
+    match (lang, territory) {
+        ("zh", Some("CN")) | ("zh", Some("SG")) | ("zh", None) => Some("zh-CN".to_string()),
+        // Traditional Chinese (TW / HK / MO) — DevTrail only ships zh-CN.
+        ("zh", _) => None,
+        ("es", _) => Some("es".to_string()),
+        ("en", _) | ("C", _) | ("POSIX", _) => Some("en".to_string()),
+        _ => None,
+    }
+}
+
 /// Resolve `<dir>/<filename>` honoring an optional translation under
 /// `<dir>/i18n/<lang>/<filename>`. When `lang` is `"en"` (or any value where
 /// the localized variant is absent), returns the root path unchanged. This is
@@ -267,6 +301,54 @@ mod tests {
         assert_eq!(resolved, dir.join("FOO.md"));
     }
 
+    #[test]
+    fn parse_posix_locale_zh_cn() {
+        assert_eq!(parse_posix_locale("zh_CN.UTF-8"), Some("zh-CN".into()));
+        assert_eq!(parse_posix_locale("zh_CN"), Some("zh-CN".into()));
+        assert_eq!(parse_posix_locale("zh_SG.UTF-8"), Some("zh-CN".into()));
+        // Bare "zh" with no territory: assume Simplified.
+        assert_eq!(parse_posix_locale("zh"), Some("zh-CN".into()));
+    }
+
+    #[test]
+    fn parse_posix_locale_traditional_chinese_unsupported() {
+        // We don't ship Traditional translations — those should fall back
+        // through to "en" via the caller's None handling, not silently
+        // claim Simplified.
+        assert_eq!(parse_posix_locale("zh_TW.UTF-8"), None);
+        assert_eq!(parse_posix_locale("zh_HK.UTF-8"), None);
+    }
+
+    #[test]
+    fn parse_posix_locale_spanish_any_territory() {
+        assert_eq!(parse_posix_locale("es_MX.UTF-8"), Some("es".into()));
+        assert_eq!(parse_posix_locale("es_ES"), Some("es".into()));
+        assert_eq!(parse_posix_locale("es_AR.UTF-8"), Some("es".into()));
+    }
+
+    #[test]
+    fn parse_posix_locale_english_and_pseudo() {
+        assert_eq!(parse_posix_locale("en_US.UTF-8"), Some("en".into()));
+        assert_eq!(parse_posix_locale("en"), Some("en".into()));
+        assert_eq!(parse_posix_locale("C"), Some("en".into()));
+        assert_eq!(parse_posix_locale("POSIX"), Some("en".into()));
+    }
+
+    #[test]
+    fn parse_posix_locale_unsupported_returns_none() {
+        // French isn't translated yet; caller must fall back to "en".
+        assert_eq!(parse_posix_locale("fr_FR.UTF-8"), None);
+        assert_eq!(parse_posix_locale("ja_JP.UTF-8"), None);
+        assert_eq!(parse_posix_locale(""), None);
+    }
+
+    #[test]
+    fn parse_posix_locale_strips_charset_and_modifier() {
+        // `@modifier` after the charset (or before it) appears in some
+        // locales; we strip whatever follows the first `@` or `.`.
+        assert_eq!(parse_posix_locale("es_ES@euro"), Some("es".into()));
+    }
+
     #[test]
     fn resolve_localized_path_for_english_skips_lookup() {
         let tmp = tempfile::TempDir::new().unwrap();

cli/src/utils.rs

@@ -49,7 +49,7 @@ DevTrail uses **independent version tags** for each component:
 | Component | Tag prefix | Example | What it includes |
 |-----------|-----------|---------|------------------|
 | Framework | `fw-` | `fw-4.3.0` | Templates (12 types), governance docs, directives |
-| CLI | `cli-` | `cli-3.4.1` | The `devtrail` binary |
+| CLI | `cli-` | `cli-3.5.0` | The `devtrail` binary |
 
 Framework and CLI are released independently. A framework update does not require a CLI update, and vice versa.
 
@@ -110,7 +110,7 @@ $ devtrail update
 Updating framework...
 ✔ Framework updated to fw-4.3.0
 Updating CLI...
-✔ CLI updated to cli-3.4.1
+✔ CLI updated to cli-3.5.0
 ```
 
 ---
@@ -143,11 +143,11 @@ Use `--method` to override auto-detection: `--method=github` or `--method=cargo`
 
 ```bash
 $ devtrail update-cli
-✔ CLI updated to cli-3.4.1
+✔ CLI updated to cli-3.5.0
 
 $ devtrail update-cli --method=cargo
 Compiling from source, this may take a few minutes...
-✔ CLI updated to cli-3.4.1
+✔ CLI updated to cli-3.5.0
 ```
 
 ---
@@ -210,7 +210,7 @@ $ devtrail status
   ┌───────────┬──────────────────────────┐
   │ Path      │ /home/user/my-project    │
   │ Framework │ fw-4.3.0                 │
-  │ CLI       │ cli-3.4.1                │
+  │ CLI       │ cli-3.5.0                │
   │ Language  │ en                       │
   └───────────┴──────────────────────────┘
 
@@ -641,7 +641,14 @@ Browse and read DevTrail documentation interactively in a terminal UI.
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--lang <code>` | `language` from `.devtrail/config.yml`, else `en` | Display language for framework governance docs (`en`, `es`, `zh-CN`). Falls back silently to English when a translation is missing. |
+| `--lang <code>` | resolved from project (see below) | Display language for the TUI shell and framework governance docs (`en`, `es`, `zh-CN`). Falls back silently to English when a translation is missing. |
+
+**Language resolution order** (since cli-3.5.0):
+
+1. `--lang <code>` flag, when provided
+2. `language` field in `.devtrail/config.yml`, when the file exists (an explicit value — even `language: en` — is treated as a deliberate user choice)
+3. `$LC_ALL` / `$LANG` env vars, mapped to a supported locale (e.g., `zh_CN.UTF-8` → `zh-CN`, `es_MX.UTF-8` → `es`). Traditional Chinese (`zh_TW` / `zh_HK`) and other unsupported locales fall through.
+4. `en`
 
 **Features:**
 
@@ -662,6 +669,7 @@ Browse and read DevTrail documentation interactively in a terminal UI.
 | `Tab` | Cycle panels: Navigation → Metadata → Document |
 | `f` | Toggle fullscreen document |
 | `/` | Search |
+| `L` | Cycle display language (`en → es → zh-CN`) |
 | `Esc` | Back / Collapse / Clear search |
 | `?` | Help popup with all shortcuts |
 | `q` | Quit |
@@ -687,7 +695,7 @@ Show version, authorship, and license information.
 ```bash
 $ devtrail about
 DevTrail CLI
-  CLI version:       cli-3.4.1
+  CLI version:       cli-3.5.0
   Framework version: fw-4.3.0
   Author:            Strange Days Tech, S.A.S.
   License:           MIT