@ddongule/i18n-cli 1.0.0

package/README.md

@@ -0,0 +1,365 @@
+# i18n-cli
+
+A practical i18n maintenance CLI for front-end repositories.
+
+It helps you:
+- **Scan** code usage vs. locale JSON files
+- Detect **Missing** keys (used in code but absent in locale files)
+- Detect **Unused** keys (present in locale files but not used in code)
+- **Safely fix** issues (create missing keys, delete unused keys, align locale structures)
+- **Import** translations from **Google Sheets** or **.xlsx**
+- (Optional) **Export** locale JSON back to Google Sheets (if enabled in your build)
+
+> Designed for real-world teams: dry-run first, safe deletes, and predictable output.
+
+---
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Project Conventions](#project-conventions)
+- [Commands](#commands)
+  - [scan](#scan)
+  - [import](#import)
+  - [export](#export)
+- [How It Works](#how-it-works)
+- [Sample: Before & After](#sample-before--after)
+- [Google Sheets Setup](#google-sheets-setup)
+- [CI / Automation Ideas](#ci--automation-ideas)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Quick Start
+
+### Install
+
+Use `npx` (no install):
+
+```bash
+npx i18n-cli scan
+```
+
+Or install as a dev dependency:
+
+```bash
+pnpm add -D i18n-cli
+# or npm i -D i18n-cli
+# or yarn add -D i18n-cli
+```
+
+Then run:
+
+```bash
+pnpm i18n-cli scan
+# or npx i18n-cli scan
+```
+
+---
+
+## Project Conventions
+
+`i18n-cli` assumes:
+
+- Your locale files are JSON under:
+
+```
+./locales/
+  en.json
+  ko.json
+  ja.json
+  ...
+```
+
+- Your code uses translation keys like:
+
+```ts
+t("home.title")
+t("profile.logout.button")
+```
+
+If your project uses a different `t()` function name or different patterns, you can extend the scanner in your fork (or add a custom scanner later).
+
+---
+
+## Commands
+
+Run `npx i18n-cli --help` for the latest options.
+
+### scan
+
+Scan your repository and report i18n status.
+
+```bash
+npx i18n-cli scan
+```
+
+#### Most used options
+
+- `--lang <code>`: base locale language (default: `en`)
+- `--md`: print Markdown report and save to `i18n-report.md` (unless `--no-save`)
+- `--json`: print JSON report and save to `i18n-report.json` (unless `--no-save`)
+- `--no-save`: do not save reports (works with `--md` / `--json`)
+- `--check-consistency`: verify all locale structures are aligned
+- `--delete-unused`: delete unused keys (**safe unused only**, if enabled)
+- `--create-missing`: create missing keys with an empty placeholder
+- `--fix-structure`: align locale structures
+- `--locale <code>`: apply modifications to only one locale (default: all)
+- `--dry-run`: simulate changes only (recommended first)
+- `--backup`: backup locale files before writing
+- `--no-confirm`: do not ask before applying changes
+
+#### Examples
+
+Base locale `en`, print pretty output:
+
+```bash
+npx i18n-cli scan --lang en
+```
+
+Generate Markdown report without saving:
+
+```bash
+npx i18n-cli scan --md --no-save
+```
+
+Create missing keys across **all locales**, but do not write:
+
+```bash
+npx i18n-cli scan --create-missing --dry-run
+```
+
+Delete safe unused keys and apply changes:
+
+```bash
+npx i18n-cli scan --delete-unused
+```
+
+> Tip: Prefer **dry-run first** before writing changes.
+
+---
+
+### import
+
+Import translations into `./locales/*.json` from either `.xlsx` or Google Sheets.
+
+#### Import from XLSX
+
+```bash
+npx i18n-cli import --file ./translations.xlsx
+```
+
+Options:
+- `--file <path>`: path to `.xlsx`
+- `--override`: replace existing translations
+- `--dry-run`: preview only
+- `--locales-dir <path>`: target locales folder (default `./locales`)
+
+#### Import from Google Sheets
+
+```bash
+npx i18n-cli import --sheet <SPREADSHEET_ID> --sheet-name <TAB_NAME>
+```
+
+Common options:
+- `--sheet <id>`: Google spreadsheet id
+- `--sheet-name <name>`: sheet tab name (e.g. `Translations`)
+- `--cred <path>`: service account credentials JSON path  
+  (default example: `./credentials/google-service-account.json`)
+- `--dry-run`: preview only
+- `--override`: replace existing translations
+- `--locales-dir <path>`: target locales folder (default `./locales`)
+
+Example:
+
+```bash
+npx i18n-cli import \
+  --sheet 1L7h7Ra3hrOrp5MW7_uWV6ANNrBF0b9CgSfJ9hXy7D7w \
+  --sheet-name Translations \
+  --cred ./credentials/google-service-account.json
+```
+
+---
+
+### export
+
+If your build includes `export` (optional), you can export locale JSON to Google Sheets.
+
+```bash
+npx i18n-cli export --sheet <SPREADSHEET_ID> --sheet-name <TAB_NAME>
+```
+
+Typical options:
+- `--sheet <id>`
+- `--sheet-name <tab>`
+- `--cred <path>`
+- `--dry-run`
+- `--locales-dir <path>`
+
+---
+
+## How It Works
+
+### Key concepts
+
+- **Base locale**: the “source of truth” structure (usually `en`)
+- **Missing keys**: keys used in code but missing in one or more locales
+- **Unused keys**: keys present in locale files but not referenced in code
+
+### What gets scanned
+
+- `./locales/*.json` are loaded and flattened to dot-keys:
+  - `{"home":{"title":"Welcome"}}` → `home.title`
+- Code scanner searches for patterns like:
+  - `t("...")`, `i18n.t("...")`, etc. (depends on your implementation)
+
+---
+
+## Sample: Before & After
+
+### Example locale files
+
+`locales/en.json`
+
+```json
+{
+  "home": {
+    "title": "Welcome",
+    "button": { "ok": "OK" }
+  },
+  "profile": {
+    "logout": { "button": "Logout" }
+  },
+  "settings2": {
+    "notification": { "enabled": "On" }
+  }
+}
+```
+
+`locales/ko.json`
+
+```json
+{
+  "home": {
+    "title": "환영합니다"
+  }
+}
+```
+
+### Example code
+
+```ts
+function example() {
+  t("home.title");
+  t("profile.logout.button");
+  t("settings.notification.enabled");
+}
+```
+
+### Run scan
+
+```bash
+npx i18n-cli scan --lang en
+```
+
+Example findings:
+- **Missing (per-locale)**: `profile.logout.button` missing in `ko`, `settings.notification.enabled` missing in multiple
+- **Unused (locale-only)**: `home.button.ok`, `settings2.notification.enabled`
+
+### Fix structure & create missing (dry-run first)
+
+```bash
+npx i18n-cli scan --fix-structure --create-missing --dry-run
+```
+
+Then apply:
+
+```bash
+npx i18n-cli scan --fix-structure --create-missing
+```
+
+After (example result):
+
+`locales/ko.json`
+
+```json
+{
+  "home": {
+    "title": "환영합니다",
+    "button": { "ok": "" }
+  },
+  "profile": {
+    "logout": { "button": "" }
+  },
+  "settings": {
+    "notification": { "enabled": "" }
+  }
+}
+```
+
+---
+
+## Google Sheets Setup
+
+### 1) Create a Google Cloud project & service account
+
+- Create a **Service Account** in Google Cloud Console
+- Create a **JSON key** and save it (e.g. `./credentials/google-service-account.json`)
+
+### 2) Share the sheet with the service account email
+
+Open the spreadsheet → **Share** → add:
+- `client_email` from your credentials JSON
+
+Give it **Viewer** for import, and **Editor** for export.
+
+### 3) Sheet format
+
+Recommended header:
+
+| key | en | ko | ja |
+|---|---|---|---|
+| home.title | Welcome | 환영합니다 | ようこそ |
+
+Notes:
+- First column is the key (dot format)
+- Languages can be any codes (`en`, `ko`, `ja`, ...)
+
+If your sheet has extra header rows, the importer should locate the header row containing `key` + language columns.
+
+---
+
+## CI / Automation Ideas
+
+- Run `scan --json` on PR and upload `i18n-report.json` as an artifact
+- Fail CI if missing keys exceed a threshold
+- Use `--dry-run` in CI; apply fixes via a separate “fix PR” job
+
+---
+
+## Troubleshooting
+
+### “Google credentials file not found”
+Provide credentials:
+
+```bash
+npx i18n-cli import --sheet <ID> --cred ./credentials/google-service-account.json
+```
+
+### “Unable to parse range”
+Your sheet tab name is wrong:
+
+```bash
+npx i18n-cli import --sheet <ID> --sheet-name <TAB_NAME>
+```
+
+### “No locale files found”
+Ensure:
+- `./locales` exists
+- files are named like `en.json`, `ko.json`
+
+---
+
+## License
+
+MIT

package/dist/commands/import.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importCommand = importCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const path_1 = __importDefault(require("path"));
+const i18n_mcp_core_1 = require("i18n-mcp-core");
+function importCommand(program) {
+    program
+        .command("import")
+        .description("import translations from spreadsheet")
+        .option("--file <path>", "xlsx file to import")
+        .option("--override", "replace existing translations", false)
+        .option("--dry-run", "simulate only", false)
+        .option("--sheet <id>", "google sheet id")
+        .option("--sheet-name <name>", "Google Sheet tab name", "Sheet1")
+        .option("--cred <path>", "google credentials path", "./credentials/google-service-account.json")
+        .action(async (options) => {
+        const { file, sheet } = options;
+        //
+        // GOOGLE SHEET MODE
+        //
+        if (sheet) {
+            const range = options.range || `${options.sheetName}!A1:Z9999`;
+            console.log(chalk_1.default.blue(`\n📥 Importing from Google Sheet (${options.sheetName})...\n`));
+            try {
+                await (0, i18n_mcp_core_1.importGoogleSheet)({
+                    sheetId: options.sheet,
+                    range,
+                    credentialsPath: options.cred, // 🔥 FIX
+                    dryRun: options.dryRun,
+                });
+                console.log(chalk_1.default.green("\n🎉 Google Sheet Import Completed!\n"));
+            }
+            catch (e) {
+                console.error(chalk_1.default.red("\n❌ Google Sheet Import Failed\n"));
+                console.error(e?.message || e);
+            }
+            return;
+        }
+        //
+        // XLSX MODE
+        //
+        if (!file) {
+            console.log(chalk_1.default.red("❌ --file is required"));
+            return;
+        }
+        const fullPath = path_1.default.join(process.cwd(), file);
+        console.log(chalk_1.default.blue("\n📥 Importing translations..."));
+        console.log(chalk_1.default.gray(`File: ${fullPath}`));
+        try {
+            await (0, i18n_mcp_core_1.importSpreadsheet)({
+                file: options.file,
+                override: options.override,
+                dryRun: options.dryRun,
+            });
+            console.log(chalk_1.default.green("\n🎉 Import completed!\n"));
+        }
+        catch (e) {
+            console.error(chalk_1.default.red("\n❌ Import failed"));
+            console.error(e.message || e);
+        }
+    });
+}

package/dist/commands/scan.js

@@ -0,0 +1,540 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanCommand = scanCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const readline_1 = __importDefault(require("readline"));
+const i18n_mcp_core_1 = require("i18n-mcp-core");
+const createPullRequest_1 = require("../utils/createPullRequest");
+const checkGh_1 = require("../utils/checkGh");
+function scanCommand(program) {
+    program
+        .command("scan")
+        .description("scan project & generate report")
+        .option("--md", "output as markdown & save file")
+        .option("--json", "output as json & save file")
+        .option("--no-save", "do not save report when using md/json")
+        .option("--lang <code>", "base locale language", "en")
+        .option("--delete-unused", "delete unused keys")
+        .option("--create-missing", "create missing keys with placeholder")
+        .option("--locale <code>", "apply fixes to only specific locale (default = ALL)")
+        .option("--check-consistency", "verify all locale structures are aligned")
+        .option("--fix-structure", "force align locale structures to base locale")
+        .option("--dry-run", "simulate changes only")
+        .option("--backup", "backup locale files before modifying", false)
+        .option("--no-confirm", "do not ask before applying changes")
+        .action(async (options) => {
+        const { md, json, lang, save, deleteUnused, createMissing, locale, checkConsistency, fixStructure, dryRun, backup, confirm, } = options;
+        console.log(chalk_1.default.blue("\n📦 Running i18n scan...\n"));
+        if (options.pr && options.dryRun) {
+            console.log(chalk_1.default.red("\n❌ Cannot create PR in dry-run mode.\n" +
+                "Remove --dry-run to allow file changes and PR creation.\n"));
+            return;
+        }
+        console.log(chalk_1.default.bgBlue.black(`  BASE LOCALE  `), chalk_1.default.white.bold(lang), "\n");
+        const localesDir = path_1.default.join(process.cwd(), "locales");
+        const locales = (0, i18n_mcp_core_1.loadLocales)(localesDir); // { en: {...}, ko: {...} }
+        const codeKeys = (0, i18n_mcp_core_1.scanCode)(process.cwd());
+        const diff = (0, i18n_mcp_core_1.analyzeDiff)(locales, codeKeys, lang);
+        // --- classify unused keys ---
+        const baseLang = lang;
+        const baseFlat = flattenLocaleObject(locales[baseLang]);
+        const localeFlats = {};
+        Object.entries(locales).forEach(([l, obj]) => {
+            localeFlats[l] = flattenLocaleObject(obj);
+        });
+        const safeUnused = [];
+        const unusedAndMissing = [];
+        diff.unused.forEach((key) => {
+            const missingIn = [];
+            Object.entries(localeFlats).forEach(([l, flat]) => {
+                if (!(key in flat))
+                    missingIn.push(l);
+            });
+            if (missingIn.length === 0) {
+                safeUnused.push(key);
+            }
+            else {
+                unusedAndMissing.push({ key, missingIn });
+            }
+        });
+        // "." 같은 이상한 값 방지
+        diff.missing = diff.missing.filter((k) => k && k.trim() && k !== "." && !/^\.+$/.test(k));
+        diff.unused = diff.unused.filter((k) => k && k.trim() && k !== "." && !/^\.+$/.test(k));
+        // 출력 포맷
+        if (md) {
+            printMarkdown(diff);
+            if (save !== false)
+                saveMarkdown(diff);
+        }
+        else if (json) {
+            printJson(diff);
+            if (save !== false)
+                saveJson(diff);
+        }
+        else {
+            printPretty(diff, locales);
+        }
+        // 구조 일관성 체크
+        if (checkConsistency) {
+            runConsistencyCheck(locales, lang);
+        }
+        const willModify = !!deleteUnused || !!createMissing || !!fixStructure;
+        if (!willModify)
+            return;
+        const targetLocales = locale ? [locale] : Object.keys(locales);
+        const backupDir = path_1.default.join(localesDir, ".i18n-mcp-backup", new Date().toISOString().replace(/[:.]/g, "-"));
+        if (!dryRun && confirm !== false) {
+            console.log(chalk_1.default.yellow(`\nAbout to modify locales: ${targetLocales.join(", ")}`));
+            const ok = await askForConfirmation("Continue?");
+            if (!ok) {
+                console.log(chalk_1.default.red("\n❌ Aborted by user.\n"));
+                return;
+            }
+        }
+        // unused 삭제 / missing 생성
+        if (deleteUnused || createMissing) {
+            applyFixes({
+                diff,
+                safeUnused,
+                baseLang: lang,
+                localesDir,
+                targetLocale: locale,
+                locales,
+                deleteUnused,
+                createMissing,
+                dryRun: !!dryRun,
+                backup: !!backup,
+                backupDir,
+            });
+        }
+        // 구조 강제 정렬
+        if (fixStructure) {
+            fixLocaleStructure({
+                baseLang: lang,
+                locales,
+                localesDir,
+                targetLocale: locale,
+                dryRun: !!dryRun,
+                backup: !!backup,
+                backupDir,
+            });
+        }
+        const hasChanges = (deleteUnused && safeUnused.length > 0) ||
+            (createMissing && diff.missing.length > 0) ||
+            fixStructure;
+        if (!options.pr) {
+            return;
+        }
+        if (!hasChanges) {
+            console.log(chalk_1.default.yellow("\n⚠ No changes detected.\n" +
+                "PR creation skipped because there are no file modifications.\n"));
+            return;
+        }
+        try {
+            (0, checkGh_1.ensureGhInstalled)();
+        }
+        catch (e) {
+            console.log(chalk_1.default.red("\n❌ " + e.message + "\n"));
+            return;
+        }
+        if (!dryRun) {
+            const branch = `i18n/update-${Date.now()}`;
+            const body = `
+            ## 🧩 i18n Update Summary
+            
+            ### Changes
+            - 🧹 Removed unused keys: ${safeUnused.length}
+            - ✨ Created missing keys: ${diff.missing.length}
+            - 🏗 Fixed locale structure: ${fixStructure ? "yes" : "no"}
+            
+            ### Affected Locales
+            ${Object.keys(locales)
+                .map((l) => `- ${l}`)
+                .join("\n")}
+            
+            ---
+
+            Generated by i18n-mcp 🤖
+            `.trim();
+            (0, createPullRequest_1.createPullRequest)({
+                title: options.prTitle,
+                body,
+                draft: options.prDraft,
+                branch,
+            });
+        }
+    });
+}
+function buildMissingByLocale(baseLang, locales) {
+    const base = locales[baseLang];
+    if (!base)
+        return {};
+    const baseFlat = flattenLocaleObject(base);
+    const baseKeys = Object.keys(baseFlat);
+    const result = {};
+    baseKeys.forEach((key) => {
+        Object.entries(locales).forEach(([lang, obj]) => {
+            if (lang === baseLang)
+                return;
+            const flat = flattenLocaleObject(obj);
+            if (!(key in flat)) {
+                if (!result[key])
+                    result[key] = [];
+                result[key].push(lang);
+            }
+        });
+    });
+    return result;
+}
+/* ---------------- OUTPUT ---------------- */
+function printPretty(diff, locales) {
+    console.log(chalk_1.default.green("📦 i18n Scan Result\n"));
+    console.log(chalk_1.default.green("✔ Locale Keys in Base:"), diff.totalLocaleKeys, chalk_1.default.gray("(unique translation keys in base locale)"));
+    console.log(chalk_1.default.green("✔ Keys Used in Code:"), diff.totalCodeKeys, chalk_1.default.gray("(detected from t('...') calls)"));
+    console.log(chalk_1.default.gray("\n--------------------------------------\n"));
+    /* ---------- PER LOCALE STATUS ---------- */
+    console.log(chalk_1.default.magenta("🌍 Locale Status\n"));
+    // base locale의 실제 nested JSON 기준으로 flatten
+    const baseLocaleObj = locales[diff.baseLang];
+    if (!baseLocaleObj) {
+        console.log(chalk_1.default.red(`⚠ Base locale "${diff.baseLang}" not found in loaded locales.`));
+    }
+    else {
+        const baseFlat = flattenLocaleObject(baseLocaleObj);
+        const baseKeys = Object.keys(baseFlat);
+        const baseTotal = baseKeys.length;
+        Object.entries(locales).forEach(([lang, obj]) => {
+            const flat = flattenLocaleObject(obj);
+            // base key 중 이 locale이 가지고 있는 key 수
+            const present = baseKeys.filter((k) => k in flat).length;
+            const missing = baseTotal - present;
+            const extra = Object.keys(flat).filter((k) => !(k in baseFlat)).length;
+            const health = baseTotal === 0 ? 100 : Math.round((present / baseTotal) * 100);
+            const bar = healthBar(health);
+            console.log(`${chalk_1.default.cyan(lang)}  →  ${health}% ${bar}  ` +
+                chalk_1.default.gray(`(${present}/${baseTotal} keys present, ${missing} missing, ${extra} extra)`));
+        });
+    }
+    console.log(chalk_1.default.gray("\n--------------------------------------\n"));
+    /* ---------- MISSING (DETAILED BY LOCALE) ---------- */
+    const missingByLocale = buildMissingByLocale(diff.baseLang, locales);
+    const missingKeys = Object.keys(missingByLocale);
+    console.log(chalk_1.default.red(`❗ Missing Keys (${missingKeys.length})\n` +
+        chalk_1.default.gray("These keys exist in the base locale, but are missing in the following locales.")));
+    if (missingKeys.length === 0) {
+        console.log(chalk_1.default.gray("  (None 🎉 All locales are up to date)"));
+    }
+    else {
+        missingKeys.forEach((key) => {
+            console.log(chalk_1.default.red(`  - ${key}`));
+            missingByLocale[key].forEach((lang) => {
+                console.log(chalk_1.default.gray(`      ↳ missing in: ${lang}`));
+            });
+        });
+    }
+    /* ---------- UNUSED (CLASSIFIED) ---------- */
+    const baseLang = diff.baseLang;
+    const baseFlat = flattenLocaleObject(locales[baseLang]);
+    const localeFlats = {};
+    Object.entries(locales).forEach(([lang, obj]) => {
+        localeFlats[lang] = flattenLocaleObject(obj);
+    });
+    const safeUnused = [];
+    const unusedAndMissing = [];
+    diff.unused.forEach((key) => {
+        const missingIn = [];
+        Object.entries(localeFlats).forEach(([lang, flat]) => {
+            if (!(key in flat))
+                missingIn.push(lang);
+        });
+        if (missingIn.length === 0) {
+            safeUnused.push(key);
+        }
+        else {
+            unusedAndMissing.push({ key, missingIn });
+        }
+    });
+    console.log(chalk_1.default.yellow(`\n🧹 Unused Keys (Safe to remove)\n` +
+        chalk_1.default.gray("These keys exist in all locale files, but are not used in code.")));
+    if (safeUnused.length === 0) {
+        console.log(chalk_1.default.gray("  (None 👍 No safe unused keys found)"));
+    }
+    else {
+        safeUnused.forEach((k) => console.log(chalk_1.default.yellow("  - " + k)));
+    }
+    console.log(chalk_1.default.magenta(`\n🧪 Unused & Missing Keys\n` +
+        chalk_1.default.gray("These keys are not used in code and are missing in some locales.")));
+    if (unusedAndMissing.length === 0) {
+        console.log(chalk_1.default.gray("  (None)"));
+    }
+    else {
+        unusedAndMissing.forEach(({ key, missingIn }) => {
+            console.log(chalk_1.default.green("  - " + key));
+            console.log(chalk_1.default.gray(`      ↳ missing in: ${missingIn.join(", ")}`));
+        });
+    }
+    console.log("\n");
+    /* ---------- NEXT ACTIONS ---------- */
+    console.log(chalk_1.default.blue("💡 Next Actions"));
+    console.log(chalk_1.default.gray("• Remove unused keys:"), chalk_1.default.white("i18n-mcp scan --delete-unused"));
+    console.log(chalk_1.default.gray("• Create missing keys with placeholders:"), chalk_1.default.white("i18n-mcp scan --create-missing"));
+    console.log(chalk_1.default.gray("• Align all locale structures to base:"), chalk_1.default.white("i18n-mcp scan --fix-structure"));
+    console.log(chalk_1.default.gray("• Export markdown report:"), chalk_1.default.white("i18n-mcp scan --md"));
+    console.log(chalk_1.default.gray("• Export json report:"), chalk_1.default.white("i18n-mcp scan --json"));
+    console.log("\n" + chalk_1.default.gray("────────────────────────────────\n"));
+}
+/* ---------- HEALTH BAR UI ---------- */
+function healthBar(percent) {
+    const total = 20;
+    const filled = Math.round((percent / 100) * total);
+    return (chalk_1.default.green("█".repeat(filled)) + chalk_1.default.gray("█".repeat(total - filled)));
+}
+function printMarkdown(diff) {
+    console.log(`## 📦 i18n Scan Result\n`);
+    console.log(`- Base Locale: **${diff.baseLang}**`);
+    console.log(`- Locale Keys: **${diff.totalLocaleKeys}**`);
+    console.log(`- Code Keys: **${diff.totalCodeKeys}**\n`);
+    console.log(`---\n`);
+    console.log(`### ❗ Missing (${diff.missing.length})`);
+    diff.missing.length === 0
+        ? console.log("- none")
+        : diff.missing.forEach((k) => console.log(`- ${k}`));
+    console.log(`\n### 🧹 Unused (${diff.unused.length})`);
+    diff.unused.length === 0
+        ? console.log("- none")
+        : diff.unused.forEach((k) => console.log(`- ${k}`));
+}
+function saveMarkdown(diff) {
+    const content = `
+  ## 📦 i18n Scan Result
+  
+  - Base Locale: **${diff.baseLang}**
+  - Locale Keys: **${diff.totalLocaleKeys}**
+  - Code Keys: **${diff.totalCodeKeys}**
+  
+  ---
+  
+  ### ❗ Missing (${diff.missing.length})
+  ${diff.missing.length === 0
+        ? "- none"
+        : diff.missing.map((k) => `- ${k}`).join("\n")}
+  
+  ### 🧹 Unused (${diff.unused.length})
+  ${diff.unused.length === 0
+        ? "- none"
+        : diff.unused.map((k) => `- ${k}`).join("\n")}
+  `.trim();
+    fs_1.default.writeFileSync("i18n-report.md", content);
+    console.log(chalk_1.default.green("\n💾 Markdown saved → i18n-report.md\n"));
+}
+function printJson(diff) {
+    console.log(JSON.stringify(diff, null, 2));
+}
+function saveJson(diff) {
+    fs_1.default.writeFileSync("i18n-report.json", JSON.stringify(diff, null, 2));
+    console.log(chalk_1.default.green("\n💾 JSON saved → i18n-report.json\n"));
+}
+/* ---------------- FLATTEN HELPER ---------------- */
+// nested locale → flat { "a.b.c": value }
+function flattenLocaleObject(obj, prefix = "", result = {}) {
+    if (typeof obj !== "object" || obj === null)
+        return result;
+    Object.entries(obj).forEach(([key, value]) => {
+        const full = prefix ? `${prefix}.${key}` : key;
+        if (typeof value === "object" && value !== null) {
+            flattenLocaleObject(value, full, result);
+        }
+        else {
+            result[full] = value;
+        }
+    });
+    return result;
+}
+/* ---------------- CONSISTENCY ---------------- */
+function runConsistencyCheck(locales, baseLang) {
+    const base = locales[baseLang];
+    if (!base) {
+        console.log(chalk_1.default.red(`⚠ base locale "${baseLang}" missing`));
+        return;
+    }
+    const baseFlat = flattenLocaleObject(base);
+    const baseKeys = new Set(Object.keys(baseFlat));
+    console.log(chalk_1.default.magenta("\n🌍 Locale Consistency Report\n"));
+    Object.entries(locales).forEach(([lang, map]) => {
+        if (lang === baseLang)
+            return;
+        const flat = flattenLocaleObject(map);
+        const keys = new Set(Object.keys(flat));
+        const missing = [];
+        const extra = [];
+        baseKeys.forEach((k) => !keys.has(k) && missing.push(k));
+        keys.forEach((k) => !baseKeys.has(k) && extra.push(k));
+        if (!missing.length && !extra.length) {
+            console.log(chalk_1.default.green(`✅ ${lang}: consistent`));
+            return;
+        }
+        console.log(chalk_1.default.yellow(`\n🔸 ${lang}`));
+        if (missing.length) {
+            console.log(chalk_1.default.red(`  ❗ Missing`));
+            missing.forEach((k) => console.log(`    - ${k}`));
+        }
+        if (extra.length) {
+            console.log(chalk_1.default.yellow(`  ⚠ Extra`));
+            extra.forEach((k) => console.log(`    - ${k}`));
+        }
+    });
+    console.log();
+}
+/* ---------------- APPLY FIXES ---------------- */
+function applyFixes({ diff, safeUnused, localesDir, targetLocale, locales, deleteUnused, createMissing, dryRun, backup, backupDir, }) {
+    const targets = targetLocale ? [targetLocale] : Object.keys(locales);
+    console.log(chalk_1.default.magenta(`\n🔧 Applying fixes to ${targets.join(", ")} (dryRun=${dryRun})\n`));
+    targets.forEach((lang) => {
+        const file = path_1.default.join(localesDir, `${lang}.json`);
+        if (!fs_1.default.existsSync(file))
+            return;
+        let obj = JSON.parse(fs_1.default.readFileSync(file, "utf-8"));
+        let deleted = 0;
+        let created = 0;
+        if (deleteUnused && diff.unused?.length)
+            deleted = deleteUnusedKeysFromObject(obj, safeUnused);
+        if (createMissing && diff.missing?.length)
+            created = createMissingKeysInObject(obj, diff.missing, "");
+        pruneEmptyObjects(obj);
+        if (dryRun)
+            console.log(chalk_1.default.gray(`[DRY-RUN] ${lang}: delete ${deleted}, create ${created}`));
+        else {
+            if (backup)
+                ensureBackup(file, lang, backupDir);
+            fs_1.default.writeFileSync(file, JSON.stringify(obj, null, 2));
+            console.log(chalk_1.default.green(`✔ ${lang}: deleted ${deleted}, created ${created}`));
+        }
+    });
+}
+/* ---------------- FIX STRUCTURE ---------------- */
+function fixLocaleStructure({ baseLang, locales, localesDir, targetLocale, dryRun, backup, backupDir, }) {
+    const baseFile = path_1.default.join(localesDir, `${baseLang}.json`);
+    if (!fs_1.default.existsSync(baseFile)) {
+        console.log(chalk_1.default.red(`⚠ base locale file not found: ${baseFile} (baseLang="${baseLang}")`));
+        return;
+    }
+    // ✅ 실제 base JSON 파일 (nested 구조)
+    const baseNested = JSON.parse(fs_1.default.readFileSync(baseFile, "utf-8"));
+    const baseFlat = flattenLocaleObject(baseNested);
+    const baseKeys = Object.keys(baseFlat);
+    const targets = targetLocale ? [targetLocale] : Object.keys(locales);
+    console.log(chalk_1.default.magenta(`\n🧱 Fixing structure to match "${baseLang}" (dryRun=${dryRun})\n`));
+    targets.forEach((lang) => {
+        const file = path_1.default.join(localesDir, `${lang}.json`);
+        if (!fs_1.default.existsSync(file))
+            return;
+        let obj = JSON.parse(fs_1.default.readFileSync(file, "utf-8"));
+        // 현재 locale도 실제 파일 기준(nested)으로 flatten
+        const langFlat = flattenLocaleObject(obj);
+        const langKeys = Object.keys(langFlat);
+        const extra = langKeys.filter((k) => !baseKeys.includes(k));
+        const missing = baseKeys.filter((k) => !langKeys.includes(k));
+        let deleted = deleteUnusedKeysFromObject(obj, extra);
+        let created = createMissingKeysInObject(obj, missing, "");
+        pruneEmptyObjects(obj);
+        // ✅ 여기에서 baseNested 기준으로 key 순서 맞춰 정렬
+        obj = sortLocaleByBase(baseNested, obj);
+        if (dryRun) {
+            console.log(chalk_1.default.gray(`[DRY-RUN] ${lang}: delete ${deleted}, create ${created}`));
+        }
+        else {
+            if (backup)
+                ensureBackup(file, lang, backupDir);
+            fs_1.default.writeFileSync(file, JSON.stringify(obj, null, 2));
+            console.log(chalk_1.default.green(`🏗 ${lang}: aligned (deleted ${deleted}, created ${created})`));
+        }
+    });
+}
+function sortLocaleByBase(base, target) {
+    if (typeof base !== "object" || base === null)
+        return target;
+    if (typeof target !== "object" || target === null)
+        return target;
+    const sorted = {};
+    Object.keys(base).forEach((key) => {
+        const baseVal = base[key];
+        const targetVal = target[key];
+        if (typeof baseVal === "object" && baseVal !== null) {
+            sorted[key] = sortLocaleByBase(baseVal, targetVal ?? {});
+        }
+        else {
+            sorted[key] = targetVal ?? "";
+        }
+    });
+    return sorted;
+}
+/* ---------------- HELPERS ---------------- */
+function pruneEmptyObjects(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return false;
+    for (const key of Object.keys(obj)) {
+        if (typeof obj[key] === "object") {
+            if (pruneEmptyObjects(obj[key]))
+                delete obj[key];
+        }
+    }
+    return Object.keys(obj).length === 0;
+}
+function ensureBackup(file, lang, dir) {
+    if (!fs_1.default.existsSync(dir))
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    fs_1.default.copyFileSync(file, path_1.default.join(dir, `${lang}.json`));
+}
+function deleteUnusedKeysFromObject(root, keys) {
+    let count = 0;
+    keys.forEach((k) => deletePath(root, k.split(".")) && count++);
+    return count;
+}
+function deletePath(obj, parts) {
+    const [h, ...r] = parts;
+    if (!(h in obj))
+        return false;
+    if (!r.length) {
+        delete obj[h];
+        return true;
+    }
+    return deletePath(obj[h], r);
+}
+function createMissingKeysInObject(root, keys, value) {
+    let count = 0;
+    keys.forEach((k) => createPath(root, k.split("."), value) && count++);
+    return count;
+}
+function createPath(obj, parts, value) {
+    const [h, ...r] = parts;
+    if (!h)
+        return false;
+    if (!r.length) {
+        if (obj[h] === undefined) {
+            obj[h] = value;
+            return true;
+        }
+        return false;
+    }
+    if (typeof obj[h] !== "object" || obj[h] === null)
+        obj[h] = {};
+    return createPath(obj[h], r, value);
+}
+function askForConfirmation(q) {
+    return new Promise((resolve) => {
+        const rl = readline_1.default.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        rl.question(`${q} (y/N) `, (a) => {
+            rl.close();
+            a = a.trim().toLowerCase();
+            resolve(a === "y" || a === "yes");
+        });
+    });
+}

package/dist/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const scan_1 = require("./commands/scan");
+const import_1 = require("./commands/import");
+const program = new commander_1.Command();
+program.name("i18n-mcp").description("i18n automation tool").version("0.0.1");
+(0, scan_1.scanCommand)(program);
+(0, import_1.importCommand)(program);
+program.parse();

package/dist/utils/checkGh.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureGhInstalled = ensureGhInstalled;
+const child_process_1 = require("child_process");
+function ensureGhInstalled() {
+    try {
+        (0, child_process_1.execSync)("gh --version", { stdio: "ignore" });
+    }
+    catch {
+        throw new Error("GitHub CLI (gh) is not installed or not available in PATH.\n" +
+            "Install it from: https://cli.github.com/\n" +
+            "Then run: gh auth login");
+    }
+}

package/dist/utils/createPullRequest.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPullRequest = createPullRequest;
+const child_process_1 = require("child_process");
+function createPullRequest({ title, body, draft, branch, }) {
+    try {
+        (0, child_process_1.execSync)(`git checkout -b ${branch}`, { stdio: "inherit" });
+        (0, child_process_1.execSync)(`git add locales`, { stdio: "inherit" });
+        (0, child_process_1.execSync)(`git commit -m "${title}"`, { stdio: "inherit" });
+        let cmd = `gh pr create --title "${title}" --body "${body}"`;
+        if (draft)
+            cmd += " --draft";
+        (0, child_process_1.execSync)(cmd, { stdio: "inherit" });
+    }
+    catch (e) {
+        throw new Error("Failed to create PR. Make sure git and gh CLI are properly set up.");
+    }
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@ddongule/i18n-cli",
+  "version": "1.0.0",
+  "private": false,
+  "bin": {
+    "i18n": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "chalk": "^5",
+    "commander": "^11",
+    "i18n-core": "workspace:*"
+  }
+}