i18ntk 4.5.3 → 4.5.4

package/CHANGELOG.md

@@ -3,11 +3,37 @@
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [4.5.3] - 2026-06-19
-
-### Fixed
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [4.5.4] - 2026-06-19
+
+### Fixed
+
+- **Analyze:** Fixed `this.provideSetupGuidance is not a function` when no target locales are available. Analyze now prints setup guidance instead of crashing.
+- **Manager Route:** Manager-routed commands now propagate subcommand failures and no longer print `Operation completed successfully!` after a runtime failure.
+- **Complete:** Fixed `i18ntk-complete --help` by wiring the shared help renderer and keeping help output side-effect free.
+- **Validate:** Removed mixed failure/success output. Validation only prints successful completion when the validation result succeeds.
+- **Summary:** Guarded empty locale roots so `Average keys per language` prints `0` instead of `NaN`, and missing locale roots exit as invalid setup/argument failures.
+- **Analyze Reports:** Report write failures now fail analyze with a non-zero exit code instead of continuing with success wording.
+
+### Changed
+
+- **CLI Flags:** Added canonical aliases: `--code-dir` / `--source-code-dir` for application source files, `--locales-dir` / `--i18n-dir` for locale files, and `--source-locale` for source language. Legacy `--source-dir`, `--i18n-dir`, and `--source-language` remain supported.
+- **Exit Codes:** Standardized automation behavior: `0` for success, `1` for validation/report/runtime failures, and `2` for invalid arguments or missing setup in non-interactive mode.
+- **CI Behavior:** Commands skip prompts when `--no-prompt` is passed, `CI=true`, stdin is not a TTY, or stdout is not a TTY.
+- **Complete Summary:** Completion output now distinguishes locales scanned, target locales changed, unique source keys added, total key insertions, files modified, files skipped, and dry-run status.
+
+### Documentation
+
+- Updated README, API, configuration, scanner, and environment-variable docs with canonical CLI flags, legacy alias notes, and CI exit-code behavior.
+
+### Tests
+
+- Added CLI reliability regression coverage for the analyze crash, manager failure propagation, complete help output, directory/source-locale aliases, summary `NaN`, non-interactive prompt suppression, validation wording, and completion summary labels.
+
+## [4.5.3] - 2026-06-19
+
+### Fixed
 
 - **Usage Scanner (Critical):** Fixed `supportedExtensions` default fallback in `config-helper.js` that excluded `.tsx` and `.jsx` files from source scanning. The default was `['.json', '.js', '.ts']` — missing `.jsx` and `.tsx`. In a Next.js project with 2704 keys across 1087 files, this caused the scanner to find only 57 keys (2.1%) instead of 2702 (99.9%) because all `.tsx` component files were silently ignored. The fix adds `.jsx` and `.tsx` to the default fallback: `['.json', '.js', '.jsx', '.ts', '.tsx']`.
 - **Usage Dead Code:** Cleaned up unreachable initializer in `i18ntk-usage.js` that was supposed to set default `includeExtensions` but never ran because `supportedExtensions` was always set by `config-helper.js`. Added `.vue` and `.svelte` to the fallback for completeness.

package/README.md

@@ -1,4 +1,4 @@
-# i18ntk v4.5.3
+# i18ntk v4.5.4
 
 A zero-dependency internationalization toolkit for setup, scanning, analysis, validation, usage tracking, translation completion, automatic JSON locale translation, reporting, and runtime translation loading.
 
@@ -9,7 +9,7 @@ A zero-dependency internationalization toolkit for setup, scanning, analysis, va
 [![node](https://img.shields.io/badge/node-%3E%3D16-339933)](https://nodejs.org)
 [![dependencies](https://img.shields.io/badge/dependencies-0-success)](https://www.npmjs.com/package/i18ntk)
 [![license](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
-[![socket](https://socket.dev/api/badge/npm/package/i18ntk/4.5.3)](https://socket.dev/npm/package/i18ntk/overview/4.5.3)
+[![socket](https://socket.dev/api/badge/npm/package/i18ntk/4.5.4)](https://socket.dev/npm/package/i18ntk/overview/4.5.4)
 
 [![i18ntk Workbench](https://img.shields.io/badge/VS_Code-i18ntk_Workbench-007ACC?logo=visualstudiocode&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=VladNoskov.i18ntk-workbench)
 [![i18ntk Lens](https://img.shields.io/badge/VS_Code-i18ntk_Lens-007ACC?logo=visualstudiocode&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=VladNoskov.i18ntk-lens)
@@ -64,6 +64,13 @@ i18next is mainly a runtime internationalization library. i18ntk is mainly workf
 | Validation reports        | Yes           | Limited          |
 | Auto-translation workflow | Yes           | External tooling |
 
+## What's New in 4.5.4
+
+- **CLI RELIABILITY**: Direct and manager-routed commands now propagate runtime, validation, and report failures with non-zero exit codes and never print success after failure.
+- **CI READY**: Commands skip prompts under `--no-prompt`, `CI=true`, or non-TTY stdin/stdout.
+- **CLEAR FLAGS**: Added `--code-dir` / `--source-code-dir`, `--locales-dir` / `--i18n-dir`, and `--source-locale` while preserving legacy aliases.
+- **COMMAND FIXES**: Fixed `i18ntk-analyze` setup guidance crash, `i18ntk-complete --help`, `i18ntk-summary` `NaN` averages, validation success/failure wording, and completion summary labels.
+
 ## What's New in 4.5.3
 
 - **TSX/JSX SCANNING**: `supportedExtensions` default now includes `.tsx` and `.jsx`. Previously excluded from source scanning, causing React/Next.js projects to miss 97%+ of translation keys.
@@ -193,20 +200,22 @@ Note: manager route `i18ntk --command=backup` is available via the interactive m
 
 Many commands support:
 
-- `--source-dir <path>`
-- `--i18n-dir <path>`
+- `--code-dir <path>` or `--source-code-dir <path>` for application source files
+- `--locales-dir <path>` or `--i18n-dir <path>` for locale files
 - `--output-dir <path>`
-- `--source-language <code>`
+- `--source-locale <code>`
 - `--ui-language <code>`
 - `--no-prompt`
 - `--help`
 
+Legacy `--source-dir` and `--source-language` remain supported. For scanner-style commands, `--source-dir` means source code. For locale-only commands, prefer `--locales-dir` to avoid ambiguity.
+
 Command-specific tools add their own flags such as `--dry-run`, `--output-report`, `--cleanup`, `--predict-expansion`, or Auto Translate provider options.
 
 Example:
 
 ```bash
-i18ntk --command=analyze --source-dir=./src --i18n-dir=./locales --output-dir=./i18ntk-reports
+i18ntk --command=analyze --code-dir=./src --locales-dir=./locales --source-locale=en --output-dir=./i18ntk-reports
 ```
 
 ## Auto Translate
@@ -358,8 +367,8 @@ Tune warnings in `.i18ntk-config`:
 `i18ntk-sizing` reports translation file sizes, key counts, average value length, and file-set mismatches across language folders.
 
 ```bash
-i18ntk-sizing --source-dir ./locales --format table
-i18ntk-sizing --source-dir ./locales --detailed --output-dir ./i18ntk-reports
+i18ntk-sizing --locales-dir ./locales --format table
+i18ntk-sizing --locales-dir ./locales --detailed --output-dir ./i18ntk-reports
 ```
 
 Use `--detailed` to print per-file rows in the terminal.
@@ -369,7 +378,7 @@ Use `--detailed` to print per-file rows in the terminal.
 Predict UI layout overflow risk by analyzing per-key character-count expansion across languages:
 
 ```bash
-i18ntk-sizing --source-dir ./locales --predict-expansion --output-report
+i18ntk-sizing --locales-dir ./locales --predict-expansion --output-report
 ```
 
 Expansion ratios are classified into risk tiers:
@@ -385,8 +394,8 @@ The report includes a built-in language-pair expansion reference table (EN→DE
 `i18ntk-scanner` now supports detecting hardcoded text in multiple source languages beyond English:
 
 ```bash
-i18ntk-scanner --source-dir ./src --source-language de
-i18ntk-scanner --source-dir ./src --source-language ja --output-report
+i18ntk-scanner --code-dir ./src --source-locale de
+i18ntk-scanner --code-dir ./src --source-locale ja --output-report
 ```
 
 Supported language profiles (12+): English, German, French, Spanish, Japanese, Chinese, Russian, Korean, Arabic, Hindi, and more. Each profile includes language-specific character ranges, stopword lists for false-positive filtering, and transliteration rules for key generation.
@@ -396,8 +405,8 @@ Supported language profiles (12+): English, German, French, Spanish, Japanese, C
 `i18ntk-usage` can identify translation keys that are defined but never referenced in source code:
 
 ```bash
-i18ntk-usage --source-dir ./src --i18n-dir ./locales --cleanup
-i18ntk-usage --source-dir ./src --i18n-dir ./locales --cleanup --dry-run-delete
+i18ntk-usage --code-dir ./src --locales-dir ./locales --cleanup
+i18ntk-usage --code-dir ./src --locales-dir ./locales --cleanup --dry-run-delete
 ```
 
 Each dead key receives a confidence score (0.0–1.0) factoring:
@@ -546,7 +555,7 @@ Example:
 
 ```json
 {
-  "version": "4.5.3",
+  "version": "4.5.4",
   "sourceDir": "./locales",
   "i18nDir": "./locales",
   "outputDir": "./i18ntk-reports",

package/main/i18ntk-analyze.js

@@ -71,9 +71,16 @@ class I18nAnalyzer {
       const uiLanguage = (this.config && this.config.uiLanguage) || 'en';
       loadTranslations(uiLanguage, path.resolve(__dirname, '..', 'ui-locales'));
       
-      this.sourceDir = this.config.sourceDir;
-      this.sourceLanguageDir = path.join(this.sourceDir, this.config.sourceLanguage);
-      this.outputDir = this.config.outputDir;
+      this.sourceDir = this.config.localesDir || this.config.i18nDir || this.config.sourceDir;
+      this.sourceLanguageDir = path.join(this.sourceDir, this.config.sourceLanguage);
+      this.outputDir = this.config.outputDir;
+
+      const explicitLocaleDir = args.i18nDir || (!args.i18nDir && args.sourceDir ? args.sourceDir : null);
+      if (explicitLocaleDir && !SecurityUtils.safeExistsSync(this.sourceDir, process.cwd())) {
+        const err = new Error(`Locale directory not found: ${this.sourceDir}`);
+        err.exitCode = 2;
+        throw err;
+      }
       
       // Validate source directory exists
       const { validateSourceDir } = require('../utils/config-helper');
@@ -710,10 +717,32 @@ try {
     }
   }
 
-  // Show help message
-  showHelp() {
-    console.log(t('analyze.help_message'));
-  }
+  // Show help message
+  showHelp() {
+    console.log(t('analyze.help_message'));
+  }
+
+  provideSetupGuidance() {
+    return [
+      'Setup guidance:',
+      `- Ensure the locale root exists: ${this.sourceDir}`,
+      `- Ensure the source locale exists: ${path.join(this.sourceDir, this.config.sourceLanguage)}`,
+      '- Add at least one target locale, for example de/common.json or de.json.',
+      '- Prefer --locales-dir for locale files. Use --code-dir for application source files.'
+    ].join('\n');
+  }
+
+  detectStructureType() {
+    const sourceLocaleDir = path.join(this.sourceDir, this.config.sourceLanguage);
+    const sourceLocaleFile = path.join(this.sourceDir, `${this.config.sourceLanguage}.json`);
+    if (SecurityUtils.safeExistsSync(sourceLocaleFile, this.sourceDir)) {
+      return { type: 'monolith' };
+    }
+    if (SecurityUtils.safeExistsSync(sourceLocaleDir, this.sourceDir)) {
+      return { type: 'directory' };
+    }
+    return { type: 'unknown' };
+  }
 
   // Main analyze method
   async analyze() {
@@ -737,9 +766,9 @@ try {
       
       const languages = this.getAvailableLanguages();
       
-      if (languages.length === 0) {
-        const error = t('analyze.noLanguages') || '⚠️  No target languages found.';
-        const guidance = this.provideSetupGuidance();
+      if (languages.length === 0) {
+        const error = t('analyze.noLanguages') || '⚠️  No target languages found.';
+        const guidance = this.provideSetupGuidance();
         
         if (args.json) {
           jsonOutput.setStatus('error', error);
@@ -751,10 +780,10 @@ try {
           console.log(JSON.stringify(jsonOutput.data, null, args.indent || 2));
           return;
         }
-        console.log(error);
-        console.log('\n' + guidance);
-        return;
-      }
+        console.log(error);
+        console.log('\n' + guidance);
+        return { success: true, warnings: 1, message: error };
+      }
       
       if (!args.json) {
         console.log(t('analyze.foundLanguages', { count: languages.length, languages: languages.join(', ') }) || `📋 Found ${languages.length} languages to analyze: ${languages.join(', ')}`);
@@ -773,8 +802,11 @@ try {
           const report = this.generateLanguageReport(analysis);
 
           // Save report
-          const reportPath = await this.saveReport(language, report);
-          const processedCount = results.length + 1;
+          const reportPath = await this.saveReport(language, report);
+          if (!reportPath) {
+            throw new Error(`Failed to save analysis report for ${language}`);
+          }
+          const processedCount = results.length + 1;
 
           if (!args.json) {
             console.log(t('analyze.completed', { language }) || `✅ Analysis completed for ${language}`);
@@ -842,9 +874,9 @@ try {
       console.log(t('analyze.finished') || '\n✅ Analysis completed successfully!');
       
       // Only prompt for input if running standalone and not in no-prompt mode
-      if (require.main === module && !this.noPrompt) {
-        await this.prompt('\nPress Enter to continue...');
-      }
+      if (require.main === module && !this.noPrompt && process.env.CI !== 'true' && process.stdin.isTTY && process.stdout.isTTY) {
+        await this.prompt('\nPress Enter to continue...');
+      }
       this.closeReadline();
       
       return results;
@@ -881,8 +913,8 @@ try {
         const uiLanguage = this.config.uiLanguage || 'en';
         loadTranslations(uiLanguage, path.resolve(__dirname, '..', 'ui-locales'));
         
-        this.sourceDir = this.config.sourceDir;
-        this.sourceLanguageDir = path.join(this.sourceDir, this.config.sourceLanguage);
+        this.sourceDir = this.config.localesDir || this.config.i18nDir || this.config.sourceDir;
+        this.sourceLanguageDir = path.join(this.sourceDir, this.config.sourceLanguage);
         this.outputDir = this.config.outputDir;
       }
       
@@ -921,19 +953,20 @@ try {
         loadTranslations(args.uiLanguage, path.resolve(__dirname, '..', 'ui-locales'));}
       
       // Update config if source directory is provided
-      if (args.sourceDir) {
-        this.config.sourceDir = args.sourceDir;
-        this.sourceDir = path.resolve(PROJECT_ROOT, this.config.sourceDir);
-        this.sourceLanguageDir = path.join(this.sourceDir, this.config.sourceLanguage);
-      }
+      const localeDirArg = args.i18nDir || (!args.i18nDir && args.sourceDir ? args.sourceDir : null);
+      if (localeDirArg) {
+        this.config.i18nDir = localeDirArg;
+        this.sourceDir = path.resolve(PROJECT_ROOT, localeDirArg);
+        this.sourceLanguageDir = path.join(this.sourceDir, this.config.sourceLanguage);
+      }
       
       if (args.outputDir) {
         this.config.outputDir = args.outputDir;
         this.outputDir = path.resolve(this.config.outputDir);
       }
-      const execute = async () => {
-        await this.analyze();
-      };
+      const execute = async () => {
+        return await this.analyze();
+      };
 
       if (args.watch) {
         await execute();
@@ -949,19 +982,21 @@ try {
         });
         console.log('��� Watching for translation changes. Press Ctrl+C to exit.');
       } else {
-        await execute();
-        if (!fromMenu && require.main === module) {
-          process.exit(0);
-        }
-      }
-    } catch (error) {
-      console.error(t('analyze.error') || '❌ Analysis failed:', error.message);
-      this.closeReadline();
-      if (!fromMenu && require.main === module) {
-        process.exit(1);
-      }
-    }
-  }
+        const result = await execute();
+        if (!fromMenu && require.main === module) {
+          process.exit(0);
+        }
+        return result;
+      }
+    } catch (error) {
+      console.error(t('analyze.error') || '❌ Analysis failed:', error.message);
+      this.closeReadline();
+      if (!fromMenu && require.main === module) {
+        process.exit(1);
+      }
+      throw error;
+    }
+  }
   
   async runSetupWizard() {
     console.log('Translation Analysis Setup Wizard');

package/main/i18ntk-complete.js

@@ -16,9 +16,10 @@ const path = require('path');
 const fs = require('fs');
 const SecurityUtils = require('../utils/security');
 const { loadTranslations, t } = require('../utils/i18n-helper');
-const { getGlobalReadline, closeGlobalReadline } = require('../utils/cli');
-const SetupEnforcer = require('../utils/setup-enforcer');
-const { getUnifiedConfig } = require('../utils/config-helper');
+const { getGlobalReadline, closeGlobalReadline } = require('../utils/cli');
+const SetupEnforcer = require('../utils/setup-enforcer');
+const { getUnifiedConfig, displayHelp } = require('../utils/config-helper');
+const { isInteractive } = require('../utils/prompt-helper');
 
 // Ensure setup is complete before running, except for help output.
 (async () => {
@@ -64,7 +65,7 @@ class I18nCompletionTool {
       
       const baseConfig = await getUnifiedConfig('complete', args);
       this.config = { ...baseConfig, ...(this.config || {}) };
-      this.sourceDir = this.config.sourceDir;
+      this.sourceDir = this.config.localesDir || this.config.i18nDir || this.config.sourceDir;
       this.sourceLanguageDir = path.join(this.sourceDir, this.config.sourceLanguage);
       
       // Validate source directory exists
@@ -99,24 +100,31 @@ class I18nCompletionTool {
     const args = process.argv.slice(2);
     const parsed = {};
     
-    args.forEach(arg => {
-      if (arg.startsWith('--')) {
-        const [key, value] = arg.substring(2).split('=');
-        if (key === 'source-dir') {
-          parsed.sourceDir = value;
-        } else if (key === 'source-language') {
-          parsed.sourceLanguage = value;
-        } else if (key === 'auto-translate') {
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i];
+      if (arg.startsWith('--')) {
+        const [key, rawValue] = arg.substring(2).split('=');
+        const value = rawValue !== undefined
+          ? rawValue
+          : (args[i + 1] && !args[i + 1].startsWith('--') ? args[++i] : true);
+        if (key === 'source-dir' || key === 'locales-dir' || key === 'i18n-dir') {
+          parsed.sourceDir = value;
+          parsed.i18nDir = value;
+      } else if (key === 'source-language' || key === 'source-locale') {
+        parsed.sourceLanguage = value;
+      } else if (key === 'code-dir' || key === 'source-code-dir') {
+        parsed.codeDir = value;
+      } else if (key === 'auto-translate') {
           parsed.autoTranslate = true;
         } else if (key === 'dry-run') {
           parsed.dryRun = true;
         } else if (key === 'no-prompt') {
           parsed.noPrompt = true;
         } else if (key === 'help' || key === 'h') {
-          parsed.help = true;
-        }
-      }
-    });
+          parsed.help = true;
+        }
+      }
+    }
     
     return parsed;
   }
@@ -567,22 +575,24 @@ class I18nCompletionTool {
       
       const uiLanguage = (this.config && this.config.uiLanguage) || 'en';
       loadTranslations(uiLanguage, path.resolve(__dirname, '..', 'ui-locales'));
-      this.sourceDir = this.config.sourceDir;
+      this.sourceDir = this.config.localesDir || this.config.i18nDir || this.config.sourceDir;
       this.sourceLanguageDir = path.join(this.sourceDir, this.config.sourceLanguage);
     } else {
       await this.initialize();
       
-      if (args.sourceDir) {
-        const resolvedSourceDir = path.resolve(args.sourceDir);
-        const validatedSourceDir = SecurityUtils.validatePath(resolvedSourceDir, process.cwd());
-        if (!validatedSourceDir) {
-          console.error(t("complete.invalidSourceDir", { sourceDir: args.sourceDir }));
-          console.error(`Path validation failed — source directory is outside the allowed project boundary.`);
-          process.exit(1);
-        }
-        this.config.sourceDir = resolvedSourceDir;
-        this.sourceDir = validatedSourceDir;
-      }
+      const localesDirArg = args.i18nDir || args.sourceDir;
+      if (localesDirArg) {
+        const resolvedSourceDir = path.resolve(localesDirArg);
+        const validatedSourceDir = SecurityUtils.validatePath(resolvedSourceDir, process.cwd());
+        if (!validatedSourceDir) {
+          console.error(t("complete.invalidSourceDir", { sourceDir: localesDirArg }));
+          console.error(`Path validation failed — source directory is outside the allowed project boundary.`);
+          process.exit(1);
+        }
+        this.config.sourceDir = resolvedSourceDir;
+        this.config.i18nDir = resolvedSourceDir;
+        this.sourceDir = validatedSourceDir;
+      }
       
       if (args.sourceLanguage) {
         this.config.sourceLanguage = SecurityUtils.sanitizeInput(args.sourceLanguage, { 
@@ -643,15 +653,24 @@ class I18nCompletionTool {
       }
       
       console.log('\n');
-      console.log(t("complete.summaryTitle"));
-      console.log(t("complete.separator"));
-      console.log(t("complete.totalChanges", { totalChanges }));
-      console.log(t("complete.languagesProcessed", { languagesProcessed: languages.length }));
-      console.log(t("complete.missingKeysAdded", { missingKeysAdded: missingKeys.length }));
-      
-      if (!args.dryRun && allChanges.length > 0 && !args.noPrompt) {
-        const rl = this.rl || this.initReadline();
-        const answer = await this.prompt('\n' + t('complete.generateReportPrompt') + ' (Y/N): ');
+      console.log(t("complete.summaryTitle"));
+      console.log(t("complete.separator"));
+      const targetLocalesChanged = allChanges.length;
+      const filesModified = new Set(allChanges.flatMap(lang => lang.changes.map(change => `${lang.language}/${change.file}`))).size;
+      const filesSkipped = Math.max(0, targetLanguages.length - targetLocalesChanged);
+      console.log(`Locales scanned: ${languages.length}`);
+      console.log(`Target locales changed: ${targetLocalesChanged}`);
+      console.log(`Unique source keys added: ${missingKeys.length}`);
+      console.log(`Total key insertions: ${totalChanges}`);
+      console.log(`Files modified: ${args.dryRun ? 0 : filesModified}`);
+      console.log(`Files skipped: ${filesSkipped}`);
+      if (args.dryRun) {
+        console.log('Dry run only. No files were modified.');
+      }
+      
+      if (!args.dryRun && allChanges.length > 0 && isInteractive(args)) {
+        const rl = this.rl || this.initReadline();
+        const answer = await this.prompt('\n' + t('complete.generateReportPrompt') + ' (Y/N): ');
         
         if (answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes') {
           await this.generateReport(allChanges, languages);

package/main/i18ntk-report.js

@@ -22,23 +22,32 @@ function parseArgs(argv = process.argv.slice(2)) {
     help: false,
   };
 
-  for (const raw of argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const raw = argv[i];
     const arg = raw === 'report' ? '' : raw;
     if (!arg) continue;
+    const nextValue = () => {
+      if (i + 1 < argv.length && !String(argv[i + 1]).startsWith('--')) {
+        return argv[++i];
+      }
+      return null;
+    };
     if (arg === '--help' || arg === '-h') args.help = true;
     else if (arg === '--json') args.json = true;
     else if (arg === '--markdown' || arg === '--md') args.markdown = true;
     else if (arg === '--html') args.html = true;
     else if (arg.startsWith('--out=')) args.out = arg.slice('--out='.length);
-    else if (arg === '--out') args.expectOut = true;
-    else if (args.expectOut) {
-      args.out = arg;
-      args.expectOut = false;
-    } else if (arg.startsWith('--source-dir=')) args.sourceDir = arg.slice('--source-dir='.length);
+    else if (arg === '--out') args.out = nextValue();
+    else if (arg.startsWith('--source-dir=')) args.sourceDir = arg.slice('--source-dir='.length);
+    else if (arg.startsWith('--code-dir=')) args.sourceDir = arg.slice('--code-dir='.length);
+    else if (arg.startsWith('--source-code-dir=')) args.sourceDir = arg.slice('--source-code-dir='.length);
+    else if (arg === '--source-dir' || arg === '--code-dir' || arg === '--source-code-dir') args.sourceDir = nextValue();
     else if (arg.startsWith('--i18n-dir=')) args.i18nDir = arg.slice('--i18n-dir='.length);
     else if (arg.startsWith('--locales-dir=')) args.i18nDir = arg.slice('--locales-dir='.length);
+    else if (arg === '--i18n-dir' || arg === '--locales-dir') args.i18nDir = nextValue();
     else if (arg.startsWith('--source-language=')) args.sourceLocale = arg.slice('--source-language='.length);
     else if (arg.startsWith('--source-locale=')) args.sourceLocale = arg.slice('--source-locale='.length);
+    else if (arg === '--source-language' || arg === '--source-locale') args.sourceLocale = nextValue();
   }
 
   if (!args.json && !args.markdown && !args.html) {
@@ -107,9 +116,13 @@ Options:
   --markdown                Print/write Markdown report output
   --html                    Print/write HTML report output
   --out <dir>               Write selected report formats into a directory
-  --source-dir=<dir>        Source code directory to scan
-  --i18n-dir=<dir>          Locale directory
-  --source-language=<code>  Source locale code (default: en)
+  --code-dir=<dir>          Source code directory to scan
+  --source-code-dir=<dir>   Alias for --code-dir
+  --source-dir=<dir>        Legacy alias for --code-dir
+  --locales-dir=<dir>       Locale directory
+  --i18n-dir=<dir>          Alias for --locales-dir
+  --source-locale=<code>    Source locale code (default: en)
+  --source-language=<code>  Legacy alias for --source-locale
 `;
 }
 

package/main/i18ntk-scanner.js

@@ -133,6 +133,8 @@ class I18nTextScanner {
 
         switch (key) {
           case 'source-dir':
+          case 'code-dir':
+          case 'source-code-dir':
             parsed.sourceDir = value || '';
             if (value === args[i + 1]) i++;
             break;
@@ -167,6 +169,7 @@ class I18nTextScanner {
             parsed.includeTests = true;
             break;
           case 'source-language':
+          case 'source-locale':
             parsed.sourceLanguage = value || '';
             if (value === args[i + 1]) i++;
             break;

package/main/i18ntk-sizing.js

@@ -1141,7 +1141,7 @@ Generated: ${new Date().toISOString()}
         const key = keyValueMatch[1];
         const value = keyValueMatch[2];
         
-        if (key === 'source-dir' || key === 's') {
+        if (key === 'source-dir' || key === 'locales-dir' || key === 'i18n-dir' || key === 's') {
           options['source-dir'] = value;
           options.s = value;
           options.sourceDirExplicit = true;
@@ -1162,7 +1162,7 @@ Generated: ${new Date().toISOString()}
             options.threshold = numValue;
             options.t = numValue;
           }
-        } else if (key === 'source-language') {
+        } else if (key === 'source-language' || key === 'source-locale') {
           options['source-language'] = value;
         } else if (key === 'detailed' || key === 'd') {
           options.detailed = value.toLowerCase() !== 'false';
@@ -1184,7 +1184,7 @@ Generated: ${new Date().toISOString()}
         const key = match[1];
         const nextArg = args[i + 1];
         
-        if (key === 'source-dir' || key === 's') {
+        if (key === 'source-dir' || key === 'locales-dir' || key === 'i18n-dir' || key === 's') {
           options['source-dir'] = nextArg || options['source-dir'];
           options.s = options['source-dir'];
           options.sourceDirExplicit = true;
@@ -1216,7 +1216,7 @@ Generated: ${new Date().toISOString()}
             options.t = value;
           }
           if (nextArg && !nextArg.startsWith('-') && !isNaN(parseInt(nextArg))) i++;
-        } else if (key === 'source-language') {
+        } else if (key === 'source-language' || key === 'source-locale') {
           options['source-language'] = nextArg || options['source-language'];
           if (nextArg && !nextArg.startsWith('-')) i++;
         } else if (key === 'detailed' || key === 'd') {
@@ -1257,12 +1257,15 @@ I18NTK Sizing Analysis Tool
 Usage: i18ntk-sizing [options]
 
 Options:
-  -s, --source-dir <dir>      Source directory containing translation files (default: ./locales)
+  -s, --locales-dir <dir>     Locale directory containing translation files (default: ./locales)
+  --i18n-dir <dir>            Alias for --locales-dir
+  --source-dir <dir>          Legacy alias for --locales-dir
   -l, --languages <langs>     Comma-separated list of languages to analyze
   -o, --output-report         Generate detailed sizing report (default: true)
   -f, --format <format>       Output format: json, csv, table (default: table)
   -t, --threshold <number>    Size difference threshold for warnings (%) (default: 50)
-  --source-language <code>    Source language baseline for comparisons (default: en)
+  --source-locale <code>      Source locale baseline for comparisons (default: en)
+  --source-language <code>    Legacy alias for --source-locale
   -d, --detailed              Generate detailed report with more information
   --detailed-keys             Show detailed key-level analysis
   --predict-expansion         Predict UI layout expansion risk per language