Merge pull request #12 from WendellXY/feat-translate-command-mentra

Add Mentra-backed translate command

Author: WendellXY

README.md

@@ -61,6 +61,7 @@ This is a `0.9.1` release available on [crates.io](https://crates.io/crates/lang
 - Edit (add/update/remove): `langcodec edit set -i 'locales/**/*.strings' -k welcome -v "Hello"` (use `--dry-run` to preview)
 - Normalize and detect drift: `langcodec normalize -i 'locales/**/*.{strings,xml,csv,tsv,xcstrings}' --check`
 - Sync existing keys only: `langcodec sync --source A.xcstrings --target B.xcstrings --match-lang en`
+- Translate drafts with Mentra: `langcodec translate --source source.xcstrings --target target.xcstrings --source-lang en --target-lang fr --provider openai --model gpt-4.1-mini`
 - View: `langcodec view -i strings.xml --full`
 - View filtered untranslated/review-needed keys: `langcodec view -i Localizable.xcstrings --status new,needs_review --keys-only`
 - View filtered results as JSON: `langcodec view -i Localizable.xcstrings --status new --lang fr --json`
@@ -102,6 +103,7 @@ This is a `0.9.1` release available on [crates.io](https://crates.io/crates/lang
 - Android path inference: `values/strings.xml` (no qualifier) defaults to English (`en`).
 - When converting to `.xcstrings`, if `source_language` or `version` metadata is missing, the CLI defaults them to `en` and `1.0` respectively (overridable via flags).
 - Strict status filtering note: `langcodec --strict view --status ...` requires explicit status metadata (supported in v1: `.xcstrings`).
+- Translate defaults to `new,stale`, writes `needs_review`, skips plurals, and supports `langcodec.toml` for translate-specific defaults.
 
 #### Plurals
 

langcodec-cli/Cargo.toml

@@ -18,8 +18,13 @@ clap_complete = "4"
 unicode-width = "0.2.1"
 crossterm = "0.29.0"
 atty = "0.2.14"
+async-trait = "0.1.89"
+mentra = "0.2.0"
+serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 serde_yaml = "0.9"
+tokio = { version = "1.50.0", features = ["rt-multi-thread", "sync"] }
+toml = "0.8"
 unic-langid = "0.9.6"
 glob = "0.3"
 rayon = "1.10"

langcodec-cli/README.md

@@ -1,9 +1,9 @@
 # langcodec-cli (Command Line)
 
-Universal CLI for converting, inspecting, merging, and editing localization files.
+Universal CLI for converting, inspecting, merging, editing, and translating localization files.
 
 - Formats: Apple `.strings`, `.xcstrings`, Android `strings.xml`, CSV, TSV
-- Commands: convert, diff, merge, sync, view, stats, debug, edit, normalize
+- Commands: convert, diff, merge, sync, view, stats, debug, edit, normalize, translate
 
 ## Install
 
@@ -87,6 +87,34 @@ langcodec stats -i Localizable.xcstrings --json
 
 Shows per-language totals, counts by status, and completion percent (excludes DoNotTranslate). Use `--json` for machine-readable output.
 
+### translate
+
+Translate singular source entries into a target language with a Mentra-backed provider.
+
+```sh
+langcodec translate \
+  --source source.xcstrings \
+  --target target.xcstrings \
+  --source-lang en \
+  --target-lang fr \
+  --provider openai \
+  --model gpt-4.1-mini
+```
+
+Behavior:
+
+- defaults to translating target entries with statuses `new,stale`
+- writes generated values as `needs_review`
+- skips plural entries in v1
+- writes in-place by default and supports `--dry-run`
+- supports translate defaults from `langcodec.toml`
+
+Provider/auth notes:
+
+- choose a Mentra provider with `--provider` (`openai|anthropic|gemini`) or `translate.provider` in config
+- set the matching API key in the environment (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `GEMINI_API_KEY`)
+- set the model with `--model`, `translate.model`, or `MENTRA_MODEL`
+
 ### debug
 
 ```sh

langcodec-cli/src/config.rs

@@ -0,0 +1,62 @@
+use serde::Deserialize;
+use std::path::PathBuf;
+
+#[derive(Debug, Clone, Default, Deserialize)]
+pub struct CliConfig {
+    #[serde(default)]
+    pub translate: TranslateConfig,
+}
+
+#[derive(Debug, Clone, Default, Deserialize)]
+pub struct TranslateConfig {
+    pub provider: Option<String>,
+    pub model: Option<String>,
+    pub source_lang: Option<String>,
+    pub target_lang: Option<String>,
+    pub concurrency: Option<usize>,
+    pub status: Option<Vec<String>>,
+}
+
+#[derive(Debug, Clone)]
+pub struct LoadedConfig {
+    pub path: PathBuf,
+    pub data: CliConfig,
+}
+
+pub fn load_config(explicit_path: Option<&str>) -> Result<Option<LoadedConfig>, String> {
+    let path = match explicit_path {
+        Some(path) => {
+            let resolved = PathBuf::from(path);
+            if !resolved.exists() {
+                return Err(format!("Config file does not exist: {}", resolved.display()));
+            }
+            resolved
+        }
+        None => match discover_config_path()? {
+            Some(path) => path,
+            None => return Ok(None),
+        },
+    };
+
+    let text = std::fs::read_to_string(&path)
+        .map_err(|e| format!("Failed to read config '{}': {}", path.display(), e))?;
+    let data: CliConfig = toml::from_str(&text)
+        .map_err(|e| format!("Failed to parse config '{}': {}", path.display(), e))?;
+    Ok(Some(LoadedConfig { path, data }))
+}
+
+fn discover_config_path() -> Result<Option<PathBuf>, String> {
+    let mut current = std::env::current_dir()
+        .map_err(|e| format!("Failed to determine current directory: {}", e))?;
+
+    loop {
+        let candidate = current.join("langcodec.toml");
+        if candidate.is_file() {
+            return Ok(Some(candidate));
+        }
+
+        if !current.pop() {
+            return Ok(None);
+        }
+    }
+}

langcodec-cli/src/lib.rs

@@ -1,10 +1,13 @@
 //! CLI library for testing purposes
 
+pub mod config;
 pub mod formats;
 pub mod merge;
+pub mod translate;
 pub mod transformers;
 pub mod validation;
 
 pub use formats::{CustomFormat, parse_custom_format};
 pub use langcodec::Codec;
+pub use translate::{TranslateOptions, run_translate_command};
 pub use transformers::custom_format_to_resource;

langcodec-cli/src/main.rs

@@ -1,3 +1,4 @@
+mod config;
 mod convert;
 mod debug;
 mod diff;
@@ -8,6 +9,7 @@ mod normalize;
 mod path_glob;
 mod stats;
 mod sync;
+mod translate;
 mod transformers;
 mod validation;
 mod view;
@@ -19,6 +21,7 @@ use crate::edit::{EditSetOptions, run_edit_set_command};
 use crate::merge::{ConflictStrategy, run_merge_command};
 use crate::normalize::{NormalizeCliOptions, run_normalize_command};
 use crate::sync::{SyncOptions, run_sync_command};
+use crate::translate::{TranslateOptions, run_translate_command};
 use crate::validation::{ValidationContext, validate_context, validate_language_code};
 use crate::view::{ViewOptions, print_view, validate_status_filter};
 use clap::{CommandFactory, Parser, Subcommand};
@@ -254,6 +257,53 @@ enum Commands {
         json: bool,
     },
 
+    /// Translate source entries into a target language using Mentra-backed providers.
+    Translate {
+        /// Source localization file
+        #[arg(short = 's', long)]
+        source: String,
+
+        /// Optional target localization file. If omitted, translates in-place within multi-language files.
+        #[arg(short = 't', long)]
+        target: Option<String>,
+
+        /// Optional output file. Defaults to in-place write to target or source.
+        #[arg(short, long)]
+        output: Option<String>,
+
+        /// Source language code. Required when the source file contains multiple languages.
+        #[arg(long)]
+        source_lang: Option<String>,
+
+        /// Target language code.
+        #[arg(long)]
+        target_lang: Option<String>,
+
+        /// Filter target entries by status before translating (default: new,stale)
+        #[arg(long)]
+        status: Option<String>,
+
+        /// Mentra provider to use: openai, anthropic, gemini
+        #[arg(long)]
+        provider: Option<String>,
+
+        /// Model identifier to use with Mentra
+        #[arg(long)]
+        model: Option<String>,
+
+        /// Number of concurrent translation workers
+        #[arg(long)]
+        concurrency: Option<usize>,
+
+        /// Optional langcodec.toml path
+        #[arg(long)]
+        config: Option<String>,
+
+        /// Preview the translation run without writing files
+        #[arg(long, default_value_t = false)]
+        dry_run: bool,
+    },
+
     /// Debug: Read a localization file and output as JSON.
     Debug {
         /// The input file to debug
@@ -647,6 +697,62 @@ fn main() {
                 strict,
             );
         }
+        Commands::Translate {
+            source,
+            target,
+            output,
+            source_lang,
+            target_lang,
+            status,
+            provider,
+            model,
+            concurrency,
+            config,
+            dry_run,
+        } => {
+            let mut context = ValidationContext::new().with_input_file(source.clone());
+            if let Some(target_path) = &target
+                && std::path::Path::new(target_path).exists()
+            {
+                context = context.with_input_file(target_path.clone());
+            }
+            if let Some(output_path) = &output {
+                context = context.with_output_file(output_path.clone());
+            } else if let Some(target_path) = &target {
+                context = context.with_output_file(target_path.clone());
+            }
+            if let Some(lang_code) = &source_lang {
+                context = context.with_language_code(lang_code.clone());
+            }
+            if let Err(e) = validate_context(&context) {
+                eprintln!("❌ Validation failed: {}", e);
+                std::process::exit(1);
+            }
+            if let Some(lang_code) = &target_lang
+                && let Err(e) = validate_language_code(lang_code)
+            {
+                eprintln!("❌ Validation failed: {}", e);
+                std::process::exit(1);
+            }
+
+            if let Err(e) = run_translate_command(TranslateOptions {
+                source,
+                target,
+                output,
+                source_lang,
+                target_lang,
+                status,
+                provider,
+                model,
+                concurrency,
+                config,
+                dry_run,
+                strict,
+            }) {
+                eprintln!("❌ Translate failed: {}", e);
+                std::process::exit(1);
+            }
+        }
         Commands::Debug {
             input,
             lang,