@inline-i18n-multi/cli 0.6.0 → 0.8.0

package/README.md

@@ -30,6 +30,68 @@ Find missing translations for specific locales:
 npx inline-i18n check --locales en,ko,ja
 ```
 
+### Validate Translations
+
+Check translation consistency across locales:
+
+```bash
+npx inline-i18n validate
+npx inline-i18n validate --locales en ko ja
+npx inline-i18n validate --unused
+```
+
+### Detect Unused Keys (v0.8.0)
+
+Find translation keys defined in dictionaries but never referenced in source code:
+
+```bash
+npx inline-i18n validate --unused
+```
+
+Example output:
+
+```
+Found 2 unused translation key(s):
+
+  - old.feature.title
+    defined in src/locales.ts:5
+  - deprecated.banner
+    defined in src/locales.ts:12
+```
+
+### Strict Mode (v0.7.0)
+
+Enable ICU type consistency checking with `--strict`:
+
+```bash
+npx inline-i18n validate --strict
+```
+
+Strict mode detects:
+- **Variable name mismatches** — different variable names across locales
+- **ICU type mismatches** — inconsistent ICU types (e.g., `plural` in one locale, `select` in another)
+
+Example output:
+
+```
+ICU type mismatch between translations
+  src/Header.tsx:12
+    en: {count, plural, one {# item} other {# items}}
+    ko: {count, select, male {He} female {She}}
+
+Found 1 issue(s)
+```
+
+### Generate Types (v0.8.0)
+
+Generate TypeScript type definitions from your translation keys for type-safe `t()` calls:
+
+```bash
+npx inline-i18n typegen --output src/i18n.d.ts
+```
+
+This scans your dictionaries and produces a `.d.ts` file with autocomplete-ready key types.
+
 ### Generate Report
 
 Generate a translation coverage report:
@@ -45,6 +107,8 @@ npx inline-i18n report
 --output, -o    Output file path
 --locales, -l   Comma-separated list of locales
 --format, -f    Output format: json, csv (default: json)
+--strict        Enable strict mode (ICU type consistency check)
+--unused        Detect unused translation keys (validate command)
 ```
 
 ## Documentation

package/dist/bin.js

@@ -71,6 +71,16 @@ function extractVariables(text) {
   if (!matches) return [];
   return matches.map((m) => m.slice(1, -1));
 }
+var ICU_TYPE_PATTERN = /\{(\w+),\s*(\w+)/g;
+function extractICUTypes(text) {
+  const types = [];
+  let match;
+  ICU_TYPE_PATTERN.lastIndex = 0;
+  while ((match = ICU_TYPE_PATTERN.exec(text)) !== null) {
+    types.push({ variable: match[1], type: match[2] });
+  }
+  return types;
+}
 function parseFile(filePath) {
   const entries = [];
   const code = fs.readFileSync(filePath, "utf-8");
@@ -106,6 +116,11 @@ function parseFile(filePath) {
           if (prop.type === "ObjectProperty" && prop.key.type === "Identifier" && prop.value.type === "StringLiteral") {
             entry.translations[prop.key.name] = prop.value.value;
             entry.variables.push(...extractVariables(prop.value.value));
+            const types = extractICUTypes(prop.value.value);
+            if (types.length > 0) {
+              if (!entry.icuTypes) entry.icuTypes = {};
+              entry.icuTypes[prop.key.name] = types;
+            }
           }
         }
       } else if (args[0]?.type === "StringLiteral" && args[1]?.type === "StringLiteral") {
@@ -114,6 +129,16 @@ function parseFile(filePath) {
         entry.translations[lang2] = args[1].value;
         entry.variables.push(...extractVariables(args[0].value));
         entry.variables.push(...extractVariables(args[1].value));
+        const types1 = extractICUTypes(args[0].value);
+        if (types1.length > 0) {
+          if (!entry.icuTypes) entry.icuTypes = {};
+          entry.icuTypes[lang1] = types1;
+        }
+        const types2 = extractICUTypes(args[1].value);
+        if (types2.length > 0) {
+          if (!entry.icuTypes) entry.icuTypes = {};
+          entry.icuTypes[lang2] = types2;
+        }
       }
       entry.variables = [...new Set(entry.variables)];
       if (Object.keys(entry.translations).length > 0) {
@@ -123,6 +148,125 @@ function parseFile(filePath) {
   });
   return entries;
 }
+function flattenObjectKeys(node, prefix = "") {
+  const keys = [];
+  if (node.type !== "ObjectExpression" || !node.properties) return keys;
+  for (const prop of node.properties) {
+    if (prop.type !== "ObjectProperty") continue;
+    let propName;
+    if (prop.key.type === "Identifier") propName = prop.key.name;
+    else if (prop.key.type === "StringLiteral") propName = prop.key.value;
+    if (!propName) continue;
+    const fullKey = prefix ? `${prefix}.${propName}` : propName;
+    if (prop.value.type === "StringLiteral") {
+      keys.push(fullKey);
+    } else if (prop.value.type === "ObjectExpression") {
+      keys.push(...flattenObjectKeys(prop.value, fullKey));
+    }
+  }
+  return keys;
+}
+function parseDictionaryKeys(filePath) {
+  const entries = [];
+  const code = fs.readFileSync(filePath, "utf-8");
+  let ast;
+  try {
+    ast = (0, import_parser.parse)(code, {
+      sourceType: "module",
+      plugins: ["typescript", "jsx"]
+    });
+  } catch {
+    return [];
+  }
+  (0, import_traverse.default)(ast, {
+    CallExpression(nodePath) {
+      const { node } = nodePath;
+      const { callee } = node;
+      if (callee.type !== "Identifier" || callee.name !== "loadDictionaries") return;
+      const args = node.arguments;
+      const loc = node.loc;
+      if (!loc || !args[0] || args[0].type !== "ObjectExpression") return;
+      let namespace = "default";
+      if (args[1]?.type === "StringLiteral") {
+        namespace = args[1].value;
+      }
+      const dictObj = args[0];
+      const allKeys = /* @__PURE__ */ new Set();
+      for (const localeProp of dictObj.properties) {
+        if (localeProp.type !== "ObjectProperty") continue;
+        if (localeProp.value.type !== "ObjectExpression") continue;
+        const localeKeys = flattenObjectKeys(localeProp.value);
+        for (const key of localeKeys) {
+          allKeys.add(key);
+        }
+      }
+      if (allKeys.size > 0) {
+        entries.push({
+          file: filePath,
+          line: loc.start.line,
+          namespace,
+          keys: [...allKeys]
+        });
+      }
+    }
+  });
+  return entries;
+}
+function parseTCalls(filePath) {
+  const entries = [];
+  const code = fs.readFileSync(filePath, "utf-8");
+  let ast;
+  try {
+    ast = (0, import_parser.parse)(code, {
+      sourceType: "module",
+      plugins: ["typescript", "jsx"]
+    });
+  } catch {
+    return [];
+  }
+  (0, import_traverse.default)(ast, {
+    CallExpression(nodePath) {
+      const { node } = nodePath;
+      const { callee } = node;
+      if (callee.type !== "Identifier" || callee.name !== "t") return;
+      const args = node.arguments;
+      const loc = node.loc;
+      if (!loc || !args[0] || args[0].type !== "StringLiteral") return;
+      entries.push({
+        file: filePath,
+        line: loc.start.line,
+        key: args[0].value
+      });
+    }
+  });
+  return entries;
+}
+async function extractProjectDictionaryKeys(options = {}) {
+  const {
+    cwd = process.cwd(),
+    include = ["**/*.{ts,tsx,js,jsx}"],
+    exclude = ["**/node_modules/**", "**/dist/**", "**/.next/**"]
+  } = options;
+  const files = await (0, import_fast_glob.default)(include, { cwd, ignore: exclude, absolute: true });
+  const allEntries = [];
+  for (const file of files) {
+    allEntries.push(...parseDictionaryKeys(file));
+  }
+  return allEntries;
+}
+async function extractProjectTCalls(options = {}) {
+  const {
+    cwd = process.cwd(),
+    include = ["**/*.{ts,tsx,js,jsx}"],
+    exclude = ["**/node_modules/**", "**/dist/**", "**/.next/**"]
+  } = options;
+  const files = await (0, import_fast_glob.default)(include, { cwd, ignore: exclude, absolute: true });
+  const allEntries = [];
+  for (const file of files) {
+    allEntries.push(...parseTCalls(file));
+  }
+  return allEntries;
+}
 async function parseProject(options = {}) {
   const {
     cwd = process.cwd(),
@@ -179,10 +323,131 @@ Searching for: "${query}"
 }
 
 // src/commands/validate.ts
+var import_chalk3 = __toESM(require("chalk"));
+
+// src/commands/unused.ts
 var import_chalk2 = __toESM(require("chalk"));
+var PLURAL_SUFFIXES = ["_zero", "_one", "_two", "_few", "_many", "_other"];
+async function unused(options = {}) {
+  const { cwd } = options;
+  console.log(import_chalk2.default.blue("\nDetecting unused translations...\n"));
+  const dictEntries = await extractProjectDictionaryKeys({ cwd });
+  const tCalls = await extractProjectTCalls({ cwd });
+  const usedKeys = /* @__PURE__ */ new Set();
+  for (const call of tCalls) {
+    usedKeys.add(call.key);
+    if (!call.key.includes(":")) {
+      usedKeys.add(call.key);
+    }
+  }
+  const unusedKeys = [];
+  for (const entry of dictEntries) {
+    for (const key of entry.keys) {
+      const fullKey = entry.namespace === "default" ? key : `${entry.namespace}:${key}`;
+      if (usedKeys.has(fullKey)) continue;
+      let isPluralVariant = false;
+      for (const suffix of PLURAL_SUFFIXES) {
+        if (key.endsWith(suffix)) {
+          const baseKey = key.slice(0, -suffix.length);
+          const fullBaseKey = entry.namespace === "default" ? baseKey : `${entry.namespace}:${baseKey}`;
+          if (usedKeys.has(fullBaseKey)) {
+            isPluralVariant = true;
+            break;
+          }
+        }
+      }
+      if (isPluralVariant) continue;
+      unusedKeys.push({
+        namespace: entry.namespace,
+        key: fullKey,
+        definedIn: entry.file,
+        line: entry.line
+      });
+    }
+  }
+  if (unusedKeys.length === 0) {
+    const totalKeys = dictEntries.reduce((sum, e) => sum + e.keys.length, 0);
+    console.log(import_chalk2.default.green("No unused translations found!\n"));
+    console.log(import_chalk2.default.gray(`Checked ${totalKeys} dictionary key(s) against ${tCalls.length} t() call(s)`));
+    return { unusedKeys };
+  }
+  console.log(import_chalk2.default.yellow(`Found ${unusedKeys.length} unused translation key(s):
+`));
+  for (const item of unusedKeys) {
+    const relativePath = item.definedIn.replace(process.cwd() + "/", "");
+    console.log(`  ${import_chalk2.default.red("-")} ${import_chalk2.default.cyan(item.key)}`);
+    console.log(import_chalk2.default.gray(`    defined in ${relativePath}:${item.line}`));
+  }
+  console.log();
+  return { unusedKeys };
+}
+
+// src/commands/validate.ts
+function checkVariableConsistency(entry) {
+  const varsByLocale = [];
+  for (const [locale, text] of Object.entries(entry.translations)) {
+    const matches = text.match(/\{(\w+)\}/g) || [];
+    const varNames = [...new Set(matches.map((v) => v.slice(1, -1)))].sort();
+    varsByLocale.push({ locale, vars: varNames });
+  }
+  if (varsByLocale.length < 2) return null;
+  const reference = varsByLocale[0];
+  const details = [];
+  for (let i = 1; i < varsByLocale.length; i++) {
+    const current = varsByLocale[i];
+    const refSet = new Set(reference.vars);
+    const curSet = new Set(current.vars);
+    const onlyInRef = reference.vars.filter((v) => !curSet.has(v));
+    const onlyInCur = current.vars.filter((v) => !refSet.has(v));
+    if (onlyInRef.length > 0) {
+      details.push(
+        `${reference.locale} has {${onlyInRef.join("}, {")}} missing in ${current.locale}`
+      );
+    }
+    if (onlyInCur.length > 0) {
+      details.push(
+        `${current.locale} has {${onlyInCur.join("}, {")}} missing in ${reference.locale}`
+      );
+    }
+  }
+  if (details.length === 0) return null;
+  return {
+    type: "variable_mismatch",
+    message: "Variable mismatch between translations",
+    entries: [entry],
+    details
+  };
+}
+function checkICUTypeConsistency(entry) {
+  if (!entry.icuTypes) return null;
+  const locales = Object.keys(entry.icuTypes);
+  if (locales.length < 2) return null;
+  const details = [];
+  const reference = locales[0];
+  const refTypes = entry.icuTypes[reference];
+  for (let i = 1; i < locales.length; i++) {
+    const locale = locales[i];
+    const curTypes = entry.icuTypes[locale];
+    for (const refType of refTypes) {
+      const match = curTypes.find((t) => t.variable === refType.variable);
+      if (match && match.type !== refType.type) {
+        details.push(
+          `{${refType.variable}} is "${refType.type}" in ${reference} but "${match.type}" in ${locale}`
+        );
+      }
+    }
+  }
+  if (details.length === 0) return null;
+  return {
+    type: "icu_type_mismatch",
+    message: "ICU type mismatch between translations",
+    entries: [entry],
+    details
+  };
+}
 async function validate(options = {}) {
-  const { cwd, locales } = options;
-  console.log(import_chalk2.default.blue("\nValidating translations...\n"));
+  const { cwd, locales, strict, unused: checkUnused } = options;
+  console.log(import_chalk3.default.blue("\nValidating translations...\n"));
   const entries = await parseProject({ cwd });
   const issues = [];
   const groups = /* @__PURE__ */ new Map();
@@ -218,49 +483,62 @@ async function validate(options = {}) {
     }
   }
   for (const entry of entries) {
-    const variableSets = Object.entries(entry.translations).map(([locale, text]) => {
-      const vars = text.match(/\{(\w+)\}/g) || [];
-      return { locale, vars: vars.sort().join(",") };
-    });
-    const uniqueVarSets = [...new Set(variableSets.map((v) => v.vars))];
-    if (uniqueVarSets.length > 1) {
-      issues.push({
-        type: "variable_mismatch",
-        message: "Variable mismatch between translations",
-        entries: [entry]
-      });
+    const issue = checkVariableConsistency(entry);
+    if (issue) issues.push(issue);
+  }
+  if (strict) {
+    for (const entry of entries) {
+      const issue = checkICUTypeConsistency(entry);
+      if (issue) issues.push(issue);
     }
   }
-  if (issues.length === 0) {
-    console.log(import_chalk2.default.green("\u2705 All translations are valid!\n"));
-    console.log(import_chalk2.default.gray(`Checked ${entries.length} translation(s)`));
+  let unusedCount = 0;
+  if (checkUnused) {
+    const result = await unused({ cwd });
+    unusedCount = result.unusedKeys.length;
+  }
+  if (issues.length === 0 && unusedCount === 0) {
+    console.log(import_chalk3.default.green("All translations are valid!\n"));
+    console.log(import_chalk3.default.gray(`Checked ${entries.length} translation(s)`));
+    if (strict) {
+      console.log(import_chalk3.default.gray("(strict mode enabled)"));
+    }
+    if (checkUnused) {
+      console.log(import_chalk3.default.gray("(unused key detection enabled)"));
+    }
     return;
   }
-  console.log(import_chalk2.default.red(`\u274C Found ${issues.length} issue(s):
+  console.log(import_chalk3.default.red(`Found ${issues.length} issue(s):
 `));
   for (const issue of issues) {
-    const icon = issue.type === "inconsistent" ? "\u26A0\uFE0F" : issue.type === "missing" ? "\u{1F4ED}" : "\u{1F500}";
-    console.log(`${icon}  ${import_chalk2.default.yellow(issue.message)}`);
+    console.log(`  ${import_chalk3.default.yellow(issue.message)}`);
     for (const entry of issue.entries) {
       const relativePath = entry.file.replace(process.cwd() + "/", "");
-      console.log(import_chalk2.default.gray(`   ${relativePath}:${entry.line}`));
+      console.log(import_chalk3.default.gray(`   ${relativePath}:${entry.line}`));
       for (const [locale, text] of Object.entries(entry.translations)) {
-        console.log(`     ${import_chalk2.default.cyan(locale)}: ${text}`);
+        console.log(`     ${import_chalk3.default.cyan(locale)}: ${text}`);
+      }
+    }
+    if (issue.details && issue.details.length > 0) {
+      for (const detail of issue.details) {
+        console.log(import_chalk3.default.gray(`     \u2192 ${detail}`));
       }
     }
     console.log();
   }
-  process.exit(1);
+  if (issues.length > 0 || unusedCount > 0) {
+    process.exit(1);
+  }
 }
 
 // src/commands/coverage.ts
-var import_chalk3 = __toESM(require("chalk"));
+var import_chalk4 = __toESM(require("chalk"));
 async function coverage(options) {
   const { cwd, locales } = options;
-  console.log(import_chalk3.default.blue("\nAnalyzing translation coverage...\n"));
+  console.log(import_chalk4.default.blue("\nAnalyzing translation coverage...\n"));
   const entries = await parseProject({ cwd });
   if (entries.length === 0) {
-    console.log(import_chalk3.default.yellow("No translations found."));
+    console.log(import_chalk4.default.yellow("No translations found."));
     return;
   }
   const coverageData = [];
@@ -279,20 +557,20 @@ async function coverage(options) {
       percentage
     });
   }
-  console.log(import_chalk3.default.bold("Translation Coverage:\n"));
+  console.log(import_chalk4.default.bold("Translation Coverage:\n"));
   const maxLocaleLen = Math.max(...locales.map((l) => l.length), 6);
   console.log(
-    import_chalk3.default.gray(
+    import_chalk4.default.gray(
       `${"Locale".padEnd(maxLocaleLen)}  ${"Coverage".padStart(10)}  ${"Translated".padStart(12)}`
     )
   );
-  console.log(import_chalk3.default.gray("\u2500".repeat(maxLocaleLen + 26)));
+  console.log(import_chalk4.default.gray("\u2500".repeat(maxLocaleLen + 26)));
   for (const data of coverageData) {
-    const color = data.percentage === 100 ? import_chalk3.default.green : data.percentage >= 80 ? import_chalk3.default.yellow : import_chalk3.default.red;
+    const color = data.percentage === 100 ? import_chalk4.default.green : data.percentage >= 80 ? import_chalk4.default.yellow : import_chalk4.default.red;
     const bar = createProgressBar(data.percentage, 10);
     const percentStr = `${data.percentage}%`.padStart(4);
     console.log(
-      `${data.locale.padEnd(maxLocaleLen)}  ${color(bar)} ${color(percentStr)}  ${import_chalk3.default.gray(`${data.translated}/${data.total}`)}`
+      `${data.locale.padEnd(maxLocaleLen)}  ${color(bar)} ${color(percentStr)}  ${import_chalk4.default.gray(`${data.translated}/${data.total}`)}`
     );
   }
   console.log();
@@ -300,9 +578,9 @@ async function coverage(options) {
   const partiallyCovered = coverageData.filter((d) => d.percentage > 0 && d.percentage < 100).length;
   const notCovered = coverageData.filter((d) => d.percentage === 0).length;
   if (fullyCovered === locales.length) {
-    console.log(import_chalk3.default.green("\u2705 All locales are fully translated!"));
+    console.log(import_chalk4.default.green("All locales are fully translated!"));
   } else {
-    console.log(import_chalk3.default.gray(`Full: ${fullyCovered}, Partial: ${partiallyCovered}, Empty: ${notCovered}`));
+    console.log(import_chalk4.default.gray(`Full: ${fullyCovered}, Partial: ${partiallyCovered}, Empty: ${notCovered}`));
   }
 }
 function createProgressBar(percentage, width) {
@@ -311,17 +589,88 @@ function createProgressBar(percentage, width) {
   return "\u2588".repeat(filled) + "\u2591".repeat(empty);
 }
 
+// src/commands/typegen.ts
+var fs2 = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var import_chalk5 = __toESM(require("chalk"));
+var PLURAL_SUFFIXES2 = ["_zero", "_one", "_two", "_few", "_many", "_other"];
+async function typegen(options = {}) {
+  const { cwd, output = "src/i18n.d.ts" } = options;
+  console.log(import_chalk5.default.blue("\nGenerating TypeScript types...\n"));
+  const dictEntries = await extractProjectDictionaryKeys({ cwd });
+  const allKeys = /* @__PURE__ */ new Set();
+  for (const entry of dictEntries) {
+    for (const key of entry.keys) {
+      const fullKey = entry.namespace === "default" ? key : `${entry.namespace}:${key}`;
+      allKeys.add(fullKey);
+      for (const suffix of PLURAL_SUFFIXES2) {
+        if (key.endsWith(suffix)) {
+          const baseKey = key.slice(0, -suffix.length);
+          const fullBaseKey = entry.namespace === "default" ? baseKey : `${entry.namespace}:${baseKey}`;
+          allKeys.add(fullBaseKey);
+        }
+      }
+    }
+  }
+  if (allKeys.size === 0) {
+    console.log(import_chalk5.default.yellow("No dictionary keys found. Make sure loadDictionaries() calls are present."));
+    return;
+  }
+  const sortedKeys = [...allKeys].sort();
+  const keyUnion = sortedKeys.map((k) => `    | '${k}'`).join("\n");
+  const content = `// Auto-generated by inline-i18n typegen
+// Do not edit manually. Re-run: npx inline-i18n typegen
+
+import 'inline-i18n-multi'
+
+declare module 'inline-i18n-multi' {
+  export type TranslationKey =
+${keyUnion}
+
+  export function t(
+    key: TranslationKey,
+    vars?: TranslationVars,
+    locale?: string
+  ): string
+
+  export function hasTranslation(
+    key: TranslationKey,
+    locale?: string
+  ): boolean
+}
+`;
+  const outputPath = path.resolve(cwd || process.cwd(), output);
+  const outputDir = path.dirname(outputPath);
+  if (!fs2.existsSync(outputDir)) {
+    fs2.mkdirSync(outputDir, { recursive: true });
+  }
+  fs2.writeFileSync(outputPath, content, "utf-8");
+  console.log(import_chalk5.default.green(`Generated ${sortedKeys.length} translation key types`));
+  console.log(import_chalk5.default.gray(`Output: ${outputPath}
+`));
+  const sample = sortedKeys.slice(0, 5);
+  for (const key of sample) {
+    console.log(`  ${import_chalk5.default.cyan(key)}`);
+  }
+  if (sortedKeys.length > 5) {
+    console.log(import_chalk5.default.gray(`  ... and ${sortedKeys.length - 5} more`));
+  }
+}
+
 // src/bin.ts
 var program = new import_commander.Command();
-program.name("inline-i18n").description("CLI tools for inline-i18n-multi").version("0.1.0");
+program.name("inline-i18n").description("CLI tools for inline-i18n-multi").version("0.8.0");
 program.command("find <query>").description("Find translations containing the query text").option("-c, --cwd <path>", "Working directory").action(async (query, options) => {
   await find({ query, cwd: options.cwd });
 });
-program.command("validate").description("Validate translation consistency").option("-c, --cwd <path>", "Working directory").option("-l, --locales <locales...>", "Required locales to check").action(async (options) => {
+program.command("validate").description("Validate translation consistency").option("-c, --cwd <path>", "Working directory").option("-l, --locales <locales...>", "Required locales to check").option("-s, --strict", "Enable strict mode (ICU type consistency check)").option("-u, --unused", "Detect unused dictionary keys").action(async (options) => {
   await validate(options);
 });
 program.command("coverage").description("Show translation coverage by locale").option("-c, --cwd <path>", "Working directory").option("-l, --locales <locales...>", "Locales to check", ["ko", "en"]).action(async (options) => {
   await coverage(options);
 });
+program.command("typegen").description("Generate TypeScript types for translation keys").option("-c, --cwd <path>", "Working directory").option("-o, --output <path>", "Output file path", "src/i18n.d.ts").action(async (options) => {
+  await typegen(options);
+});
 program.parse();
 //# sourceMappingURL=bin.js.map