feat(cli): language-aware devtrail explore (cli-3.4.0) (#57)

Wire `language` config and a new `--lang` flag through the explore TUI so
framework governance docs (QUICK-REFERENCE, AGENT-RULES, China regulatory
guides, etc.) are served from `i18n/<lang>/` when a translation exists,
falling back silently to English otherwise. Adopter content under user
subgroups stays untouched.

A shared utils::resolve_localized_path helper now backs both `devtrail
explore` and the existing `devtrail new` template lookup, so they share
one definition of how `i18n/<lang>/<filename>` resolves.

Resolution order for explore: --lang > config.language > "en".

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

Author: montfort

CHANGELOG.md

@@ -7,6 +7,18 @@ and this project uses [independent versioning](README.md#versioning) for Framewo
 
 ---
 
+## CLI 3.4.0 — Language-Aware `devtrail explore`
+
+### Added (CLI)
+- `devtrail explore` now resolves framework governance docs (`QUICK-REFERENCE`, `AGENT-RULES`, `CHINA-REGULATORY-FRAMEWORK`, `PIPL-PIPIA-GUIDE`, etc.) in the language set by `language` in `.devtrail/config.yml`. With `language: zh-CN` or `es`, the navigation tree, titles, and document body all switch to the translated variant — the English original is used silently as a fallback when no translation exists. CJK rendering relies on the Unicode-safe layout work done in 3.2.3 / 3.2.4.
+- New `--lang <code>` flag on `devtrail explore` to override the configured language for a single session (e.g., `devtrail explore --lang zh-CN`). Resolution order: `--lang` > `config.language` > `en`.
+- Adopter-authored content under subgroups (`02-design/decisions/`, `05-operations/incidents/`, etc.) is intentionally never localized — it has no canonical i18n sibling.
+
+### Changed (CLI)
+- Shared `utils::resolve_localized_path()` is now the single source of truth for `i18n/<lang>/<filename>` lookups. `devtrail new` (templates) and `devtrail explore` (governance docs) both delegate to it.
+
+---
+
 ## Framework 4.3.0 / CLI 3.3.0 — China Regulatory Coverage (TC260, PIPL, GB 45438, CAC, GB/T 45652, CSL)
 
 DevTrail now supports six Chinese AI / data regulations as an opt-in regional scope. Existing projects are unaffected — Chinese frameworks activate only when `regional_scope: china` is added to `.devtrail/config.yml`.

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.3.0` | The `devtrail` binary |
+| CLI | `cli-` | `cli-3.4.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.3.0"
+version = "3.4.0"
 edition = "2021"
 description = "CLI tool for DevTrail - Documentation Governance for AI-Assisted Development"
 license = "MIT"

cli/Cargo.toml

@@ -1,8 +1,9 @@
 use anyhow::{bail, Result};
 
+use crate::config::DevTrailConfig;
 use crate::utils;
 
-pub fn run(path: &str) -> Result<()> {
+pub fn run(path: &str, lang_override: Option<&str>) -> Result<()> {
     let resolved = match utils::resolve_project_root(path) {
         Some(r) => r,
         None => {
@@ -12,5 +13,13 @@ pub fn run(path: &str) -> Result<()> {
         }
     };
 
-    crate::tui::run(&resolved.path, resolved.is_fallback)
+    // Effective language: --lang flag > config.language > "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()),
+    };
+
+    crate::tui::run(&resolved.path, resolved.is_fallback, &language)
 }

cli/src/commands/explore.rs

@@ -204,15 +204,8 @@ fn resolve_template_path(
     lang: &str,
 ) -> PathBuf {
     let template_name = format!("TEMPLATE-{}.md", doc_type.prefix());
-    if lang != "en" {
-        let i18n_path = devtrail_dir
-            .join(format!("templates/i18n/{}", lang))
-            .join(&template_name);
-        if i18n_path.exists() {
-            return i18n_path;
-        }
-    }
-    devtrail_dir.join("templates").join(&template_name)
+    let templates_dir = devtrail_dir.join("templates");
+    utils::resolve_localized_path(&templates_dir, &template_name, lang)
 }
 
 #[cfg(test)]

cli/src/commands/new.rs

@@ -168,6 +168,10 @@ enum Commands {
         /// Target directory (default: current directory)
         #[arg(default_value = ".")]
         path: String,
+        /// Display language override (e.g., en, es, zh-CN). Defaults to
+        /// `language` from .devtrail/config.yml.
+        #[arg(long)]
+        lang: Option<String>,
     },
 }
 
@@ -219,7 +223,7 @@ fn main() {
             top,
         } => commands::analyze::run(&path, threshold, &output, top),
         #[cfg(feature = "tui")]
-        Commands::Explore { path } => commands::explore::run(&path),
+        Commands::Explore { path, lang } => commands::explore::run(&path, lang.as_deref()),
     };
 
     if let Err(e) = result {

cli/src/main.rs

@@ -96,12 +96,15 @@ pub struct App {
     pub project_root: PathBuf,
     /// Whether we're using a fallback path (repo root instead of cwd)
     pub is_fallback: bool,
+    /// Active display language ("en", "es", "zh-CN"). Persisted on the app
+    /// so refresh ('r') rebuilds the index in the same locale.
+    pub language: String,
 }
 
 impl App {
-    pub fn new(project_root: &Path, is_fallback: bool) -> Self {
+    pub fn new(project_root: &Path, is_fallback: bool, language: &str) -> Self {
         let devtrail_dir = project_root.join(".devtrail");
-        let index = DocIndex::build(&devtrail_dir);
+        let index = DocIndex::build(&devtrail_dir, language);
         let num_groups = index.groups.len();
 
         Self {
@@ -125,6 +128,7 @@ impl App {
             should_quit: false,
             project_root: project_root.to_path_buf(),
             is_fallback,
+            language: language.to_string(),
         }
     }
 

cli/src/tui/app.rs

@@ -130,7 +130,8 @@ fn handle_key(app: &mut App, key: KeyEvent) {
         KeyCode::Char('r') => {
             let root = app.project_root.clone();
             let fallback = app.is_fallback;
-            *app = App::new(&root, fallback);
+            let language = app.language.clone();
+            *app = App::new(&root, fallback, &language);
         }
 
         _ => {}

cli/src/tui/event.rs

@@ -2,6 +2,7 @@ use std::collections::HashMap;
 use std::path::{Path, PathBuf};
 
 use super::document::DocFrontMatter;
+use crate::utils;
 
 /// A group in the documentation hierarchy (e.g., "02-design")
 #[derive(Debug, Clone)]
@@ -109,8 +110,15 @@ const GROUP_DEFS: &[(&str, &str, &[SubgroupDef])] = &[
 ];
 
 impl DocIndex {
-    /// Build the index by scanning the .devtrail directory
-    pub fn build(devtrail_dir: &Path) -> Self {
+    /// Build the index by scanning the .devtrail directory.
+    ///
+    /// `language` selects the preferred locale (e.g. `"en"`, `"es"`, `"zh-CN"`).
+    /// When non-`"en"`, framework files at group roots (e.g. governance docs)
+    /// are transparently swapped for their `i18n/<lang>/<filename>` counterpart
+    /// when one exists; otherwise the English original is used. User-authored
+    /// content under subgroups (`decisions/`, `incidents/`, ...) is never
+    /// localized.
+    pub fn build(devtrail_dir: &Path, language: &str) -> Self {
         let mut groups = Vec::new();
         let mut relations = RelationIndex::default();
         let mut total_docs = 0;
@@ -128,17 +136,20 @@ impl DocIndex {
                 continue;
             }
 
-            // Scan files directly in the group dir (non-recursive, subgroups scanned separately)
-            let files = scan_md_files_flat(&group_path, &mut relations);
+            // Scan files directly in the group dir. Group roots host framework
+            // docs that ship with translations under `i18n/<lang>/`, so apply
+            // localization here.
+            let files = scan_md_files_flat(&group_path, Some(language), &mut relations);
             total_docs += files.len();
 
             // Scan subgroups and their user-created subdirectories
             let mut subgroups = Vec::new();
             for &(sg_name, sg_label) in subgroup_defs {
                 let sg_path = group_path.join(sg_name);
                 if sg_path.exists() {
-                    // Files directly in the subgroup
-                    let sg_files = scan_md_files_flat(&sg_path, &mut relations);
+                    // Subgroups hold adopter content, which has no localized
+                    // sibling to swap to.
+                    let sg_files = scan_md_files_flat(&sg_path, None, &mut relations);
                     total_docs += sg_files.len();
 
                     // Scan user-created subdirectories
@@ -279,8 +290,18 @@ fn entry_matches(filename: &str, path: &Path, ref_filename: &str, clean_ref: &st
     false
 }
 
-/// Scan only direct .md files in a directory (non-recursive, for group root dirs)
-fn scan_md_files_flat(dir: &Path, relations: &mut RelationIndex) -> Vec<DocEntry> {
+/// Scan only direct .md files in a directory (non-recursive, for group root dirs).
+///
+/// When `localize` is `Some(lang)` and a translation exists at
+/// `dir/i18n/<lang>/<filename>`, the entry's path (and therefore the title /
+/// frontmatter shown in the TUI) is taken from the translated file. Pass
+/// `None` for directories whose contents are user-authored and have no
+/// localized counterpart.
+fn scan_md_files_flat(
+    dir: &Path,
+    localize: Option<&str>,
+    relations: &mut RelationIndex,
+) -> Vec<DocEntry> {
     let mut entries = Vec::new();
 
     let Ok(read_dir) = std::fs::read_dir(dir) else {
@@ -314,11 +335,19 @@ fn scan_md_files_flat(dir: &Path, relations: &mut RelationIndex) -> Vec<DocEntry
             .unwrap_or("")
             .to_string();
 
-        let meta = quick_scan_frontmatter(&path, relations);
+        // Prefer a localized variant when this directory is a framework
+        // root that ships with translations. Falls back to the English
+        // original silently when no translation exists.
+        let resolved_path = match localize {
+            Some(lang) => utils::resolve_localized_path(dir, &filename, lang),
+            None => path,
+        };
+
+        let meta = quick_scan_frontmatter(&resolved_path, relations);
 
         entries.push(DocEntry {
             filename,
-            path,
+            path: resolved_path,
             title: meta.title,
             id: meta.id,
             doc_type: meta.doc_type,
@@ -540,3 +569,141 @@ fn quick_scan_frontmatter(path: &Path, relations: &mut RelationIndex) -> Scanned
         None => fallback_meta(path, Some(body)),
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Build a fixture .devtrail tree with a translated and an English-only
+    /// governance doc, and verify DocIndex prefers the translation when
+    /// language=zh-CN, falling back to English silently when no translation
+    /// exists.
+    #[test]
+    fn build_zh_cn_swaps_governance_path_when_translation_present() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        let devtrail_dir = tmp.path().join(".devtrail");
+        let governance = devtrail_dir.join("00-governance");
+        let zh = governance.join("i18n").join("zh-CN");
+        std::fs::create_dir_all(&zh).unwrap();
+
+        // Translated doc (governance).
+        std::fs::write(
+            governance.join("QUICK-REFERENCE.md"),
+            "# Quick Reference\n\nEnglish body.\n",
+        )
+        .unwrap();
+        std::fs::write(
+            zh.join("QUICK-REFERENCE.md"),
+            "# 快速参考\n\n中文正文。\n",
+        )
+        .unwrap();
+
+        // English-only doc (no zh-CN sibling).
+        std::fs::write(
+            governance.join("ISO-25010-2023-REFERENCE.md"),
+            "# ISO 25010\n\nEnglish only.\n",
+        )
+        .unwrap();
+
+        let index = DocIndex::build(&devtrail_dir, "zh-CN");
+
+        let governance_group = index
+            .groups
+            .iter()
+            .find(|g| g.name == "00-governance")
+            .expect("governance group present");
+
+        let quick_ref = governance_group
+            .files
+            .iter()
+            .find(|e| e.filename == "QUICK-REFERENCE.md")
+            .expect("QUICK-REFERENCE indexed");
+        assert_eq!(
+            quick_ref.path,
+            zh.join("QUICK-REFERENCE.md"),
+            "zh-CN translation should be preferred"
+        );
+        assert_eq!(quick_ref.title, "快速参考");
+
+        let iso = governance_group
+            .files
+            .iter()
+            .find(|e| e.filename == "ISO-25010-2023-REFERENCE.md")
+            .expect("ISO doc indexed");
+        assert_eq!(
+            iso.path,
+            governance.join("ISO-25010-2023-REFERENCE.md"),
+            "missing translation must fall back to English silently"
+        );
+        assert_eq!(iso.title, "ISO 25010");
+    }
+
+    #[test]
+    fn build_en_never_descends_into_i18n_subdirs() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        let devtrail_dir = tmp.path().join(".devtrail");
+        let governance = devtrail_dir.join("00-governance");
+        let zh = governance.join("i18n").join("zh-CN");
+        std::fs::create_dir_all(&zh).unwrap();
+
+        std::fs::write(governance.join("AGENT-RULES.md"), "# Rules").unwrap();
+        std::fs::write(zh.join("AGENT-RULES.md"), "# 规则").unwrap();
+
+        let index = DocIndex::build(&devtrail_dir, "en");
+        let governance_group = index
+            .groups
+            .iter()
+            .find(|g| g.name == "00-governance")
+            .unwrap();
+
+        // Exactly one entry: the English root file. The translation must
+        // never appear as a separate doc (no duplication of total_docs).
+        assert_eq!(governance_group.files.len(), 1);
+        assert_eq!(
+            governance_group.files[0].path,
+            governance.join("AGENT-RULES.md")
+        );
+    }
+
+    #[test]
+    fn build_does_not_localize_user_subgroups() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        let devtrail_dir = tmp.path().join(".devtrail");
+        let decisions = devtrail_dir.join("02-design").join("decisions");
+        let stray_zh = decisions.join("i18n").join("zh-CN");
+        std::fs::create_dir_all(&stray_zh).unwrap();
+
+        std::fs::write(
+            decisions.join("ADR-2026-01-01-001-foo.md"),
+            "# English ADR",
+        )
+        .unwrap();
+        // A translation file under a user subgroup must be ignored — adopter
+        // content has no canonical English<->zh mapping.
+        std::fs::write(stray_zh.join("ADR-2026-01-01-001-foo.md"), "# 中文 ADR")
+            .unwrap();
+
+        let index = DocIndex::build(&devtrail_dir, "zh-CN");
+        let design = index
+            .groups
+            .iter()
+            .find(|g| g.name == "02-design")
+            .unwrap();
+        let decisions_sg = design
+            .subgroups
+            .iter()
+            .find(|s| s.name == "decisions")
+            .unwrap();
+
+        let adr = decisions_sg
+            .files
+            .iter()
+            .find(|e| e.filename == "ADR-2026-01-01-001-foo.md")
+            .expect("ADR indexed");
+        assert_eq!(
+            adr.path,
+            decisions.join("ADR-2026-01-01-001-foo.md"),
+            "user-authored docs must not be swapped for any i18n sibling"
+        );
+    }
+}