@kopynator/cli 1.5.1 → 1.6.0

package/README.md

@@ -3,7 +3,13 @@
 The official Command Line Interface for [Kopynator](https://kopynator.com).
 Manage your internationalization workflow directly from your terminal.
 
-## Installation
+**Languages / Idiomas:** [English](#english) · [Español](#español)
+
+---
+
+## English
+
+### Installation
 
 You don't need to install it globally! We recommend using `npx` for the latest version:
 
@@ -17,33 +23,67 @@ If you prefer a global installation:
 npm install -g @kopynator/cli
 ```
 
-## Commands
+### Commands
 
-### 1. Initialize
-Sets up Kopynator in your project. Creates the configuration file and guides you verify the setup.
+| Command | What it does |
+| --- | --- |
+| [`init`](#1-init) | Sets up Kopynator in your project (framework detection, config injection). |
+| [`check`](#2-check) | Validates local translation files: JSON syntax, broken references, duplicate global keys. |
+| [`sync`](#3-sync) | Downloads translations from Kopynator Cloud into local JSON files. |
+| [`upload`](#4-upload) | Uploads a local JSON file to Kopynator Cloud. |
+| [`limits`](#5-limits) | Shows your plan's limits and current usage. |
+| [`help`](#6-help) | Prints help for all commands. |
+
+#### 1. `init`
+Sets up Kopynator in your project. Auto-detects your framework (Angular, React, Vue, React Native, Ionic) and either injects `provideKopynator(...)` directly into your app config, or falls back to creating a `kopynator.config.json` file. Interactively asks for your default locale and supported languages.
 
 ```bash
 npx -y @kopynator/cli init
 ```
 
-### 2. Check / Validate
-Validates your local JSON translation files for syntax errors. Useful for CI/CD pipelines.
+#### 2. `check`
+Validates your local translation files. Three things, in order:
+
+1. **JSON syntax** — every locale file must parse.
+2. **Broken references** — translation keys used in your source code (`| kopy`, `[kopy]="'...'"`, `.translate()`/`.t()`) that don't exist in *any* locale file.
+3. **Duplicate global keys** — keys whose value duplicates an existing `global.*` key, so your team converges on one canonical key instead of silently drifting into copies.
+
+Useful for CI/CD pipelines and pre-commit hooks — it exits with a non-zero code on failure.
 
 ```bash
 npx -y @kopynator/cli check
 ```
 
-### 3. Sync
-Downloads translations from the Kopynator Cloud and saves them as local JSON files (e.g. `src/assets/i18n/en.json`).
+Flags:
+- `--base-ref <ref>` — git ref to diff against when deciding which duplicate keys are *new* (default: `master`). Duplicates that already existed at that ref aren't re-flagged, so adopting `check` doesn't force you to clean up all pre-existing debt at once.
+- `--update-baseline` — accepts every currently-missing key as backlog, writing `kopynator.i18n-baseline.json`. From then on, `check` only fails on keys that go missing *after* that point.
+- `--all` — lists every missing key (baseline + new), tagging which ones are already accepted.
+
+Two optional project-root config files:
+- `kopynator.i18n-baseline.json` — `{ "keys": [...] }`, written automatically by `--update-baseline`.
+- `kopynator.i18n-safelist.json` — `{ "dynamicPrefixes": ["status."] }`. Protects key families built dynamically at runtime (e.g. `` `status.${s}` ``) from being flagged as missing. You can also declare a prefix inline, right next to the code that uses it, with a comment: `// kopynator-keys: status.*`.
+
+Set `KOPYNATOR_I18N_SKIP=1` to bypass the check entirely (e.g. an emergency commit).
+
+```bash
+# CI example: only fail on regressions since main
+npx -y @kopynator/cli check --base-ref origin/main
+
+# Adopt the check on a legacy project without a big-bang cleanup
+npx -y @kopynator/cli check --update-baseline
+```
+
+#### 3. `sync`
+Downloads translations from the Kopynator Cloud and saves them as local JSON files (e.g. `src/assets/i18n/en.json`). On first run it asks how you want the output formatted (nested vs. flat keys, pretty-print, indentation) and remembers your choice in `kopynator.sync.config.json`.
 
 ```bash
 npx -y @kopynator/cli sync
 ```
 
-### 4. Upload
-Uploads a JSON translation file to the Kopynator Cloud. Keys are merged/updated for the given language. Use the same API key (token) as in your app or `kopynator.config.json`.
+#### 4. `upload`
+Uploads a JSON translation file to the Kopynator Cloud. Keys are merged/updated for the given language. Uses the same API key (token) as your app or `kopynator.config.json`.
 
-**Project:** The target project is determined by the token. Each token is linked to one project when created in [Dashboard → Settings → Tokens](https://www.kopynator.com/dashboard/settings/tokens). To upload to a different project, use that project’s token (e.g. another `apiKey` in `kopynator.config.json` or a separate config).
+**Project:** the target project is determined by the token. Each token is linked to one project when created in [Dashboard → Settings → Tokens](https://www.kopynator.com/dashboard/settings/tokens). To upload to a different project, use that project's token.
 
 ```bash
 # Language inferred from filename (es.json → es)
@@ -55,8 +95,140 @@ npx -y @kopynator/cli upload --file=locales/en.json --lang=en
 
 After uploading, run `sync` to download the latest state from the cloud if needed.
 
-## Configuration
-The `init` command creates a `kopynator.config.json` file in your root:
+#### 5. `limits`
+Shows your current plan, and per-organization limits and usage (projects, translation keys, members). Reads the same API key resolution as `sync`/`upload` (`kopynator.config.json`, `app.config.ts`/`app.module.ts`, or `KOPYNATOR_API_KEY`).
+
+```bash
+npx -y @kopynator/cli limits
+```
+
+#### 6. `help`
+Prints help for every command.
+
+```bash
+npx -y @kopynator/cli help
+```
+
+### Configuration
+The `init` command creates a `kopynator.config.json` file in your root (used as a fallback when it can't inject config directly into your app):
+
+```json
+{
+  "apiKey": "YOUR_API_KEY",
+  "defaultLocale": "en",
+  "languages": ["en", "es"],
+  "mode": "local"
+}
+```
+
+For CI environments without a config file, set `KOPYNATOR_API_KEY` (and optionally `KOPYNATOR_BASE_URL`) instead.
+
+---
+
+## Español
+
+### Instalación
+
+No hace falta instalarlo globalmente. Recomendamos usar `npx` para tener siempre la última versión:
+
+```bash
+npx -y @kopynator/cli <comando>
+```
+
+Si prefieres instalarlo de forma global:
+
+```bash
+npm install -g @kopynator/cli
+```
+
+### Comandos
+
+| Comando | Qué hace |
+| --- | --- |
+| [`init`](#1-init-1) | Configura Kopynator en tu proyecto (detecta el framework e inyecta la configuración). |
+| [`check`](#2-check-1) | Valida los ficheros de traducción locales: sintaxis JSON, referencias rotas, claves globales duplicadas. |
+| [`sync`](#3-sync-1) | Descarga las traducciones de Kopynator Cloud a ficheros JSON locales. |
+| [`upload`](#4-upload-1) | Sube un fichero JSON local a Kopynator Cloud. |
+| [`limits`](#5-limits-1) | Muestra los límites de tu plan y el uso actual. |
+| [`help`](#6-help-1) | Muestra la ayuda de todos los comandos. |
+
+#### 1. `init`
+Configura Kopynator en tu proyecto. Detecta automáticamente el framework (Angular, React, Vue, React Native, Ionic) e inyecta `provideKopynator(...)` directamente en la configuración de tu app, o crea un `kopynator.config.json` si no puede hacerlo. Te pregunta interactivamente el idioma por defecto y los idiomas que quieres soportar.
+
+```bash
+npx -y @kopynator/cli init
+```
+
+#### 2. `check`
+Valida tus ficheros de traducción locales. Comprueba tres cosas, en este orden:
+
+1. **Sintaxis JSON** — todos los ficheros de idioma deben parsear correctamente.
+2. **Referencias rotas** — claves de traducción usadas en tu código (`| kopy`, `[kopy]="'...'"`, `.translate()`/`.t()`) que no existen en *ningún* fichero de idioma.
+3. **Claves globales duplicadas** — claves cuyo valor duplica el de una clave `global.*` ya existente, para que el equipo converja en una única clave canónica en vez de ir creando copias sin darse cuenta.
+
+Útil en pipelines de CI/CD y hooks de pre-commit — termina con código de salida distinto de cero si falla.
+
+```bash
+npx -y @kopynator/cli check
+```
+
+Flags:
+- `--base-ref <ref>` — referencia git contra la que comparar para decidir qué claves duplicadas son *nuevas* (por defecto: `master`). Los duplicados que ya existían en esa referencia no se vuelven a marcar, así que adoptar `check` no obliga a limpiar toda la deuda existente de golpe.
+- `--update-baseline` — acepta todas las claves actualmente rotas como deuda pendiente, escribiendo `kopynator.i18n-baseline.json`. A partir de ahí, `check` solo falla con claves que se rompan *después* de ese punto.
+- `--all` — lista todas las claves rotas (aceptadas + nuevas), indicando cuáles ya están aceptadas.
+
+Dos ficheros de configuración opcionales en la raíz del proyecto:
+- `kopynator.i18n-baseline.json` — `{ "keys": [...] }`, se escribe automáticamente con `--update-baseline`.
+- `kopynator.i18n-safelist.json` — `{ "dynamicPrefixes": ["status."] }`. Protege familias de claves construidas dinámicamente en tiempo de ejecución (p. ej. `` `status.${s}` ``) para que no se marquen como rotas. También puedes declarar un prefijo en línea, junto al código que lo usa, con un comentario: `// kopynator-keys: status.*`.
+
+Define `KOPYNATOR_I18N_SKIP=1` para saltarte el check por completo (p. ej. un commit de emergencia).
+
+```bash
+# Ejemplo de CI: solo falla con regresiones desde main
+npx -y @kopynator/cli check --base-ref origin/main
+
+# Adoptar el check en un proyecto legacy sin limpieza masiva previa
+npx -y @kopynator/cli check --update-baseline
+```
+
+#### 3. `sync`
+Descarga las traducciones de Kopynator Cloud y las guarda como ficheros JSON locales (p. ej. `src/assets/i18n/en.json`). La primera vez te pregunta cómo quieres el formato de salida (claves anidadas o planas, formato legible, indentación) y recuerda tu elección en `kopynator.sync.config.json`.
+
+```bash
+npx -y @kopynator/cli sync
+```
+
+#### 4. `upload`
+Sube un fichero JSON de traducción a Kopynator Cloud. Las claves se fusionan/actualizan para el idioma indicado. Usa la misma API key (token) que tu app o `kopynator.config.json`.
+
+**Proyecto:** el proyecto de destino lo determina el token. Cada token está vinculado a un proyecto al crearse en [Dashboard → Settings → Tokens](https://www.kopynator.com/dashboard/settings/tokens). Para subir a otro proyecto, usa el token de ese proyecto.
+
+```bash
+# Idioma inferido del nombre del fichero (es.json → es)
+npx -y @kopynator/cli upload --file=src/assets/i18n/es.json
+
+# Idioma explícito
+npx -y @kopynator/cli upload --file=locales/en.json --lang=en
+```
+
+Después de subir, ejecuta `sync` si necesitas descargar el estado más reciente de la nube.
+
+#### 5. `limits`
+Muestra tu plan actual y los límites y uso por organización (proyectos, claves de traducción, miembros). Resuelve la API key igual que `sync`/`upload` (`kopynator.config.json`, `app.config.ts`/`app.module.ts`, o `KOPYNATOR_API_KEY`).
+
+```bash
+npx -y @kopynator/cli limits
+```
+
+#### 6. `help`
+Muestra la ayuda de todos los comandos.
+
+```bash
+npx -y @kopynator/cli help
+```
+
+### Configuración
+El comando `init` crea un fichero `kopynator.config.json` en la raíz (se usa como alternativa cuando no puede inyectar la configuración directamente en tu app):
 
 ```json
 {
@@ -66,3 +238,5 @@ The `init` command creates a `kopynator.config.json` file in your root:
   "mode": "local"
 }
 ```
+
+Para entornos de CI sin fichero de configuración, define `KOPYNATOR_API_KEY` (y opcionalmente `KOPYNATOR_BASE_URL`).

package/dist/index.js

@@ -270,81 +270,302 @@ async function initCommand() {
 
 // src/commands/check.ts
 var import_chalk2 = __toESM(require("chalk"));
+var import_fs4 = __toESM(require("fs"));
+var import_path4 = __toESM(require("path"));
+
+// src/lib/project.ts
 var import_fs2 = __toESM(require("fs"));
 var import_path2 = __toESM(require("path"));
-async function checkCommand() {
+function detectFramework() {
+  const angularJson = import_path2.default.join(process.cwd(), "angular.json");
+  const packageJson = import_path2.default.join(process.cwd(), "package.json");
+  if (import_fs2.default.existsSync(angularJson)) {
+    return "Angular";
+  }
+  if (import_fs2.default.existsSync(packageJson)) {
+    try {
+      const pkg = JSON.parse(import_fs2.default.readFileSync(packageJson, "utf-8"));
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+      if (deps["@angular/core"]) return "Angular";
+      if (deps["react"]) return "React";
+      if (deps["vue"]) return "Vue";
+    } catch (e) {
+    }
+  }
+  return "Other";
+}
+function getTranslationDir(framework) {
+  switch (framework) {
+    case "Angular":
+      return import_path2.default.join(process.cwd(), "src/assets/i18n");
+    case "React":
+    case "Vue":
+      return import_path2.default.join(process.cwd(), "public/locales");
+    default:
+      return import_path2.default.join(process.cwd(), "locales");
+  }
+}
+function getSourceRoot(framework) {
+  switch (framework) {
+    case "Angular":
+    case "React":
+    case "Vue":
+      return import_path2.default.join(process.cwd(), "src");
+    default:
+      return process.cwd();
+  }
+}
+
+// src/lib/i18n-guardian.ts
+var import_fs3 = __toESM(require("fs"));
+var import_path3 = __toESM(require("path"));
+var import_child_process = require("child_process");
+var SAFELIST_FILE = "kopynator.i18n-safelist.json";
+var BASELINE_FILE = "kopynator.i18n-baseline.json";
+var SOURCE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".html", ".vue"];
+var EXCLUDED_DIRS = /* @__PURE__ */ new Set(["node_modules", "dist", "build", ".git", ".angular", "coverage", ".next", ".nuxt", "out"]);
+var KEY = `[\\w.:-]+`;
+var USE_PATTERNS = [
+  // {{ 'key' | kopy }} — Angular pipe
+  { re: new RegExp(`(['"\`])(${KEY})\\1\\s*\\|\\s*kopy`, "g"), group: 2 },
+  // [kopy]="'key'" — Angular directive with a string literal binding
+  { re: new RegExp(`\\[kopy\\]\\s*=\\s*"'(${KEY})'"`, "g"), group: 1 },
+  // .translate('key') / .t('key') — @kopynator/core & @kopynator/react API
+  { re: new RegExp(`\\.(?:translate|t)\\(\\s*(['"\`])(${KEY})\\1`, "g"), group: 2 }
+];
+var MAGIC_RE = /kopynator-keys\s*:\s*([^\n]+)/g;
+function flatten(obj, prefix = "") {
+  const out = {};
+  for (const [k, v] of Object.entries(obj || {})) {
+    const key = prefix ? `${prefix}.${k}` : k;
+    if (v && typeof v === "object" && !Array.isArray(v)) {
+      Object.assign(out, flatten(v, key));
+    } else {
+      out[key] = String(v);
+    }
+  }
+  return out;
+}
+function walkSourceFiles(rootDir) {
+  if (!import_fs3.default.existsSync(rootDir)) return [];
+  const results = [];
+  function walk(dir) {
+    for (const entry of import_fs3.default.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (EXCLUDED_DIRS.has(entry.name)) continue;
+        walk(import_path3.default.join(dir, entry.name));
+      } else if (SOURCE_EXTENSIONS.includes(import_path3.default.extname(entry.name))) {
+        results.push(import_path3.default.join(dir, entry.name));
+      }
+    }
+  }
+  walk(rootDir);
+  return results;
+}
+function scanUsedKeys(files) {
+  const used = /* @__PURE__ */ new Map();
+  const dynamicPrefixes = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    const content = import_fs3.default.readFileSync(file, "utf-8");
+    for (const { re, group } of USE_PATTERNS) {
+      re.lastIndex = 0;
+      let match;
+      while (match = re.exec(content)) {
+        const key = match[group];
+        used.set(key, (used.get(key) || 0) + 1);
+      }
+    }
+    MAGIC_RE.lastIndex = 0;
+    let magicMatch;
+    while (magicMatch = MAGIC_RE.exec(content)) {
+      for (const raw of magicMatch[1].split(",")) {
+        const prefix = raw.trim().replace(/\*$/, "");
+        if (prefix) dynamicPrefixes.add(prefix);
+      }
+    }
+  }
+  return { used, dynamicPrefixes };
+}
+function loadSafelist(cwd) {
+  const p = import_path3.default.join(cwd, SAFELIST_FILE);
+  if (!import_fs3.default.existsSync(p)) return { dynamicPrefixes: [] };
+  try {
+    return JSON.parse(import_fs3.default.readFileSync(p, "utf-8"));
+  } catch {
+    return { dynamicPrefixes: [] };
+  }
+}
+function loadBaseline(cwd) {
+  const p = import_path3.default.join(cwd, BASELINE_FILE);
+  if (!import_fs3.default.existsSync(p)) return { keys: [] };
+  try {
+    const parsed = JSON.parse(import_fs3.default.readFileSync(p, "utf-8"));
+    return { keys: Array.isArray(parsed.keys) ? parsed.keys : [] };
+  } catch {
+    return { keys: [] };
+  }
+}
+function saveBaseline(cwd, keys) {
+  const p = import_path3.default.join(cwd, BASELINE_FILE);
+  import_fs3.default.writeFileSync(p, JSON.stringify({ keys: keys.sort() }, null, 2) + "\n");
+}
+function isProtectedByPrefix(key, prefixes) {
+  for (const prefix of prefixes) {
+    if (key.startsWith(prefix)) return true;
+  }
+  return false;
+}
+function gitShowFile(cwd, ref, relPath) {
+  try {
+    return (0, import_child_process.execFileSync)("git", ["show", `${ref}:${relPath}`], { cwd, stdio: ["pipe", "pipe", "ignore"] }).toString("utf-8");
+  } catch {
+    return null;
+  }
+}
+function slugify(value, maxLen = 40) {
+  return String(value).replace(/<[^>]+>/g, "").replace(/\{\{[^}]+\}\}/g, "").normalize("NFD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "").slice(0, maxLen) || "value";
+}
+function pickGlobal(keys) {
+  const globals = keys.filter((k) => k.startsWith("global."));
+  if (!globals.length) return null;
+  const segmented = globals.filter((k) => /^global\.(status|error|action)\./.test(k));
+  const pool = segmented.length ? segmented : globals;
+  return pool.reduce((shortest, k) => k.length < shortest.length ? k : shortest, pool[0]);
+}
+function findGlobalDuplicates(values, usedKeys) {
+  const byValue = /* @__PURE__ */ new Map();
+  for (const [key, value] of Object.entries(values)) {
+    const trimmed = value.trim();
+    if (!trimmed) continue;
+    const group = byValue.get(trimmed) || [];
+    group.push(key);
+    byValue.set(trimmed, group);
+  }
+  const findings = [];
+  for (const [value, keys] of byValue) {
+    if (keys.length < 2) continue;
+    const canonical = pickGlobal(keys) || `global.${slugify(value)}`;
+    for (const key of keys) {
+      if (key === canonical) continue;
+      if (!usedKeys.has(key)) continue;
+      findings.push({ key, value, canonical, canonicalIsNew: !keys.includes(canonical) });
+    }
+  }
+  return findings;
+}
+
+// src/commands/check.ts
+async function checkCommand(opts = {}) {
+  if (process.env.KOPYNATOR_I18N_SKIP === "1") {
+    console.log(import_chalk2.default.yellow("\u26A0\uFE0F  KOPYNATOR_I18N_SKIP=1 \u2014 skipping i18n check."));
+    return;
+  }
   console.log(import_chalk2.default.bold.blue("\n\u{1F50D} Validating JSON translation files...\n"));
-  const assetsDir = import_path2.default.join(process.cwd(), "src/assets/i18n");
-  if (!import_fs2.default.existsSync(assetsDir)) {
+  const cwd = process.cwd();
+  const framework = detectFramework();
+  const assetsDir = getTranslationDir(framework);
+  if (!import_fs4.default.existsSync(assetsDir)) {
     console.log(import_chalk2.default.red(`\u274C Could not find directory: ${assetsDir}`));
     console.log(import_chalk2.default.yellow("Make sure you are running this from your project root."));
-    return;
+    process.exit(1);
   }
-  const files = import_fs2.default.readdirSync(assetsDir).filter((f) => f.endsWith(".json"));
+  const files = import_fs4.default.readdirSync(assetsDir).filter((f) => f.endsWith(".json"));
   if (files.length === 0) {
-    console.log(import_chalk2.default.yellow("\u26A0\uFE0F No JSON files found in assets/i18n."));
+    console.log(import_chalk2.default.yellow("\u26A0\uFE0F No JSON files found in " + assetsDir + "."));
     return;
   }
-  let hasErrors = false;
+  let hasJsonErrors = false;
+  const parsed = {};
   files.forEach((file) => {
     try {
-      const content = import_fs2.default.readFileSync(import_path2.default.join(assetsDir, file), "utf-8");
-      JSON.parse(content);
+      const content = import_fs4.default.readFileSync(import_path4.default.join(assetsDir, file), "utf-8");
+      parsed[file] = JSON.parse(content);
       console.log(import_chalk2.default.green(`\u2713 ${file} is valid JSON.`));
     } catch (e) {
-      hasErrors = true;
+      hasJsonErrors = true;
       console.log(import_chalk2.default.red(`\u274C ${file} has syntax errors:`));
       console.log(import_chalk2.default.red(`   ${e.message}`));
     }
   });
-  if (hasErrors) {
+  if (hasJsonErrors) {
     console.log(import_chalk2.default.red("\n\u{1F4A5} Validation failed. Please fix the errors above."));
     process.exit(1);
-  } else {
-    console.log(import_chalk2.default.bold.green("\n\u2728 All files are valid! You are ready to go."));
   }
+  console.log(import_chalk2.default.bold.blue("\n\u{1F6E1}\uFE0F  Guarding against broken references and duplicate keys...\n"));
+  const definedKeys = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    Object.keys(flatten(parsed[file])).forEach((k) => definedKeys.add(k));
+  }
+  const refFile = files.includes("en.json") ? "en.json" : files.sort()[0];
+  const refValues = flatten(parsed[refFile]);
+  const sourceRoot = getSourceRoot(framework);
+  const sourceFiles = walkSourceFiles(sourceRoot);
+  const { used, dynamicPrefixes: magicPrefixes } = scanUsedKeys(sourceFiles);
+  const safelist = loadSafelist(cwd);
+  const protectedPrefixes = /* @__PURE__ */ new Set([...safelist.dynamicPrefixes || [], ...magicPrefixes]);
+  const missing = [...used.keys()].filter((k) => !definedKeys.has(k)).filter((k) => !isProtectedByPrefix(k, protectedPrefixes));
+  const baseline = loadBaseline(cwd);
+  const baselineSet = new Set(baseline.keys);
+  const freshMissing = missing.filter((k) => !baselineSet.has(k));
+  const staleBaseline = baseline.keys.filter((k) => !missing.includes(k));
+  if (opts.updateBaseline) {
+    saveBaseline(cwd, missing);
+    console.log(import_chalk2.default.green(`\u2705 Baseline updated: ${missing.length} accepted missing key(s) written to kopynator.i18n-baseline.json`));
+    return;
+  }
+  if (opts.all) {
+    console.log(import_chalk2.default.bold(`
+All missing keys (${missing.length}):`));
+    missing.slice().sort().forEach((k) => {
+      const tag = baselineSet.has(k) ? import_chalk2.default.gray("[baseline]") : import_chalk2.default.red("[NEW]");
+      console.log(`  ${tag} ${k} ${import_chalk2.default.gray(`(used ${used.get(k)}x)`)}`);
+    });
+  }
+  const baseRef = opts.baseRef || "master";
+  const oldRefContent = gitShowFile(cwd, baseRef, import_path4.default.relative(cwd, import_path4.default.join(assetsDir, refFile)));
+  const oldRefValues = oldRefContent ? flatten(JSON.parse(oldRefContent)) : {};
+  const duplicates = findGlobalDuplicates(refValues, new Set(used.keys())).filter(
+    (d) => oldRefValues[d.key] === void 0 || oldRefValues[d.key] !== refValues[d.key]
+  );
+  let hasFailures = false;
+  if (freshMissing.length) {
+    hasFailures = true;
+    console.log(import_chalk2.default.red(`
+\u274C ${freshMissing.length} translation key(s) used in code but missing from ${assetsDir}:`));
+    freshMissing.sort().forEach((k) => console.log(import_chalk2.default.red(`   - ${k} ${import_chalk2.default.gray(`(used ${used.get(k)}x)`)}`)));
+  }
+  if (duplicates.length) {
+    hasFailures = true;
+    console.log(import_chalk2.default.red(`
+\u274C ${duplicates.length} key(s) duplicate an existing global value:`));
+    duplicates.forEach(
+      (d) => console.log(import_chalk2.default.red(`   - "${d.key}" duplicates "${d.canonical}"${d.canonicalIsNew ? import_chalk2.default.gray(" (not created yet \u2014 proposed)") : ""} \u2192 "${d.value}"`))
+    );
+  }
+  if (staleBaseline.length) {
+    console.log(
+      import_chalk2.default.blue(`
+\u2139\uFE0F  i18n: ${staleBaseline.length} baseline key(s) no longer missing; regenerate: kopynator check --update-baseline`)
+    );
+  }
+  if (hasFailures) {
+    console.log(import_chalk2.default.red("\n\u{1F4A5} i18n check failed. Fix the issues above, or run with --update-baseline to accept current debt."));
+    process.exit(1);
+  }
+  console.log(import_chalk2.default.bold.green(`
+\u2728 i18n check passed (${files.length} locale file(s); baseline=${baselineSet.size}; scanned ${sourceFiles.length} source file(s)).`));
 }
 
 // src/commands/sync.ts
 var import_chalk3 = __toESM(require("chalk"));
-var import_fs3 = __toESM(require("fs"));
-var import_path3 = __toESM(require("path"));
+var import_fs5 = __toESM(require("fs"));
+var import_path5 = __toESM(require("path"));
 var import_inquirer2 = __toESM(require("inquirer"));
 var import_ora = __toESM(require("ora"));
-function detectFramework() {
-  const angularJson = import_path3.default.join(process.cwd(), "angular.json");
-  const packageJson = import_path3.default.join(process.cwd(), "package.json");
-  if (import_fs3.default.existsSync(angularJson)) {
-    return "Angular";
-  }
-  if (import_fs3.default.existsSync(packageJson)) {
-    try {
-      const pkg = JSON.parse(import_fs3.default.readFileSync(packageJson, "utf-8"));
-      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-      if (deps["@angular/core"]) return "Angular";
-      if (deps["react"]) return "React";
-      if (deps["vue"]) return "Vue";
-    } catch (e) {
-    }
-  }
-  return "Other";
-}
-function getTranslationDir(framework) {
-  switch (framework) {
-    case "Angular":
-      return import_path3.default.join(process.cwd(), "src/assets/i18n");
-    case "React":
-      return import_path3.default.join(process.cwd(), "public/locales");
-    case "Vue":
-      return import_path3.default.join(process.cwd(), "public/locales");
-    default:
-      return import_path3.default.join(process.cwd(), "locales");
-  }
-}
 function loadJsonConfig(jsonPath) {
-  if (!import_fs3.default.existsSync(jsonPath)) return null;
+  if (!import_fs5.default.existsSync(jsonPath)) return null;
   try {
-    const config = JSON.parse(import_fs3.default.readFileSync(jsonPath, "utf-8"));
+    const config = JSON.parse(import_fs5.default.readFileSync(jsonPath, "utf-8"));
     if (config.apiKey) return { apiKey: config.apiKey, baseUrl: config.baseUrl };
   } catch (e) {
     if (jsonPath.includes("kopynator.config.json")) {
@@ -355,28 +576,28 @@ function loadJsonConfig(jsonPath) {
 }
 function extractApiKey() {
   const cwd = process.cwd();
-  const configFromRoot = loadJsonConfig(import_path3.default.join(cwd, "kopynator.config.json"));
+  const configFromRoot = loadJsonConfig(import_path5.default.join(cwd, "kopynator.config.json"));
   if (configFromRoot) {
     console.log(import_chalk3.default.blue("\u2139\uFE0F  Found API key in kopynator.config.json"));
     return configFromRoot;
   }
-  const configFromSrc = loadJsonConfig(import_path3.default.join(cwd, "src/kopynator.config.json"));
+  const configFromSrc = loadJsonConfig(import_path5.default.join(cwd, "src/kopynator.config.json"));
   if (configFromSrc) {
     console.log(import_chalk3.default.blue("\u2139\uFE0F  Found API key in src/kopynator.config.json"));
     return configFromSrc;
   }
-  const appConfigPath = import_path3.default.join(cwd, "src/app/app.config.ts");
-  const appModulePath = import_path3.default.join(cwd, "src/app/app.module.ts");
-  if (import_fs3.default.existsSync(appConfigPath)) {
-    const content = import_fs3.default.readFileSync(appConfigPath, "utf-8");
+  const appConfigPath = import_path5.default.join(cwd, "src/app/app.config.ts");
+  const appModulePath = import_path5.default.join(cwd, "src/app/app.module.ts");
+  if (import_fs5.default.existsSync(appConfigPath)) {
+    const content = import_fs5.default.readFileSync(appConfigPath, "utf-8");
     const apiKeyMatch = content.match(/apiKey:\s*['"]([^'"]+)['"]/);
     if (apiKeyMatch) {
       console.log(import_chalk3.default.blue("\u2139\uFE0F  Found API key in app.config.ts"));
       return { apiKey: apiKeyMatch[1] };
     }
   }
-  if (import_fs3.default.existsSync(appModulePath)) {
-    const content = import_fs3.default.readFileSync(appModulePath, "utf-8");
+  if (import_fs5.default.existsSync(appModulePath)) {
+    const content = import_fs5.default.readFileSync(appModulePath, "utf-8");
     const apiKeyMatch = content.match(/apiKey:\s*['"]([^'"]+)['"]/);
     if (apiKeyMatch) {
       console.log(import_chalk3.default.blue("\u2139\uFE0F  Found API key in app.module.ts"));
@@ -394,10 +615,10 @@ function extractApiKey() {
   return null;
 }
 async function getSyncConfig() {
-  const configPath = import_path3.default.join(process.cwd(), "kopynator.sync.config.json");
-  if (import_fs3.default.existsSync(configPath)) {
+  const configPath = import_path5.default.join(process.cwd(), "kopynator.sync.config.json");
+  if (import_fs5.default.existsSync(configPath)) {
     try {
-      const config2 = JSON.parse(import_fs3.default.readFileSync(configPath, "utf-8"));
+      const config2 = JSON.parse(import_fs5.default.readFileSync(configPath, "utf-8"));
       console.log(import_chalk3.default.blue("\u2139\uFE0F  Using existing sync configuration"));
       return config2;
     } catch (e) {
@@ -442,7 +663,7 @@ async function getSyncConfig() {
     pretty: answers.pretty,
     indent: answers.indent
   };
-  import_fs3.default.writeFileSync(configPath, JSON.stringify(config, null, 2));
+  import_fs5.default.writeFileSync(configPath, JSON.stringify(config, null, 2));
   console.log(import_chalk3.default.green("\u2705 Configuration saved to kopynator.sync.config.json\n"));
   return config;
 }
@@ -475,8 +696,8 @@ async function syncCommand() {
     const languages = await languagesResponse.json();
     spinner.succeed(`Found ${languages.length} language(s): ${languages.join(", ")}`);
     const i18nDir = getTranslationDir(framework);
-    if (!import_fs3.default.existsSync(i18nDir)) {
-      import_fs3.default.mkdirSync(i18nDir, { recursive: true });
+    if (!import_fs5.default.existsSync(i18nDir)) {
+      import_fs5.default.mkdirSync(i18nDir, { recursive: true });
       console.log(import_chalk3.default.blue(`\u{1F4C1} Created directory: ${i18nDir}`));
     }
     for (const locale of languages) {
@@ -493,7 +714,7 @@ async function syncCommand() {
           continue;
         }
         const translationData = await translationResponse.json();
-        const outputPath = import_path3.default.join(i18nDir, `${locale}.json`);
+        const outputPath = import_path5.default.join(i18nDir, `${locale}.json`);
         let jsonString;
         if (syncConfig.pretty) {
           const indentValue = syncConfig.indent === "tab" ? "	" : Number(syncConfig.indent);
@@ -501,7 +722,7 @@ async function syncCommand() {
         } else {
           jsonString = JSON.stringify(translationData);
         }
-        import_fs3.default.writeFileSync(outputPath, jsonString);
+        import_fs5.default.writeFileSync(outputPath, jsonString);
         downloadSpinner.succeed(`Saved ${locale}.json`);
       } catch (err) {
         downloadSpinner.fail(`Error downloading ${locale}: ${err instanceof Error ? err.message : "Unknown error"}`);
@@ -515,17 +736,17 @@ async function syncCommand() {
 
 // src/commands/upload.ts
 var import_chalk4 = __toESM(require("chalk"));
-var import_fs4 = __toESM(require("fs"));
-var import_path4 = __toESM(require("path"));
+var import_fs6 = __toESM(require("fs"));
+var import_path6 = __toESM(require("path"));
 var import_ora2 = __toESM(require("ora"));
 var BATCH_SIZE = 500;
-function flatten(data, prefix = "") {
+function flatten2(data, prefix = "") {
   const result = {};
   for (const key in data) {
     const fullKey = prefix ? `${prefix}.${key}` : key;
     const value = data[key];
     if (value !== null && typeof value === "object" && !Array.isArray(value)) {
-      Object.assign(result, flatten(value, fullKey));
+      Object.assign(result, flatten2(value, fullKey));
     } else {
       result[fullKey] = String(value);
     }
@@ -533,9 +754,9 @@ function flatten(data, prefix = "") {
   return result;
 }
 function loadJsonConfig2(jsonPath) {
-  if (!import_fs4.default.existsSync(jsonPath)) return null;
+  if (!import_fs6.default.existsSync(jsonPath)) return null;
   try {
-    const config = JSON.parse(import_fs4.default.readFileSync(jsonPath, "utf-8"));
+    const config = JSON.parse(import_fs6.default.readFileSync(jsonPath, "utf-8"));
     const key = config.apiKey ?? config.api_key;
     if (key && typeof key === "string") return { apiKey: key, baseUrl: config.baseUrl };
   } catch {
@@ -544,19 +765,19 @@ function loadJsonConfig2(jsonPath) {
 }
 function extractApiKey2() {
   const cwd = process.cwd();
-  const appConfigPath = import_path4.default.join(cwd, "src/app/app.config.ts");
-  const appModulePath = import_path4.default.join(cwd, "src/app/app.module.ts");
-  const configFromRoot = loadJsonConfig2(import_path4.default.join(cwd, "kopynator.config.json"));
+  const appConfigPath = import_path6.default.join(cwd, "src/app/app.config.ts");
+  const appModulePath = import_path6.default.join(cwd, "src/app/app.module.ts");
+  const configFromRoot = loadJsonConfig2(import_path6.default.join(cwd, "kopynator.config.json"));
   if (configFromRoot) return configFromRoot;
-  const configFromSrc = loadJsonConfig2(import_path4.default.join(cwd, "src/kopynator.config.json"));
+  const configFromSrc = loadJsonConfig2(import_path6.default.join(cwd, "src/kopynator.config.json"));
   if (configFromSrc) return configFromSrc;
-  if (import_fs4.default.existsSync(appConfigPath)) {
-    const content = import_fs4.default.readFileSync(appConfigPath, "utf-8");
+  if (import_fs6.default.existsSync(appConfigPath)) {
+    const content = import_fs6.default.readFileSync(appConfigPath, "utf-8");
     const apiKeyMatch = content.match(/apiKey:\s*['"]([^'"]+)['"]/);
     if (apiKeyMatch) return { apiKey: apiKeyMatch[1] };
   }
-  if (import_fs4.default.existsSync(appModulePath)) {
-    const content = import_fs4.default.readFileSync(appModulePath, "utf-8");
+  if (import_fs6.default.existsSync(appModulePath)) {
+    const content = import_fs6.default.readFileSync(appModulePath, "utf-8");
     const apiKeyMatch = content.match(/apiKey:\s*['"]([^'"]+)['"]/);
     if (apiKeyMatch) return { apiKey: apiKeyMatch[1] };
   }
@@ -570,7 +791,7 @@ function extractApiKey2() {
   return null;
 }
 function inferLangFromFile(filePath) {
-  const base = import_path4.default.basename(filePath, import_path4.default.extname(filePath));
+  const base = import_path6.default.basename(filePath, import_path6.default.extname(filePath));
   return base;
 }
 async function uploadCommand(options) {
@@ -578,13 +799,13 @@ async function uploadCommand(options) {
   const config = extractApiKey2();
   if (!config) {
     const cwd = process.cwd();
-    const rootConfig = import_path4.default.join(cwd, "kopynator.config.json");
-    const srcConfig = import_path4.default.join(cwd, "src/kopynator.config.json");
+    const rootConfig = import_path6.default.join(cwd, "kopynator.config.json");
+    const srcConfig = import_path6.default.join(cwd, "src/kopynator.config.json");
     console.log(import_chalk4.default.red("\u274C Could not find API key. Set it in kopynator.config.json, app.config.ts, or KOPYNATOR_API_KEY. Run `npx kopynator init` to create config."));
     console.log(import_chalk4.default.gray(`   Directorio actual: ${cwd}`));
-    console.log(import_chalk4.default.gray(`   Comprobado: ${rootConfig} (${import_fs4.default.existsSync(rootConfig) ? "existe" : "no existe"})`));
-    console.log(import_chalk4.default.gray(`   Comprobado: ${srcConfig} (${import_fs4.default.existsSync(srcConfig) ? "existe" : "no existe"})`));
-    if (import_fs4.default.existsSync(rootConfig) || import_fs4.default.existsSync(srcConfig)) {
+    console.log(import_chalk4.default.gray(`   Comprobado: ${rootConfig} (${import_fs6.default.existsSync(rootConfig) ? "existe" : "no existe"})`));
+    console.log(import_chalk4.default.gray(`   Comprobado: ${srcConfig} (${import_fs6.default.existsSync(srcConfig) ? "existe" : "no existe"})`));
+    if (import_fs6.default.existsSync(rootConfig) || import_fs6.default.existsSync(srcConfig)) {
       console.log(import_chalk4.default.yellow('\u{1F4A1} Si el archivo existe, comprueba que tenga la propiedad "apiKey" (o "api_key") con un valor no vac\xEDo.'));
     } else {
       console.log(import_chalk4.default.yellow("\u{1F4A1} Ejecuta el comando desde la ra\xEDz del proyecto (donde est\xE1 package.json)."));
@@ -596,8 +817,8 @@ async function uploadCommand(options) {
     console.log(import_chalk4.default.red("\u274C Missing --file. Example: npx kopynator upload --file=es.json [--lang=es]"));
     return;
   }
-  const resolvedPath = import_path4.default.isAbsolute(fileOption) ? fileOption : import_path4.default.join(process.cwd(), fileOption);
-  if (!import_fs4.default.existsSync(resolvedPath)) {
+  const resolvedPath = import_path6.default.isAbsolute(fileOption) ? fileOption : import_path6.default.join(process.cwd(), fileOption);
+  if (!import_fs6.default.existsSync(resolvedPath)) {
     console.log(import_chalk4.default.red(`\u274C File not found: ${resolvedPath}`));
     return;
   }
@@ -606,7 +827,7 @@ async function uploadCommand(options) {
   const token = config.apiKey;
   let raw;
   try {
-    raw = JSON.parse(import_fs4.default.readFileSync(resolvedPath, "utf-8"));
+    raw = JSON.parse(import_fs6.default.readFileSync(resolvedPath, "utf-8"));
   } catch (e) {
     console.log(import_chalk4.default.red(`\u274C Invalid JSON: ${resolvedPath}`));
     return;
@@ -615,7 +836,7 @@ async function uploadCommand(options) {
     console.log(import_chalk4.default.red("\u274C JSON root must be an object (key-value)."));
     return;
   }
-  const flat = flatten(raw);
+  const flat = flatten2(raw);
   const entries = Object.entries(flat);
   const total = entries.length;
   if (total === 0) {
@@ -691,14 +912,14 @@ async function uploadCommand(options) {
 
 // src/commands/limits.ts
 var import_chalk5 = __toESM(require("chalk"));
-var import_fs5 = __toESM(require("fs"));
-var import_path5 = __toESM(require("path"));
+var import_fs7 = __toESM(require("fs"));
+var import_path7 = __toESM(require("path"));
 function resolveApiKey() {
   const cwd = process.cwd();
   const fromJson = (p) => {
     try {
-      if (import_fs5.default.existsSync(p)) {
-        const cfg = JSON.parse(import_fs5.default.readFileSync(p, "utf-8"));
+      if (import_fs7.default.existsSync(p)) {
+        const cfg = JSON.parse(import_fs7.default.readFileSync(p, "utf-8"));
         if (cfg && cfg.apiKey) return { apiKey: cfg.apiKey, baseUrl: cfg.baseUrl };
       }
     } catch {
@@ -707,8 +928,8 @@ function resolveApiKey() {
   };
   const fromAppFile = (p) => {
     try {
-      if (import_fs5.default.existsSync(p)) {
-        const content = import_fs5.default.readFileSync(p, "utf-8");
+      if (import_fs7.default.existsSync(p)) {
+        const content = import_fs7.default.readFileSync(p, "utf-8");
         const match = content.match(/apiKey:\s*['"]([^'"]+)['"]/);
         if (match) return { apiKey: match[1] };
       }
@@ -716,7 +937,7 @@ function resolveApiKey() {
     }
     return null;
   };
-  return fromJson(import_path5.default.join(cwd, "kopynator.config.json")) || fromJson(import_path5.default.join(cwd, "src/kopynator.config.json")) || fromAppFile(import_path5.default.join(cwd, "src/app/app.config.ts")) || fromAppFile(import_path5.default.join(cwd, "src/app/app.module.ts")) || (process.env.KOPYNATOR_API_KEY ? { apiKey: process.env.KOPYNATOR_API_KEY.trim(), baseUrl: process.env.KOPYNATOR_BASE_URL?.trim() } : null);
+  return fromJson(import_path7.default.join(cwd, "kopynator.config.json")) || fromJson(import_path7.default.join(cwd, "src/kopynator.config.json")) || fromAppFile(import_path7.default.join(cwd, "src/app/app.config.ts")) || fromAppFile(import_path7.default.join(cwd, "src/app/app.module.ts")) || (process.env.KOPYNATOR_API_KEY ? { apiKey: process.env.KOPYNATOR_API_KEY.trim(), baseUrl: process.env.KOPYNATOR_BASE_URL?.trim() } : null);
 }
 function formatLimit(value) {
   return value === -1 ? "Unlimited" : String(value);
@@ -772,7 +993,7 @@ async function limitsCommand() {
 var program = new import_commander.Command();
 program.name("kopynator").description("Kopynator CLI - Manage your i18n workflow").version("1.5.1", "-v, --version").helpOption("-h, --help", "Display help for command").addHelpText("beforeAll", import_chalk6.default.blue("\n\u{1F44B} Welcome to Kopynator CLI!\n"));
 program.command("init").description("Initialize Kopynator in your project").action(initCommand);
-program.command("check").description("Validate your local JSON translation files").action(checkCommand);
+program.command("check").description("Validate translation files: JSON syntax, broken references and duplicate global keys").option("--base-ref <ref>", "Git ref to diff against when detecting new duplicate keys", "master").option("--update-baseline", "Accept all currently-missing keys as backlog (writes kopynator.i18n-baseline.json)").option("--all", "List every missing key, including ones already accepted in the baseline").action((opts) => checkCommand({ baseRef: opts.baseRef, updateBaseline: opts.updateBaseline, all: opts.all }));
 program.command("sync").description("Sync your translations with the Kopynator Cloud").action(syncCommand);
 program.command("upload").description("Upload a JSON translation file to Kopynator Cloud").option("-f, --file <path>", "Path to the JSON file (e.g. es.json)").option("-l, --lang <code>", "Language code (default: inferred from filename)").action((opts) => uploadCommand({ file: opts.file, lang: opts.lang }));
 program.command("limits").description("Show your plan limits and current usage (projects, keys, members)").action(limitsCommand);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kopynator/cli",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "CLI tool for Kopynator - The i18n management solution",
   "bin": {
     "kopynator": "dist/index.js"

package/src/commands/check.ts

@@ -1,43 +1,151 @@
 import chalk from 'chalk';
 import fs from 'fs';
 import path from 'path';
+import { detectFramework, getSourceRoot, getTranslationDir } from '../lib/project';
+import {
+  findGlobalDuplicates,
+  flatten,
+  gitShowFile,
+  isProtectedByPrefix,
+  loadBaseline,
+  loadSafelist,
+  saveBaseline,
+  scanUsedKeys,
+  walkSourceFiles,
+} from '../lib/i18n-guardian';
+
+export interface CheckOptions {
+  baseRef?: string;
+  updateBaseline?: boolean;
+  all?: boolean;
+}
+
+export async function checkCommand(opts: CheckOptions = {}) {
+  if (process.env.KOPYNATOR_I18N_SKIP === '1') {
+    console.log(chalk.yellow('⚠️  KOPYNATOR_I18N_SKIP=1 — skipping i18n check.'));
+    return;
+  }
 
-export async function checkCommand() {
   console.log(chalk.bold.blue('\n🔍 Validating JSON translation files...\n'));
 
-  const assetsDir = path.join(process.cwd(), 'src/assets/i18n'); // Default angular structural assumption for demo
+  const cwd = process.cwd();
+  const framework = detectFramework();
+  const assetsDir = getTranslationDir(framework);
 
   if (!fs.existsSync(assetsDir)) {
     console.log(chalk.red(`❌ Could not find directory: ${assetsDir}`));
     console.log(chalk.yellow('Make sure you are running this from your project root.'));
-    return;
+    process.exit(1);
   }
 
   const files = fs.readdirSync(assetsDir).filter(f => f.endsWith('.json'));
 
   if (files.length === 0) {
-    console.log(chalk.yellow('⚠️ No JSON files found in assets/i18n.'));
+    console.log(chalk.yellow('⚠️ No JSON files found in ' + assetsDir + '.'));
     return;
   }
 
-  let hasErrors = false;
+  let hasJsonErrors = false;
+  const parsed: Record<string, any> = {};
 
   files.forEach(file => {
     try {
       const content = fs.readFileSync(path.join(assetsDir, file), 'utf-8');
-      JSON.parse(content);
+      parsed[file] = JSON.parse(content);
       console.log(chalk.green(`✓ ${file} is valid JSON.`));
     } catch (e: any) {
-      hasErrors = true;
+      hasJsonErrors = true;
       console.log(chalk.red(`❌ ${file} has syntax errors:`));
       console.log(chalk.red(`   ${e.message}`));
     }
   });
 
-  if (hasErrors) {
+  if (hasJsonErrors) {
     console.log(chalk.red('\n💥 Validation failed. Please fix the errors above.'));
     process.exit(1);
-  } else {
-    console.log(chalk.bold.green('\n✨ All files are valid! You are ready to go.'));
   }
+
+  console.log(chalk.bold.blue('\n🛡️  Guarding against broken references and duplicate keys...\n'));
+
+  // Defined keys: union across every locale file (a key only needs to exist somewhere).
+  const definedKeys = new Set<string>();
+  for (const file of files) {
+    Object.keys(flatten(parsed[file])).forEach(k => definedKeys.add(k));
+  }
+
+  // Reference locale for value-based duplicate detection: prefer en.json, else first alphabetically.
+  const refFile = files.includes('en.json') ? 'en.json' : files.sort()[0];
+  const refValues = flatten(parsed[refFile]);
+
+  // Scan app source for key usage + inline `kopynator-keys: prefix.*` declarations.
+  const sourceRoot = getSourceRoot(framework);
+  const sourceFiles = walkSourceFiles(sourceRoot);
+  const { used, dynamicPrefixes: magicPrefixes } = scanUsedKeys(sourceFiles);
+
+  const safelist = loadSafelist(cwd);
+  const protectedPrefixes = new Set([...(safelist.dynamicPrefixes || []), ...magicPrefixes]);
+
+  // --- Broken references: used in code, not defined in any locale file ---
+  const missing = [...used.keys()]
+    .filter(k => !definedKeys.has(k))
+    .filter(k => !isProtectedByPrefix(k, protectedPrefixes));
+
+  const baseline = loadBaseline(cwd);
+  const baselineSet = new Set(baseline.keys);
+  const freshMissing = missing.filter(k => !baselineSet.has(k));
+  const staleBaseline = baseline.keys.filter(k => !missing.includes(k));
+
+  if (opts.updateBaseline) {
+    saveBaseline(cwd, missing);
+    console.log(chalk.green(`✅ Baseline updated: ${missing.length} accepted missing key(s) written to kopynator.i18n-baseline.json`));
+    return;
+  }
+
+  if (opts.all) {
+    console.log(chalk.bold(`\nAll missing keys (${missing.length}):`));
+    missing
+      .slice()
+      .sort()
+      .forEach(k => {
+        const tag = baselineSet.has(k) ? chalk.gray('[baseline]') : chalk.red('[NEW]');
+        console.log(`  ${tag} ${k} ${chalk.gray(`(used ${used.get(k)}x)`)}`);
+      });
+  }
+
+  // --- Duplicate-of-global values: only flag keys that are new since the base ref ---
+  const baseRef = opts.baseRef || 'master';
+  const oldRefContent = gitShowFile(cwd, baseRef, path.relative(cwd, path.join(assetsDir, refFile)));
+  const oldRefValues = oldRefContent ? flatten(JSON.parse(oldRefContent)) : {};
+  const duplicates = findGlobalDuplicates(refValues, new Set(used.keys())).filter(
+    d => oldRefValues[d.key] === undefined || oldRefValues[d.key] !== refValues[d.key]
+  );
+
+  let hasFailures = false;
+
+  if (freshMissing.length) {
+    hasFailures = true;
+    console.log(chalk.red(`\n❌ ${freshMissing.length} translation key(s) used in code but missing from ${assetsDir}:`));
+    freshMissing.sort().forEach(k => console.log(chalk.red(`   - ${k} ${chalk.gray(`(used ${used.get(k)}x)`)}`)));
+  }
+
+  if (duplicates.length) {
+    hasFailures = true;
+    console.log(chalk.red(`\n❌ ${duplicates.length} key(s) duplicate an existing global value:`));
+    duplicates.forEach(d =>
+      console.log(chalk.red(`   - "${d.key}" duplicates "${d.canonical}"${d.canonicalIsNew ? chalk.gray(' (not created yet — proposed)') : ''} → "${d.value}"`))
+    );
+  }
+
+  if (staleBaseline.length) {
+    console.log(
+      chalk.blue(`\nℹ️  i18n: ${staleBaseline.length} baseline key(s) no longer missing; regenerate: kopynator check --update-baseline`)
+    );
+  }
+
+  if (hasFailures) {
+    console.log(chalk.red('\n💥 i18n check failed. Fix the issues above, or run with --update-baseline to accept current debt.'));
+    process.exit(1);
+  }
+
+  console.log(chalk.bold.green(`\n✨ i18n check passed (${files.length} locale file(s); baseline=${baselineSet.size}; scanned ${sourceFiles.length} source file(s)).`));
 }

package/src/commands/sync.ts

@@ -3,6 +3,7 @@ import fs from 'fs';
 import path from 'path';
 import inquirer from 'inquirer';
 import ora from 'ora';
+import { detectFramework, getTranslationDir } from '../lib/project';
 
 interface KopyConfig {
   apiKey: string;
@@ -16,54 +17,6 @@ interface SyncConfig {
   indent: '2' | '4' | 'tab';
 }
 
-/**
- * Detect the framework being used in the current project
- */
-function detectFramework(): 'Angular' | 'React' | 'Vue' | 'Other' {
-  const angularJson = path.join(process.cwd(), 'angular.json');
-  const packageJson = path.join(process.cwd(), 'package.json');
-
-  // Check for Angular
-  if (fs.existsSync(angularJson)) {
-    return 'Angular';
-  }
-
-  // Check package.json for React/Vue
-  if (fs.existsSync(packageJson)) {
-    try {
-      const pkg = JSON.parse(fs.readFileSync(packageJson, 'utf-8'));
-      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-      
-      if (deps['@angular/core']) return 'Angular';
-      if (deps['react']) return 'React';
-      if (deps['vue']) return 'Vue';
-    } catch (e) {
-      // Ignore parse errors
-    }
-  }
-
-  return 'Other';
-}
-
-/**
- * Get the translation directory path based on framework
- */
-function getTranslationDir(framework: string): string {
-  switch (framework) {
-    case 'Angular':
-      return path.join(process.cwd(), 'src/assets/i18n');
-    case 'React':
-      // Common React patterns, can be customized later
-      return path.join(process.cwd(), 'public/locales');
-    case 'Vue':
-      // Common Vue patterns, can be customized later
-      return path.join(process.cwd(), 'public/locales');
-    default:
-      // Default fallback
-      return path.join(process.cwd(), 'locales');
-  }
-}
-
 /**
  * API key del proyecto primero (no hace falta en el comando), luego env para CI.
  * Order: app.config.ts -> app.module.ts -> kopynator.config.json -> KOPYNATOR_API_KEY

package/src/index.ts

@@ -19,8 +19,11 @@ program
 
 program
   .command('check')
-  .description('Validate your local JSON translation files')
-  .action(checkCommand);
+  .description('Validate translation files: JSON syntax, broken references and duplicate global keys')
+  .option('--base-ref <ref>', 'Git ref to diff against when detecting new duplicate keys', 'master')
+  .option('--update-baseline', 'Accept all currently-missing keys as backlog (writes kopynator.i18n-baseline.json)')
+  .option('--all', 'List every missing key, including ones already accepted in the baseline')
+  .action((opts) => checkCommand({ baseRef: opts.baseRef, updateBaseline: opts.updateBaseline, all: opts.all }));
 
 program
   .command('sync')

package/src/lib/i18n-guardian.ts

@@ -0,0 +1,190 @@
+import fs from 'fs';
+import path from 'path';
+import { execFileSync } from 'child_process';
+
+export interface SafelistConfig {
+  dynamicPrefixes?: string[];
+}
+
+export interface BaselineConfig {
+  keys: string[];
+}
+
+export interface UsedKey {
+  key: string;
+  count: number;
+}
+
+export interface DuplicateFinding {
+  key: string;
+  value: string;
+  canonical: string;
+  canonicalIsNew: boolean;
+}
+
+const SAFELIST_FILE = 'kopynator.i18n-safelist.json';
+const BASELINE_FILE = 'kopynator.i18n-baseline.json';
+const SOURCE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.html', '.vue'];
+const EXCLUDED_DIRS = new Set(['node_modules', 'dist', 'build', '.git', '.angular', 'coverage', '.next', '.nuxt', 'out']);
+
+const KEY = `[\\w.:-]+`;
+const USE_PATTERNS: { re: RegExp; group: number }[] = [
+  // {{ 'key' | kopy }} — Angular pipe
+  { re: new RegExp(`(['"\`])(${KEY})\\1\\s*\\|\\s*kopy`, 'g'), group: 2 },
+  // [kopy]="'key'" — Angular directive with a string literal binding
+  { re: new RegExp(`\\[kopy\\]\\s*=\\s*"'(${KEY})'"`, 'g'), group: 1 },
+  // .translate('key') / .t('key') — @kopynator/core & @kopynator/react API
+  { re: new RegExp(`\\.(?:translate|t)\\(\\s*(['"\`])(${KEY})\\1`, 'g'), group: 2 },
+];
+
+const MAGIC_RE = /kopynator-keys\s*:\s*([^\n]+)/g;
+
+/** Recursively flattens a nested translation object into dot-notation keys. */
+export function flatten(obj: Record<string, any>, prefix = ''): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(obj || {})) {
+    const key = prefix ? `${prefix}.${k}` : k;
+    if (v && typeof v === 'object' && !Array.isArray(v)) {
+      Object.assign(out, flatten(v, key));
+    } else {
+      out[key] = String(v);
+    }
+  }
+  return out;
+}
+
+export function walkSourceFiles(rootDir: string): string[] {
+  if (!fs.existsSync(rootDir)) return [];
+  const results: string[] = [];
+
+  function walk(dir: string) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (EXCLUDED_DIRS.has(entry.name)) continue;
+        walk(path.join(dir, entry.name));
+      } else if (SOURCE_EXTENSIONS.includes(path.extname(entry.name))) {
+        results.push(path.join(dir, entry.name));
+      }
+    }
+  }
+
+  walk(rootDir);
+  return results;
+}
+
+/** Scans source files for translation key usage and inline `kopynator-keys:` dynamic-prefix declarations. */
+export function scanUsedKeys(files: string[]): { used: Map<string, number>; dynamicPrefixes: Set<string> } {
+  const used = new Map<string, number>();
+  const dynamicPrefixes = new Set<string>();
+
+  for (const file of files) {
+    const content = fs.readFileSync(file, 'utf-8');
+
+    for (const { re, group } of USE_PATTERNS) {
+      re.lastIndex = 0;
+      let match: RegExpExecArray | null;
+      while ((match = re.exec(content))) {
+        const key = match[group];
+        used.set(key, (used.get(key) || 0) + 1);
+      }
+    }
+
+    MAGIC_RE.lastIndex = 0;
+    let magicMatch: RegExpExecArray | null;
+    while ((magicMatch = MAGIC_RE.exec(content))) {
+      for (const raw of magicMatch[1].split(',')) {
+        const prefix = raw.trim().replace(/\*$/, '');
+        if (prefix) dynamicPrefixes.add(prefix);
+      }
+    }
+  }
+
+  return { used, dynamicPrefixes };
+}
+
+export function loadSafelist(cwd: string): SafelistConfig {
+  const p = path.join(cwd, SAFELIST_FILE);
+  if (!fs.existsSync(p)) return { dynamicPrefixes: [] };
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf-8'));
+  } catch {
+    return { dynamicPrefixes: [] };
+  }
+}
+
+export function loadBaseline(cwd: string): BaselineConfig {
+  const p = path.join(cwd, BASELINE_FILE);
+  if (!fs.existsSync(p)) return { keys: [] };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(p, 'utf-8'));
+    return { keys: Array.isArray(parsed.keys) ? parsed.keys : [] };
+  } catch {
+    return { keys: [] };
+  }
+}
+
+export function saveBaseline(cwd: string, keys: string[]): void {
+  const p = path.join(cwd, BASELINE_FILE);
+  fs.writeFileSync(p, JSON.stringify({ keys: keys.sort() }, null, 2) + '\n');
+}
+
+export function isProtectedByPrefix(key: string, prefixes: Set<string> | string[]): boolean {
+  for (const prefix of prefixes) {
+    if (key.startsWith(prefix)) return true;
+  }
+  return false;
+}
+
+/** Reads a file's content at a given git ref, or null if git/ref/file is unavailable. */
+export function gitShowFile(cwd: string, ref: string, relPath: string): string | null {
+  try {
+    return execFileSync('git', ['show', `${ref}:${relPath}`], { cwd, stdio: ['pipe', 'pipe', 'ignore'] }).toString('utf-8');
+  } catch {
+    return null;
+  }
+}
+
+export function slugify(value: string, maxLen = 40): string {
+  return String(value)
+    .replace(/<[^>]+>/g, '')
+    .replace(/\{\{[^}]+\}\}/g, '')
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .slice(0, maxLen) || 'value';
+}
+
+/** Picks the canonical key among a group of keys sharing the same value: prefers a category-segmented `global.*` key, else the shortest `global.*`, else null (no existing canonical). */
+export function pickGlobal(keys: string[]): string | null {
+  const globals = keys.filter(k => k.startsWith('global.'));
+  if (!globals.length) return null;
+  const segmented = globals.filter(k => /^global\.(status|error|action)\./.test(k));
+  const pool = segmented.length ? segmented : globals;
+  return pool.reduce((shortest, k) => (k.length < shortest.length ? k : shortest), pool[0]);
+}
+
+/** Finds keys whose value duplicates an existing (or proposable) `global.*` canonical, restricted to keys actually used in source. */
+export function findGlobalDuplicates(values: Record<string, string>, usedKeys: Set<string>): DuplicateFinding[] {
+  const byValue = new Map<string, string[]>();
+  for (const [key, value] of Object.entries(values)) {
+    const trimmed = value.trim();
+    if (!trimmed) continue;
+    const group = byValue.get(trimmed) || [];
+    group.push(key);
+    byValue.set(trimmed, group);
+  }
+
+  const findings: DuplicateFinding[] = [];
+  for (const [value, keys] of byValue) {
+    if (keys.length < 2) continue;
+    const canonical = pickGlobal(keys) || `global.${slugify(value)}`;
+    for (const key of keys) {
+      if (key === canonical) continue;
+      if (!usedKeys.has(key)) continue;
+      findings.push({ key, value, canonical, canonicalIsNew: !keys.includes(canonical) });
+    }
+  }
+  return findings;
+}

package/src/lib/project.ts

@@ -0,0 +1,60 @@
+import fs from 'fs';
+import path from 'path';
+
+export type Framework = 'Angular' | 'React' | 'Vue' | 'Other';
+
+/**
+ * Detect the framework being used in the current project
+ */
+export function detectFramework(): Framework {
+  const angularJson = path.join(process.cwd(), 'angular.json');
+  const packageJson = path.join(process.cwd(), 'package.json');
+
+  if (fs.existsSync(angularJson)) {
+    return 'Angular';
+  }
+
+  if (fs.existsSync(packageJson)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(packageJson, 'utf-8'));
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+      if (deps['@angular/core']) return 'Angular';
+      if (deps['react']) return 'React';
+      if (deps['vue']) return 'Vue';
+    } catch (e) {
+      // Ignore parse errors
+    }
+  }
+
+  return 'Other';
+}
+
+/**
+ * Get the translation directory path based on framework
+ */
+export function getTranslationDir(framework: Framework): string {
+  switch (framework) {
+    case 'Angular':
+      return path.join(process.cwd(), 'src/assets/i18n');
+    case 'React':
+    case 'Vue':
+      return path.join(process.cwd(), 'public/locales');
+    default:
+      return path.join(process.cwd(), 'locales');
+  }
+}
+
+/**
+ * Get the app source root to scan for translation key usage.
+ */
+export function getSourceRoot(framework: Framework): string {
+  switch (framework) {
+    case 'Angular':
+    case 'React':
+    case 'Vue':
+      return path.join(process.cwd(), 'src');
+    default:
+      return process.cwd();
+  }
+}