locai 2.6.1 → 2.7.0

package/README.md

@@ -1,54 +1,53 @@
 # Locai
 
-**The Universal AI Localization Engine.**
+[![CI](https://github.com/ahmetenesdur/locai/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ahmetenesdur/locai/actions/workflows/ci.yml)
 
-Locai brings human-quality AI localization to **any project** (Next.js, Flutter, Android, iOS, Python) and **any file format** with a single command. It fits right into your workflow, whether you're a solo dev or an enterprise team.
+**AI translation for JSON locale files.**
+
+Locai translates the JSON locale files of your project (`en.json` or `en/translation.json`) with an AI provider of your choice, from a single command. It works with any project that keeps its translations in JSON, for example Next.js, React or Vue apps using i18next.
 
 ## 🚀 Quick Start
 
-Translate your project in seconds without installing anything:
+Run it with `npx`, without installing anything:
 
 ```bash
 # Translates your ./locales from English to Turkish, Spanish, and German
 npx locai translate --source en --targets tr,es,de
 ```
 
-> **Need a permanent setup?** Check out our [Configuration Guide](./docs/configuration.md) to create a `localize.config.js` file.
+> **Need a permanent setup?** See the [Configuration Guide](./docs/configuration.md) to create a `localize.config.ts` file.
 
 ## 📖 Documentation
 
-Everything you need to know to master Locai.
-
 ### [Getting Started](./docs/getting-started.md)
 
 Introduction, installation options, and setting up your API keys.
 
 ### [Configuration Guide](./docs/configuration.md)
 
-Detailed guide on `localize.config.ts`, supported file formats (`json`, `yaml`, `po`, `arb`), and advanced settings.
+Detailed guide on `localize.config.ts`, the supported locale file layouts, and advanced settings.
 
 ### [CLI Reference](./docs/cli-reference.md)
 
-Master the command line. Learn about `translate`, `fix`, `review`, and `analyze`.
+Learn about `translate`, `fix`, `review`, and `validate-config`.
 
 ### [Providers](./docs/providers.md)
 
-Choose the right brain for your localization. Compare OpenAI, Gemini, DeepSeek, and more.
+Supported providers (OpenAI, Anthropic, Gemini, DeepSeek, Dashscope, XAI), their default models, API keys, rate limits and fallback.
 
 ### [Core Concepts](./docs/concepts.md)
 
-Deep dive into Locai's intelligent features. We didn't just wrap an API; we built a localization engine.
+How Locai's features work:
 
-- **Smart Context Awareness**: Uses AI to understand the context of your strings for better translations.
-- **Deep Context Analysis**: Scans your source code (AST) to extract component names, comments, and props for context-aware translations.
-- **Infinite Memory**: Uses vector embeddings to remember previous translations and maintain consistency. If you translate the same (or similar) sentence again, we fetch it from local cache instantly. Zero cost, 100% consistency.
-- **Smart Sync**: We hash every key. Locai only translates **new** or **modified** keys. If you have 1000 keys and change 5, we only send 5 to the AI.
-- **Context Awareness**: Locai analyzes your content. It knows if a string is for a **Button** (keep it short), **Marketing** (make it punchy), or **Legal** (be precise).
-- **Glossary & Brand Safety**: Define immutable terms (like "Locai", "API", "SaaS"). We guarantee they are never translated or corrupted.
-- **Auto-Fix Engine**: Did the AI forget a closing quote? Or mess up a `{placeholder}`? Locai detects these syntax errors and fixes them automatically before saving.
-- **Multi-Provider Fallback**: OpenAI down? Rate limit hit? Locai automatically switches to Gemini, DeepSeek, or other configured providers without breaking the build.
-- **Confidence Scoring**: Every translation gets a score (0-1). Low confidence translations are flagged for your review.
-- **Interactive Review**: A built-in Terminal UI (TUI) to manually approve or edit translations that need attention.
+- **Context Categories**: You define categories (keywords plus a prompt) in `context.categories`. When a string contains enough of a category's keywords, that category's prompt is added to the translation request. There are no built-in categories. AI classification of longer strings is optional (`context.useAI`, off by default).
+- **Deep Context Analysis**: Finds where each key is used in your TypeScript/TSX code (`t("key")` calls) and sends that usage with the translation request: file and line, component name, nearby comments, JSX props and a short code snippet. Turn it off with `deepContext: false` or `--no-deep-context`.
+- **Vector Memory (optional)**: With `vectorMemory.enabled: true`, Locai stores OpenAI embeddings of translated strings in a local database. Near-identical strings (similarity ≥ 0.98) reuse the stored translation without a translation call; similar ones (≥ 0.85) are given to the model as a reference. Requires `OPENAI_API_KEY`, and each new string costs an embedding request.
+- **Smart Sync**: Locai stores a hash of each source string. A key is translated when it is missing from a target file or its source text changed since the last run. If you have 1000 translated keys and change 5, only those 5 are sent to the AI. Keys removed from the source file are removed from the target files.
+- **Glossary & Brand Safety**: Define protected terms (like "Locai", "API", "SaaS"). Locai swaps them for placeholder tokens in the text being translated, then restores your configured translation, so the model does not see or translate those terms in that text. (Source code sent by Deep Context Analysis is not tokenized.)
+- **Auto-Fix**: After each translation, rule-based checks repair what they can: unbalanced quotes, missing or damaged placeholders (`{name}`, `${name}`, `%s`, `%d`), HTML tags and ending punctuation, plus markdown, code blocks and special characters if you turn those rules on. The checks do not reject a translation.
+- **Provider Fallback**: With `useFallback` (on by default), a failed request is retried with the other providers that have an API key set.
+- **Confidence Scoring** (opt-in): Each new translation gets a score (0-1) computed from checks on the translation itself: lost placeholders or HTML tags, untranslated text, leftover model commentary, unusual length or punctuation. Low scores are flagged for review; very low ones are not written to the locale file.
+- **Interactive Review**: `locai review` steps through the saved review queue in the terminal so you can approve or edit flagged translations; the ones you approve or edit are written to the locale file.
 
 ### [Development Guide](./docs/development.md)
 
@@ -56,11 +55,10 @@ Contributing to Locai? Learn how to build, test, and run the project locally.
 
 ## ✨ Why Locai?
 
-- **Framework Agnostic**: Works with Next.js, Flutter, Django, and more.
-- **Context Aware**: Knows the difference between "Home" (House) and "Home" (Page).
-- **Cost Efficient**: Smart caching and incremental updates save ~90% of AI costs.
-- **Flexible Structure**: Supports both flat (`en.json`) and nested (`en/translation.json`) directory structures automatically.
-- **Developer Friendly**: TypeScript config, type safety, and great error messages.
+- **JSON Locale Files**: Works with any project that stores translations as JSON (`<lang>.json` or `<lang>/translation.json`).
+- **Fewer API Calls**: Only new, changed or missing keys are sent to the AI. Strings already translated in the current run, or found in vector memory when it is enabled, are reused instead of triggering another translation call.
+- **Flat or Nested Layout**: Supports flat (`en.json`) and nested (`en/translation.json`) layouts. Target files are written in the same layout as the source file. The nested layout requires the file name `translation.json`.
+- **TypeScript Config**: `localize.config.ts` with types via `defineConfig` from `locai/config`.
 
 ## 🤝 Community & Contributing
 

package/dist/cli/helpers.d.ts

@@ -1,2 +1,34 @@
-export declare const autoDetectConfig: (defaultConfig: any) => Promise<any>;
-export declare const runCommand: (defaultConfig: any, commandOptions: any, commandName: string) => Promise<void>;
+import { LocalizeConfig, ResolvedLocalizeConfig } from "../config/index.js";
+import type { ReviewCommandConfig } from "../commands/review.js";
+/**
+ * Settings for `locai review`: the global `--source` / `--localesDir` flags (whose
+ * defaults are the config values) decide where approved translations are written.
+ */
+export declare const resolveReviewConfig: (defaultConfig: LocalizeConfig) => ReviewCommandConfig;
+/**
+ * Options commander parses for the commands handled by runCommand.
+ * Each command sets only its own subset (see the option definitions in src/cli.ts).
+ */
+export interface CommandOptions {
+    provider?: string;
+    concurrency?: number;
+    /** `--no-cache` sets `cache: false`. */
+    cache?: boolean;
+    force?: boolean;
+    /** `fix --length` is a boolean flag ("fix length issues"); a string is a length mode. */
+    length?: string | boolean;
+    autoOptimize?: boolean;
+    stats?: boolean;
+    minConfidence?: number;
+    saveReviewQueue?: boolean;
+    useAi?: boolean;
+    contextProvider?: string;
+    contextThreshold?: number;
+    contextConfidence?: number;
+    contextDebug?: boolean;
+    minTextLength?: number;
+    allowNewCategories?: boolean;
+    maxRetries?: number;
+}
+export declare const autoDetectConfig: <T extends LocalizeConfig>(defaultConfig: T) => Promise<T>;
+export declare const runCommand: (defaultConfig: ResolvedLocalizeConfig, commandOptions: CommandOptions, commandName: string) => Promise<void>;

package/dist/cli/helpers.js

@@ -4,9 +4,26 @@ import { program } from "commander";
 import { findLocaleFiles, translateFile, validateAndFixExistingTranslations, } from "../commands/translator.js";
 import InputValidator from "../utils/input-validator.js";
 import ErrorHelper from "../utils/error-helper.js";
+import { NoProviderError } from "../core/provider-factory.js";
+import { runFailures } from "../utils/statistics-manager.js";
 import { FrameworkDetector } from "../core/detection/framework-detector.js";
 import { StructureDetector, LocaleStructure } from "../core/detection/structure-detector.js";
 import { configureComponents } from "../config/setup.js";
+/**
+ * Settings for `locai review`: the global `--source` / `--localesDir` flags (whose
+ * defaults are the config values) decide where approved translations are written.
+ */
+export const resolveReviewConfig = (defaultConfig) => {
+    const globalOpts = program.opts();
+    const source = globalOpts.source ?? defaultConfig.source;
+    const localesDir = globalOpts.localesDir ?? defaultConfig.localesDir;
+    return {
+        source: source ? InputValidator.validateLanguageCode(source, "source language") : "en",
+        localesDir: localesDir
+            ? InputValidator.validateDirectoryPath(localesDir, "locales directory")
+            : "./locales",
+    };
+};
 export const autoDetectConfig = async (defaultConfig) => {
     // Auto-detect framework and configuration if not explicitly set
     const detected = await FrameworkDetector.detect(process.cwd());
@@ -60,8 +77,8 @@ export const runCommand = async (defaultConfig, commandOptions, commandName) =>
         if (globalOpts.debug) {
             const safeGlobalOpts = { ...globalOpts };
             const safeCommandOptions = { ...commandOptions };
-            if (safeGlobalOpts.targets) {
-                safeGlobalOpts.targets = `[${safeGlobalOpts.targets.length} languages]`;
+            if (globalOpts.targets) {
+                safeGlobalOpts.targets = `[${globalOpts.targets.length} languages]`;
             }
             if (safeGlobalOpts.localesDir) {
                 safeGlobalOpts.localesDir = "[directory_path]";
@@ -88,30 +105,49 @@ export const runCommand = async (defaultConfig, commandOptions, commandName) =>
             sanitizedCommandOptions.provider = InputValidator.validateProvider(sanitizedCommandOptions.provider, "API provider");
         }
         if (sanitizedCommandOptions.concurrency !== undefined) {
-            const concurrency = parseInt(sanitizedCommandOptions.concurrency);
+            const concurrency = parseInt(String(sanitizedCommandOptions.concurrency));
             if (isNaN(concurrency) || concurrency < 1 || concurrency > 20) {
                 throw new Error("Concurrency must be a number between 1 and 20");
             }
             sanitizedCommandOptions.concurrency = concurrency;
         }
         if (sanitizedCommandOptions.contextThreshold !== undefined) {
-            const threshold = parseInt(sanitizedCommandOptions.contextThreshold);
+            const threshold = parseInt(String(sanitizedCommandOptions.contextThreshold));
             if (isNaN(threshold) || threshold < 1 || threshold > 10) {
                 throw new Error("Context threshold must be a number between 1 and 10");
             }
             sanitizedCommandOptions.contextThreshold = threshold;
         }
         if (sanitizedCommandOptions.contextConfidence !== undefined) {
-            const confidence = parseFloat(sanitizedCommandOptions.contextConfidence);
+            const confidence = parseFloat(String(sanitizedCommandOptions.contextConfidence));
             if (isNaN(confidence) || confidence < 0 || confidence > 1) {
                 throw new Error("Context confidence must be a number between 0 and 1");
             }
             sanitizedCommandOptions.contextConfidence = confidence;
         }
-        if (sanitizedCommandOptions.length) {
-            const validLengthModes = ["strict", "flexible", "exact", "relaxed", "smart"];
-            if (!validLengthModes.includes(sanitizedCommandOptions.length)) {
-                throw new Error(`Invalid length mode: ${sanitizedCommandOptions.length}. Valid modes: ${validLengthModes.join(", ")}`);
+        if (sanitizedCommandOptions.minConfidence !== undefined) {
+            const minConfidence = parseFloat(String(sanitizedCommandOptions.minConfidence));
+            if (isNaN(minConfidence) || minConfidence < 0 || minConfidence > 1) {
+                console.warn(`Warning: ignoring --min-confidence ${sanitizedCommandOptions.minConfidence}: it must be a number between 0 and 1`);
+                sanitizedCommandOptions.minConfidence = undefined;
+            }
+            else {
+                sanitizedCommandOptions.minConfidence = minConfidence;
+            }
+        }
+        let lengthMode;
+        if (typeof sanitizedCommandOptions.length === "string") {
+            const validLengthModes = [
+                "strict",
+                "flexible",
+                "exact",
+                "relaxed",
+                "smart",
+            ];
+            const requested = sanitizedCommandOptions.length;
+            lengthMode = validLengthModes.find((mode) => mode === requested);
+            if (!lengthMode) {
+                throw new Error(`Invalid length mode: ${requested}. Valid modes: ${validLengthModes.join(", ")}`);
             }
         }
         const mergedOpts = {
@@ -126,7 +162,7 @@ export const runCommand = async (defaultConfig, commandOptions, commandName) =>
             }),
             ...sanitizedCommandOptions,
         };
-        let concurrencyLimit = parseInt(mergedOpts.concurrency) || defaultConfig.concurrencyLimit || 5;
+        let concurrencyLimit = parseInt(String(mergedOpts.concurrency)) || defaultConfig.concurrencyLimit || 5;
         if (mergedOpts.autoOptimize) {
             const cpuCount = os.cpus().length;
             const memoryGB = Math.floor(os.totalmem() / (1024 * 1024 * 1024));
@@ -153,10 +189,15 @@ export const runCommand = async (defaultConfig, commandOptions, commandName) =>
             localesDir: mergedOpts.localesDir,
             apiProvider: mergedOpts.provider || defaultConfig.apiProvider,
             concurrencyLimit: concurrencyLimit,
-            cacheEnabled: mergedOpts.noCache === undefined ? defaultConfig.cacheEnabled : !mergedOpts.noCache,
-            debug: mergedOpts.debug,
-            verbose: mergedOpts.verbose || defaultConfig.logging?.verbose || false,
-            forceUpdate: mergedOpts.force || false,
+            // commander turns `--no-cache` into `cache: false`
+            cacheEnabled: mergedOpts.cache === false ? false : defaultConfig.cacheEnabled,
+            // `--no-deep-context` sets `deepContext: false`; commander defaults it to true
+            deepContext: sanitizedGlobalOpts.deepContext === false ? false : defaultConfig.deepContext,
+            debug: sanitizedGlobalOpts.debug || defaultConfig.debug || false,
+            verbose: sanitizedGlobalOpts.verbose || defaultConfig.logging?.verbose || false,
+            forceUpdate: mergedOpts.force || defaultConfig.forceUpdate || false,
+            minConfidence: mergedOpts.minConfidence ?? defaultConfig.minConfidence,
+            saveReviewQueue: mergedOpts.saveReviewQueue || defaultConfig.saveReviewQueue,
             showDetailedStats: mergedOpts.stats || false,
             autoOptimize: mergedOpts.autoOptimize || defaultConfig.advanced?.autoOptimize || false,
             fixLength: commandName === "fix",
@@ -165,18 +206,18 @@ export const runCommand = async (defaultConfig, commandOptions, commandName) =>
             qualityChecks: defaultConfig.qualityChecks,
             lengthControl: {
                 ...defaultConfig.lengthControl,
-                mode: mergedOpts.length || defaultConfig.lengthControl?.mode || "smart",
+                mode: lengthMode || defaultConfig.lengthControl?.mode || "smart",
             },
             retryOptions: {
                 ...defaultConfig.retryOptions,
                 maxRetries: mergedOpts.maxRetries || defaultConfig.retryOptions?.maxRetries || 2,
-                initialDelay: mergedOpts.initialDelay || defaultConfig.retryOptions?.initialDelay || 1000,
-                maxDelay: mergedOpts.maxDelay || defaultConfig.retryOptions?.maxDelay || 10000,
+                initialDelay: defaultConfig.retryOptions?.initialDelay || 1000,
+                maxDelay: defaultConfig.retryOptions?.maxDelay || 10000,
                 jitter: defaultConfig.retryOptions?.jitter !== false,
             },
             context: {
                 ...defaultConfig.context,
-                enabled: true,
+                enabled: defaultConfig.context.enabled !== false,
                 debug: mergedOpts.contextDebug || defaultConfig.context.debug || false,
                 useAI: mergedOpts.useAi ||
                     mergedOpts.contextProvider !== undefined ||
@@ -198,11 +239,11 @@ export const runCommand = async (defaultConfig, commandOptions, commandName) =>
             },
             advanced: {
                 ...defaultConfig.advanced,
-                timeoutMs: mergedOpts.timeout || defaultConfig.advanced?.timeoutMs || 60000,
+                timeoutMs: defaultConfig.advanced?.timeoutMs || 60000,
                 maxKeyLength: defaultConfig.advanced?.maxKeyLength || 10000,
                 maxBatchSize: defaultConfig.advanced?.maxBatchSize || 50,
                 autoOptimize: mergedOpts.autoOptimize || defaultConfig.advanced?.autoOptimize || false,
-                debug: mergedOpts.debug || defaultConfig.advanced?.debug || false,
+                debug: sanitizedGlobalOpts.debug || defaultConfig.advanced?.debug || false,
             },
             rateLimiter: {
                 ...defaultConfig.rateLimiter,
@@ -211,7 +252,7 @@ export const runCommand = async (defaultConfig, commandOptions, commandName) =>
             fileOperations: defaultConfig.fileOperations || {},
             logging: {
                 ...defaultConfig.logging,
-                verbose: mergedOpts.verbose || defaultConfig.logging?.verbose || false,
+                verbose: sanitizedGlobalOpts.verbose || defaultConfig.logging?.verbose || false,
             },
         };
         try {
@@ -221,9 +262,8 @@ export const runCommand = async (defaultConfig, commandOptions, commandName) =>
             }
         }
         catch (configError) {
-            const error = ErrorHelper.configValidationError(configError.message.includes("validation failed")
-                ? configError.message.split("\n").slice(1)
-                : [configError.message]);
+            const message = configError instanceof Error ? configError.message : String(configError);
+            const error = ErrorHelper.configValidationError(message.includes("validation failed") ? message.split("\n").slice(1) : [message]);
             console.error(ErrorHelper.formatError(error, { showDebug: globalOpts.debug }));
             process.exit(1);
         }
@@ -277,10 +317,18 @@ export const runCommand = async (defaultConfig, commandOptions, commandName) =>
             process.exit(1);
         }
         switch (commandName) {
-            case "fix":
+            case "fix": {
                 console.log("\nRunning in FIX mode");
-                await Promise.all(files.map((file) => validateAndFixExistingTranslations(file, finalConfig)));
-                break;
+                const summaries = await Promise.all(files.map((file) => validateAndFixExistingTranslations(file, finalConfig)));
+                const unfixed = summaries.reduce((sum, s) => sum + (s.issues - s.fixed), 0);
+                if (unfixed > 0) {
+                    console.error(`\n${unfixed} length issue(s) could not be fixed`);
+                    process.exit(1);
+                    return;
+                }
+                process.exit(0);
+                return;
+            }
             case "analyze":
                 console.log("\nRunning in ANALYZE mode");
                 console.log("Context analysis mode is not fully implemented yet.");
@@ -289,7 +337,7 @@ export const runCommand = async (defaultConfig, commandOptions, commandName) =>
                 console.log("\nRunning ADVANCED configuration");
             // Fall through to translate
             case "translate":
-            default:
+            default: {
                 console.log("\nRunning in TRANSLATION mode");
                 const providerMap = {
                     openai: "OPENAI_API_KEY",
@@ -301,7 +349,7 @@ export const runCommand = async (defaultConfig, commandOptions, commandName) =>
                 };
                 const availableProviders = Object.keys(providerMap).filter((key) => process.env[providerMap[key]]);
                 console.log(`API Configuration:`);
-                console.log(`   - Active Provider: ${finalConfig.apiProvider}`);
+                console.log(`   - Active Provider: ${finalConfig.apiProvider || "first provider with an API key"}`);
                 console.log(`   - Available Providers: ${availableProviders.join(", ") || "None"}`);
                 if (finalConfig.context.useAI) {
                     console.log(`AI Context Analysis: ENABLED (Provider: ${finalConfig.context.aiProvider || finalConfig.apiProvider})`);
@@ -319,23 +367,34 @@ export const runCommand = async (defaultConfig, commandOptions, commandName) =>
                 if (finalConfig.forceUpdate) {
                     console.log(`Warning: Force update mode ENABLED (will update existing translations)`);
                 }
+                let failedTranslations = 0;
+                const failedLanguages = [];
                 for (const file of files) {
-                    await translateFile(file, finalConfig);
+                    const failures = runFailures(await translateFile(file, finalConfig));
+                    failedTranslations += failures.failedTranslations;
+                    failedLanguages.push(...failures.failedLanguages);
                 }
-                // Exit after successful translation in CLI mode
-                // This allows translateFile to be used as library without forcing exit
-                process.exit(0);
-                break;
+                // Exit here in CLI mode (translateFile can also be used as a library). A run in
+                // which anything failed exits non-zero, so CI does not pass a run that did not translate.
+                process.exit(failedTranslations > 0 || failedLanguages.length > 0 ? 1 : 0);
+                return;
+            }
         }
         // Other commands (fix, analyze) handle their own completion
     }
     catch (validationError) {
-        if (validationError.message.includes("Configuration validation")) {
+        const message = validationError instanceof Error ? validationError.message : String(validationError);
+        if (message.includes("Configuration validation")) {
             // Already handled above with better formatting
             return;
         }
-        console.error(`\nInput validation error: ${validationError.message}`);
-        if (validationError.stack && process.env.DEBUG) {
+        if (validationError instanceof NoProviderError) {
+            console.error(`\nError: ${message}`);
+            process.exit(1);
+            return;
+        }
+        console.error(`\nInput validation error: ${message}`);
+        if (validationError instanceof Error && validationError.stack && process.env.DEBUG) {
             console.error("\nStack trace:");
             console.error(validationError.stack);
         }

package/dist/cli.js

@@ -4,8 +4,13 @@ import { program } from "commander";
 import ErrorHelper from "./utils/error-helper.js";
 import { loadConfig, validateEnvironment } from "./config/index.js";
 import { loadEnvironmentVariables, configureComponents } from "./config/setup.js";
-import { autoDetectConfig, runCommand } from "./cli/helpers.js";
+import { autoDetectConfig, runCommand, resolveReviewConfig, } from "./cli/helpers.js";
 import InputValidator from "./utils/input-validator.js";
+/** Errors built by ErrorHelper carry an `ERR_*` code and get its formatted output. */
+const isHelperError = (error) => error instanceof Error &&
+    "code" in error &&
+    typeof error.code === "string" &&
+    error.code.startsWith("ERR_");
 // Use createRequire to load package.json in ESM context
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
@@ -13,15 +18,14 @@ const main = async () => {
     await loadEnvironmentVariables();
     // Load configuration
     const loaded = await loadConfig();
-    let defaultConfig = loaded.config || {};
+    let defaultConfig = loaded.config;
     defaultConfig = await autoDetectConfig(defaultConfig);
     configureComponents(defaultConfig);
     validateEnvironment(defaultConfig);
-    const toolVersion = defaultConfig.version || version;
     program
         .name("locai")
-        .description("AI-powered localization tool for Next.js projects")
-        .version(toolVersion);
+        .description("AI-powered localization tool for JSON locale files")
+        .version(version);
     program
         .option("-s, --source <lang>", "Source language", defaultConfig.source)
         .option("-t, --targets <langs>", "Target languages (comma separated)", (val) => val.split(","), defaultConfig.targets)
@@ -46,7 +50,7 @@ const main = async () => {
         .option("--force", "Force update of existing translations", false)
         .option("--length <mode>", "Length control mode", defaultConfig.lengthControl?.mode || "smart")
         .option("--auto-optimize", "Auto-optimize system parameters based on hardware", false)
-        .option("--stats", "Show detailed stats after completion", false)
+        .option("--stats", "No effect: the full summary is always shown", false)
         .option("--min-confidence <score>", "Minimum confidence threshold (0-1)", parseFloat)
         .option("--save-review-queue", "Save low-confidence items for manual review", false)
         .action(async (options) => {
@@ -54,7 +58,7 @@ const main = async () => {
             await runCommand(defaultConfig, options, "translate");
         }
         catch (error) {
-            if (error.code && error.code.startsWith("ERR_")) {
+            if (isHelperError(error)) {
                 console.error(ErrorHelper.formatError(error, {
                     showDebug: process.env.DEBUG === "true",
                     showSolutions: true,
@@ -62,8 +66,9 @@ const main = async () => {
                 }));
             }
             else {
-                console.error(`\nError: ${error.message}`);
-                if (error.stack && process.env.DEBUG) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(`\nError: ${message}`);
+                if (error instanceof Error && error.stack && process.env.DEBUG) {
                     console.error(error.stack);
                 }
             }
@@ -72,19 +77,20 @@ const main = async () => {
     });
     program
         .command("fix")
-        .description("Fix issues in existing translations")
-        .option("--length", "Fix length issues in existing translations", true)
+        .description("Re-translate existing translations that fail the length check")
+        .option("--length", "Fix length issues in existing translations (always on)", true)
         .action(async (options) => {
         try {
             await runCommand(defaultConfig, options, "fix");
         }
         catch (error) {
-            if (error.code && error.code.startsWith("ERR_")) {
+            if (isHelperError(error)) {
                 console.error(ErrorHelper.formatError(error, { showDebug: process.env.DEBUG === "true" }));
             }
             else {
-                console.error(`\nError: ${error.message}`);
-                if (error.stack && process.env.DEBUG) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(`\nError: ${message}`);
+                if (error instanceof Error && error.stack && process.env.DEBUG) {
                     console.error(error.stack);
                 }
             }
@@ -93,21 +99,22 @@ const main = async () => {
     });
     program
         .command("analyze")
-        .description("Analyze context patterns")
-        .option("--use-ai", "Enable AI-based context analysis", defaultConfig.context?.useAI)
-        .option("--context-provider <provider>", "AI provider for analysis", defaultConfig.context?.aiProvider)
-        .option("--context-threshold <number>", "Minimum match count", Number, defaultConfig.context?.detection?.threshold)
+        .description("Not implemented yet: only loads the config and finds the source files")
+        .option("--use-ai", "No effect yet (analyze is not implemented)", defaultConfig.context?.useAI)
+        .option("--context-provider <provider>", "No effect yet (analyze is not implemented)", defaultConfig.context?.aiProvider)
+        .option("--context-threshold <number>", "No effect yet (analyze is not implemented)", Number, defaultConfig.context?.detection?.threshold)
         .action(async (options) => {
         try {
             await runCommand(defaultConfig, options, "analyze");
         }
         catch (error) {
-            if (error.code && error.code.startsWith("ERR_")) {
+            if (isHelperError(error)) {
                 console.error(ErrorHelper.formatError(error, { showDebug: process.env.DEBUG === "true" }));
             }
             else {
-                console.error(`\nError: ${error.message}`);
-                if (error.stack && process.env.DEBUG) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(`\nError: ${message}`);
+                if (error instanceof Error && error.stack && process.env.DEBUG) {
                     console.error(error.stack);
                 }
             }
@@ -116,9 +123,9 @@ const main = async () => {
     });
     program
         .command("advanced")
-        .description("Access advanced configuration options")
+        .description("Translate (like `translate`) with advanced context and retry settings")
         .option("--context-confidence <number>", "Minimum confidence score", Number, defaultConfig.context?.detection?.minConfidence)
-        .option("--context-debug", "Show context details", defaultConfig.context?.debug)
+        .option("--context-debug", "No effect (not implemented)", defaultConfig.context?.debug)
         .option("--min-text-length <number>", "Minimum text length for AI analysis", Number, defaultConfig.context?.minTextLength)
         .option("--allow-new-categories", "Allow AI to suggest new categories", defaultConfig.context?.allowNewCategories)
         .option("--max-retries <number>", "Maximum number of retries for API calls", Number, defaultConfig.retryOptions?.maxRetries || 2)
@@ -127,12 +134,13 @@ const main = async () => {
             await runCommand(defaultConfig, options, "advanced");
         }
         catch (error) {
-            if (error.code && error.code.startsWith("ERR_")) {
+            if (isHelperError(error)) {
                 console.error(ErrorHelper.formatError(error, { showDebug: process.env.DEBUG === "true" }));
             }
             else {
-                console.error(`\nError: ${error.message}`);
-                if (error.stack && process.env.DEBUG) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(`\nError: ${message}`);
+                if (error instanceof Error && error.stack && process.env.DEBUG) {
                     console.error(error.stack);
                 }
             }
@@ -185,7 +193,7 @@ const main = async () => {
         }
         catch (error) {
             console.error("\nConfiguration Validation Failed:\n");
-            console.error(error.message);
+            console.error(error instanceof Error ? error.message : String(error));
             console.error("\nFix the errors above and try again\n");
             process.exit(1);
         }
@@ -197,15 +205,7 @@ const main = async () => {
         .action(async (options) => {
         try {
             const ReviewCommand = (await import("./commands/review.js")).default;
-            // Ensure config matches expectations of ReviewCommand
-            // ReviewCommand expects ConfigLayer/LocalizeConfig, need to ensure mandatory fields or cast
-            // ReviewCommandConfig requires localesDir and source to be strings (not undefined)
-            const reviewConfig = {
-                ...defaultConfig,
-                localesDir: defaultConfig.localesDir || "./locales",
-                source: defaultConfig.source || "en",
-            };
-            const review = new ReviewCommand(reviewConfig);
+            const review = new ReviewCommand(resolveReviewConfig(defaultConfig));
             if (options.export) {
                 review.exportReviewQueue(options.export);
             }
@@ -214,8 +214,9 @@ const main = async () => {
             }
         }
         catch (error) {
-            console.error(`\nError: ${error.message}`);
-            if (error.stack && process.env.DEBUG) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`\nError: ${message}`);
+            if (error instanceof Error && error.stack && process.env.DEBUG) {
                 console.error(error.stack);
             }
             process.exit(1);
@@ -226,7 +227,7 @@ const main = async () => {
             await runCommand(defaultConfig, {}, "translate");
         }
         catch (error) {
-            console.error(`\nError: ${error.message}`);
+            console.error(`\nError: ${error instanceof Error ? error.message : String(error)}`);
             process.exit(1);
         }
     });