ai-localize-validators 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,60 @@
+import { ValidationError, ValidationWarning, ValidationResult } from '@ai-localize/shared';
+
+declare class MissingKeyValidator {
+    private localesDir;
+    private defaultLanguage;
+    private targetLanguages;
+    constructor(localesDir: string, defaultLanguage?: string, targetLanguages?: string[]);
+    validate(): {
+        errors: ValidationError[];
+        missingByLanguage: Record<string, string[]>;
+    };
+}
+
+declare class DuplicateKeyValidator {
+    private localesDir;
+    private defaultLanguage;
+    constructor(localesDir: string, defaultLanguage?: string);
+    validate(): {
+        errors: ValidationError[];
+        duplicates: string[];
+    };
+}
+
+declare class PlaceholderValidator {
+    private localesDir;
+    private defaultLanguage;
+    constructor(localesDir: string, defaultLanguage?: string);
+    validate(): ValidationError[];
+    private extract;
+}
+
+declare class UnusedKeyValidator {
+    private localesDir;
+    private sourceDir;
+    private defaultLanguage;
+    constructor(localesDir: string, sourceDir: string, defaultLanguage?: string);
+    validate(): {
+        warnings: ValidationWarning[];
+        unusedKeys: string[];
+    };
+    private collectLocaleKeys;
+    private collectSourceContent;
+}
+
+interface ValidatorOptions {
+    localesDir: string;
+    sourceDir: string;
+    defaultLanguage?: string;
+    targetLanguages?: string[];
+    checkUnused?: boolean;
+    checkDuplicates?: boolean;
+    checkPlaceholders?: boolean;
+}
+declare class LocaleValidator {
+    private options;
+    constructor(options: ValidatorOptions);
+    validate(): ValidationResult;
+}
+
+export { DuplicateKeyValidator, LocaleValidator, MissingKeyValidator, PlaceholderValidator, UnusedKeyValidator, type ValidatorOptions };

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+import { ValidationError, ValidationWarning, ValidationResult } from '@ai-localize/shared';
+
+declare class MissingKeyValidator {
+    private localesDir;
+    private defaultLanguage;
+    private targetLanguages;
+    constructor(localesDir: string, defaultLanguage?: string, targetLanguages?: string[]);
+    validate(): {
+        errors: ValidationError[];
+        missingByLanguage: Record<string, string[]>;
+    };
+}
+
+declare class DuplicateKeyValidator {
+    private localesDir;
+    private defaultLanguage;
+    constructor(localesDir: string, defaultLanguage?: string);
+    validate(): {
+        errors: ValidationError[];
+        duplicates: string[];
+    };
+}
+
+declare class PlaceholderValidator {
+    private localesDir;
+    private defaultLanguage;
+    constructor(localesDir: string, defaultLanguage?: string);
+    validate(): ValidationError[];
+    private extract;
+}
+
+declare class UnusedKeyValidator {
+    private localesDir;
+    private sourceDir;
+    private defaultLanguage;
+    constructor(localesDir: string, sourceDir: string, defaultLanguage?: string);
+    validate(): {
+        warnings: ValidationWarning[];
+        unusedKeys: string[];
+    };
+    private collectLocaleKeys;
+    private collectSourceContent;
+}
+
+interface ValidatorOptions {
+    localesDir: string;
+    sourceDir: string;
+    defaultLanguage?: string;
+    targetLanguages?: string[];
+    checkUnused?: boolean;
+    checkDuplicates?: boolean;
+    checkPlaceholders?: boolean;
+}
+declare class LocaleValidator {
+    private options;
+    constructor(options: ValidatorOptions);
+    validate(): ValidationResult;
+}
+
+export { DuplicateKeyValidator, LocaleValidator, MissingKeyValidator, PlaceholderValidator, UnusedKeyValidator, type ValidatorOptions };

package/dist/index.js

@@ -0,0 +1,257 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DuplicateKeyValidator: () => DuplicateKeyValidator,
+  LocaleValidator: () => LocaleValidator,
+  MissingKeyValidator: () => MissingKeyValidator,
+  PlaceholderValidator: () => PlaceholderValidator,
+  UnusedKeyValidator: () => UnusedKeyValidator
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/missing-key-validator.ts
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var import_shared = require("@ai-localize/shared");
+var MissingKeyValidator = class {
+  constructor(localesDir, defaultLanguage = "en", targetLanguages = []) {
+    this.localesDir = localesDir;
+    this.defaultLanguage = defaultLanguage;
+    this.targetLanguages = targetLanguages;
+  }
+  localesDir;
+  defaultLanguage;
+  targetLanguages;
+  validate() {
+    const errors = [];
+    const missingByLanguage = {};
+    const defaultDir = path.join(this.localesDir, this.defaultLanguage);
+    if (!fs.existsSync(defaultDir)) return { errors, missingByLanguage };
+    const nsFiles = fs.readdirSync(defaultDir).filter((f) => f.endsWith(".json"));
+    const langs = this.targetLanguages.length > 0 ? this.targetLanguages : fs.readdirSync(this.localesDir, { withFileTypes: true }).filter((e) => e.isDirectory() && e.name !== this.defaultLanguage).map((e) => e.name);
+    for (const nsFile of nsFiles) {
+      const defaultEntries = (0, import_shared.readJsonSafe)(path.join(defaultDir, nsFile));
+      if (!defaultEntries) continue;
+      const namespace = nsFile.replace(".json", "");
+      for (const lang of langs) {
+        const targetPath = path.join(this.localesDir, lang, nsFile);
+        const targetEntries = (0, import_shared.readJsonSafe)(targetPath) || {};
+        for (const key of Object.keys(defaultEntries)) {
+          if (!(key in targetEntries) || targetEntries[key] === "") {
+            const fullKey = `${namespace}.${key}`;
+            errors.push({ type: "missing-key", key: fullKey, language: lang, message: `Missing key "${fullKey}" in "${lang}"`, filePath: targetPath });
+            if (!missingByLanguage[lang]) missingByLanguage[lang] = [];
+            missingByLanguage[lang].push(fullKey);
+          }
+        }
+      }
+    }
+    return { errors, missingByLanguage };
+  }
+};
+
+// src/duplicate-key-validator.ts
+var fs2 = __toESM(require("fs"));
+var path2 = __toESM(require("path"));
+var import_shared2 = require("@ai-localize/shared");
+var DuplicateKeyValidator = class {
+  constructor(localesDir, defaultLanguage = "en") {
+    this.localesDir = localesDir;
+    this.defaultLanguage = defaultLanguage;
+  }
+  localesDir;
+  defaultLanguage;
+  validate() {
+    const errors = [];
+    const duplicates = [];
+    const defaultDir = path2.join(this.localesDir, this.defaultLanguage);
+    if (!fs2.existsSync(defaultDir)) return { errors, duplicates };
+    const nsFiles = fs2.readdirSync(defaultDir).filter((f) => f.endsWith(".json"));
+    for (const nsFile of nsFiles) {
+      const entries = (0, import_shared2.readJsonSafe)(path2.join(defaultDir, nsFile));
+      if (!entries) continue;
+      const namespace = nsFile.replace(".json", "");
+      const valueMap = /* @__PURE__ */ new Map();
+      for (const [key, value] of Object.entries(entries)) {
+        if (!value) continue;
+        const existing = valueMap.get(value) || [];
+        existing.push(key);
+        valueMap.set(value, existing);
+      }
+      for (const [value, keys] of valueMap) {
+        if (keys.length > 1) {
+          const fullKeys = keys.map((k) => `${namespace}.${k}`);
+          duplicates.push(...fullKeys);
+          errors.push({ type: "duplicate-key", key: fullKeys.join(", "), message: `Duplicate value "${value}" for: ${fullKeys.join(", ")}` });
+        }
+      }
+    }
+    return { errors, duplicates };
+  }
+};
+
+// src/placeholder-validator.ts
+var fs3 = __toESM(require("fs"));
+var path3 = __toESM(require("path"));
+var import_shared3 = require("@ai-localize/shared");
+var PATTERNS = [/\{\{([^}]+)\}\}/g, /\{([^}]+)\}/g, /%\(([^)]+)\)s/g, /%(\w+)/g];
+var PlaceholderValidator = class {
+  constructor(localesDir, defaultLanguage = "en") {
+    this.localesDir = localesDir;
+    this.defaultLanguage = defaultLanguage;
+  }
+  localesDir;
+  defaultLanguage;
+  validate() {
+    const errors = [];
+    const defaultDir = path3.join(this.localesDir, this.defaultLanguage);
+    if (!fs3.existsSync(defaultDir)) return errors;
+    const nsFiles = fs3.readdirSync(defaultDir).filter((f) => f.endsWith(".json"));
+    const langs = fs3.readdirSync(this.localesDir, { withFileTypes: true }).filter((e) => e.isDirectory() && e.name !== this.defaultLanguage).map((e) => e.name);
+    for (const nsFile of nsFiles) {
+      const defaultEntries = (0, import_shared3.readJsonSafe)(path3.join(defaultDir, nsFile));
+      if (!defaultEntries) continue;
+      const namespace = nsFile.replace(".json", "");
+      for (const lang of langs) {
+        const targetEntries = (0, import_shared3.readJsonSafe)(path3.join(this.localesDir, lang, nsFile)) || {};
+        for (const [key, defaultVal] of Object.entries(defaultEntries)) {
+          const targetVal = targetEntries[key];
+          if (!targetVal) continue;
+          const defPh = this.extract(defaultVal);
+          const tgtPh = this.extract(targetVal);
+          const missing = defPh.filter((p) => !tgtPh.includes(p));
+          const extra = tgtPh.filter((p) => !defPh.includes(p));
+          if (missing.length > 0 || extra.length > 0) {
+            errors.push({ type: "placeholder-mismatch", key: `${namespace}.${key}`, language: lang, message: `Placeholder mismatch in "${lang}": missing [${missing.join(", ")}], extra [${extra.join(", ")}]` });
+          }
+        }
+      }
+    }
+    return errors;
+  }
+  extract(value) {
+    const result = [];
+    for (const p of PATTERNS) {
+      p.lastIndex = 0;
+      let m;
+      while ((m = p.exec(value)) !== null) result.push(m[0]);
+    }
+    return [...new Set(result)];
+  }
+};
+
+// src/unused-key-validator.ts
+var fs4 = __toESM(require("fs"));
+var path4 = __toESM(require("path"));
+var import_shared4 = require("@ai-localize/shared");
+var UnusedKeyValidator = class {
+  constructor(localesDir, sourceDir, defaultLanguage = "en") {
+    this.localesDir = localesDir;
+    this.sourceDir = sourceDir;
+    this.defaultLanguage = defaultLanguage;
+  }
+  localesDir;
+  sourceDir;
+  defaultLanguage;
+  validate() {
+    const warnings = [];
+    const unusedKeys = [];
+    const allKeys = this.collectLocaleKeys();
+    const sourceContent = this.collectSourceContent();
+    for (const key of allKeys) {
+      const shortKey = key.includes(".") ? key.split(".").slice(1).join(".") : key;
+      const referenced = sourceContent.includes(`'${key}'`) || sourceContent.includes(`"${key}"`) || sourceContent.includes(`'${shortKey}'`) || sourceContent.includes(`"${shortKey}"`);
+      if (!referenced) {
+        unusedKeys.push(key);
+        warnings.push({ type: "unused-key", key, message: `Key "${key}" not referenced in source` });
+      }
+    }
+    return { warnings, unusedKeys };
+  }
+  collectLocaleKeys() {
+    const keys = [];
+    const defaultDir = path4.join(this.localesDir, this.defaultLanguage);
+    if (!fs4.existsSync(defaultDir)) return keys;
+    for (const file of fs4.readdirSync(defaultDir).filter((f) => f.endsWith(".json"))) {
+      const ns = file.replace(".json", "");
+      const entries = (0, import_shared4.readJsonSafe)(path4.join(defaultDir, file)) || {};
+      for (const key of Object.keys(entries)) keys.push(`${ns}.${key}`);
+    }
+    return keys;
+  }
+  collectSourceContent() {
+    const files = (0, import_shared4.collectFiles)(this.sourceDir, ["ts", "tsx", "js", "jsx", "vue", "html"], ["node_modules", "dist"]);
+    let content = "";
+    for (const f of files) {
+      try {
+        content += fs4.readFileSync(f, "utf-8") + "\n";
+      } catch {
+      }
+    }
+    return content;
+  }
+};
+
+// src/locale-validator.ts
+var LocaleValidator = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  validate() {
+    const errors = [];
+    const warnings = [];
+    const lang = this.options.defaultLanguage || "en";
+    const { errors: missingErrors } = new MissingKeyValidator(this.options.localesDir, lang, this.options.targetLanguages || []).validate();
+    errors.push(...missingErrors);
+    if (this.options.checkDuplicates !== false) {
+      const { errors: dupErrors } = new DuplicateKeyValidator(this.options.localesDir, lang).validate();
+      errors.push(...dupErrors);
+    }
+    if (this.options.checkPlaceholders !== false) {
+      errors.push(...new PlaceholderValidator(this.options.localesDir, lang).validate());
+    }
+    if (this.options.checkUnused !== false) {
+      const { warnings: unusedWarnings } = new UnusedKeyValidator(this.options.localesDir, this.options.sourceDir, lang).validate();
+      warnings.push(...unusedWarnings);
+    }
+    return { valid: errors.length === 0, errors, warnings };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DuplicateKeyValidator,
+  LocaleValidator,
+  MissingKeyValidator,
+  PlaceholderValidator,
+  UnusedKeyValidator
+});

package/dist/index.mjs

@@ -0,0 +1,216 @@
+// src/missing-key-validator.ts
+import * as fs from "fs";
+import * as path from "path";
+import { readJsonSafe } from "@ai-localize/shared";
+var MissingKeyValidator = class {
+  constructor(localesDir, defaultLanguage = "en", targetLanguages = []) {
+    this.localesDir = localesDir;
+    this.defaultLanguage = defaultLanguage;
+    this.targetLanguages = targetLanguages;
+  }
+  localesDir;
+  defaultLanguage;
+  targetLanguages;
+  validate() {
+    const errors = [];
+    const missingByLanguage = {};
+    const defaultDir = path.join(this.localesDir, this.defaultLanguage);
+    if (!fs.existsSync(defaultDir)) return { errors, missingByLanguage };
+    const nsFiles = fs.readdirSync(defaultDir).filter((f) => f.endsWith(".json"));
+    const langs = this.targetLanguages.length > 0 ? this.targetLanguages : fs.readdirSync(this.localesDir, { withFileTypes: true }).filter((e) => e.isDirectory() && e.name !== this.defaultLanguage).map((e) => e.name);
+    for (const nsFile of nsFiles) {
+      const defaultEntries = readJsonSafe(path.join(defaultDir, nsFile));
+      if (!defaultEntries) continue;
+      const namespace = nsFile.replace(".json", "");
+      for (const lang of langs) {
+        const targetPath = path.join(this.localesDir, lang, nsFile);
+        const targetEntries = readJsonSafe(targetPath) || {};
+        for (const key of Object.keys(defaultEntries)) {
+          if (!(key in targetEntries) || targetEntries[key] === "") {
+            const fullKey = `${namespace}.${key}`;
+            errors.push({ type: "missing-key", key: fullKey, language: lang, message: `Missing key "${fullKey}" in "${lang}"`, filePath: targetPath });
+            if (!missingByLanguage[lang]) missingByLanguage[lang] = [];
+            missingByLanguage[lang].push(fullKey);
+          }
+        }
+      }
+    }
+    return { errors, missingByLanguage };
+  }
+};
+
+// src/duplicate-key-validator.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+import { readJsonSafe as readJsonSafe2 } from "@ai-localize/shared";
+var DuplicateKeyValidator = class {
+  constructor(localesDir, defaultLanguage = "en") {
+    this.localesDir = localesDir;
+    this.defaultLanguage = defaultLanguage;
+  }
+  localesDir;
+  defaultLanguage;
+  validate() {
+    const errors = [];
+    const duplicates = [];
+    const defaultDir = path2.join(this.localesDir, this.defaultLanguage);
+    if (!fs2.existsSync(defaultDir)) return { errors, duplicates };
+    const nsFiles = fs2.readdirSync(defaultDir).filter((f) => f.endsWith(".json"));
+    for (const nsFile of nsFiles) {
+      const entries = readJsonSafe2(path2.join(defaultDir, nsFile));
+      if (!entries) continue;
+      const namespace = nsFile.replace(".json", "");
+      const valueMap = /* @__PURE__ */ new Map();
+      for (const [key, value] of Object.entries(entries)) {
+        if (!value) continue;
+        const existing = valueMap.get(value) || [];
+        existing.push(key);
+        valueMap.set(value, existing);
+      }
+      for (const [value, keys] of valueMap) {
+        if (keys.length > 1) {
+          const fullKeys = keys.map((k) => `${namespace}.${k}`);
+          duplicates.push(...fullKeys);
+          errors.push({ type: "duplicate-key", key: fullKeys.join(", "), message: `Duplicate value "${value}" for: ${fullKeys.join(", ")}` });
+        }
+      }
+    }
+    return { errors, duplicates };
+  }
+};
+
+// src/placeholder-validator.ts
+import * as fs3 from "fs";
+import * as path3 from "path";
+import { readJsonSafe as readJsonSafe3 } from "@ai-localize/shared";
+var PATTERNS = [/\{\{([^}]+)\}\}/g, /\{([^}]+)\}/g, /%\(([^)]+)\)s/g, /%(\w+)/g];
+var PlaceholderValidator = class {
+  constructor(localesDir, defaultLanguage = "en") {
+    this.localesDir = localesDir;
+    this.defaultLanguage = defaultLanguage;
+  }
+  localesDir;
+  defaultLanguage;
+  validate() {
+    const errors = [];
+    const defaultDir = path3.join(this.localesDir, this.defaultLanguage);
+    if (!fs3.existsSync(defaultDir)) return errors;
+    const nsFiles = fs3.readdirSync(defaultDir).filter((f) => f.endsWith(".json"));
+    const langs = fs3.readdirSync(this.localesDir, { withFileTypes: true }).filter((e) => e.isDirectory() && e.name !== this.defaultLanguage).map((e) => e.name);
+    for (const nsFile of nsFiles) {
+      const defaultEntries = readJsonSafe3(path3.join(defaultDir, nsFile));
+      if (!defaultEntries) continue;
+      const namespace = nsFile.replace(".json", "");
+      for (const lang of langs) {
+        const targetEntries = readJsonSafe3(path3.join(this.localesDir, lang, nsFile)) || {};
+        for (const [key, defaultVal] of Object.entries(defaultEntries)) {
+          const targetVal = targetEntries[key];
+          if (!targetVal) continue;
+          const defPh = this.extract(defaultVal);
+          const tgtPh = this.extract(targetVal);
+          const missing = defPh.filter((p) => !tgtPh.includes(p));
+          const extra = tgtPh.filter((p) => !defPh.includes(p));
+          if (missing.length > 0 || extra.length > 0) {
+            errors.push({ type: "placeholder-mismatch", key: `${namespace}.${key}`, language: lang, message: `Placeholder mismatch in "${lang}": missing [${missing.join(", ")}], extra [${extra.join(", ")}]` });
+          }
+        }
+      }
+    }
+    return errors;
+  }
+  extract(value) {
+    const result = [];
+    for (const p of PATTERNS) {
+      p.lastIndex = 0;
+      let m;
+      while ((m = p.exec(value)) !== null) result.push(m[0]);
+    }
+    return [...new Set(result)];
+  }
+};
+
+// src/unused-key-validator.ts
+import * as fs4 from "fs";
+import * as path4 from "path";
+import { readJsonSafe as readJsonSafe4, collectFiles } from "@ai-localize/shared";
+var UnusedKeyValidator = class {
+  constructor(localesDir, sourceDir, defaultLanguage = "en") {
+    this.localesDir = localesDir;
+    this.sourceDir = sourceDir;
+    this.defaultLanguage = defaultLanguage;
+  }
+  localesDir;
+  sourceDir;
+  defaultLanguage;
+  validate() {
+    const warnings = [];
+    const unusedKeys = [];
+    const allKeys = this.collectLocaleKeys();
+    const sourceContent = this.collectSourceContent();
+    for (const key of allKeys) {
+      const shortKey = key.includes(".") ? key.split(".").slice(1).join(".") : key;
+      const referenced = sourceContent.includes(`'${key}'`) || sourceContent.includes(`"${key}"`) || sourceContent.includes(`'${shortKey}'`) || sourceContent.includes(`"${shortKey}"`);
+      if (!referenced) {
+        unusedKeys.push(key);
+        warnings.push({ type: "unused-key", key, message: `Key "${key}" not referenced in source` });
+      }
+    }
+    return { warnings, unusedKeys };
+  }
+  collectLocaleKeys() {
+    const keys = [];
+    const defaultDir = path4.join(this.localesDir, this.defaultLanguage);
+    if (!fs4.existsSync(defaultDir)) return keys;
+    for (const file of fs4.readdirSync(defaultDir).filter((f) => f.endsWith(".json"))) {
+      const ns = file.replace(".json", "");
+      const entries = readJsonSafe4(path4.join(defaultDir, file)) || {};
+      for (const key of Object.keys(entries)) keys.push(`${ns}.${key}`);
+    }
+    return keys;
+  }
+  collectSourceContent() {
+    const files = collectFiles(this.sourceDir, ["ts", "tsx", "js", "jsx", "vue", "html"], ["node_modules", "dist"]);
+    let content = "";
+    for (const f of files) {
+      try {
+        content += fs4.readFileSync(f, "utf-8") + "\n";
+      } catch {
+      }
+    }
+    return content;
+  }
+};
+
+// src/locale-validator.ts
+var LocaleValidator = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  validate() {
+    const errors = [];
+    const warnings = [];
+    const lang = this.options.defaultLanguage || "en";
+    const { errors: missingErrors } = new MissingKeyValidator(this.options.localesDir, lang, this.options.targetLanguages || []).validate();
+    errors.push(...missingErrors);
+    if (this.options.checkDuplicates !== false) {
+      const { errors: dupErrors } = new DuplicateKeyValidator(this.options.localesDir, lang).validate();
+      errors.push(...dupErrors);
+    }
+    if (this.options.checkPlaceholders !== false) {
+      errors.push(...new PlaceholderValidator(this.options.localesDir, lang).validate());
+    }
+    if (this.options.checkUnused !== false) {
+      const { warnings: unusedWarnings } = new UnusedKeyValidator(this.options.localesDir, this.options.sourceDir, lang).validate();
+      warnings.push(...unusedWarnings);
+    }
+    return { valid: errors.length === 0, errors, warnings };
+  }
+};
+export {
+  DuplicateKeyValidator,
+  LocaleValidator,
+  MissingKeyValidator,
+  PlaceholderValidator,
+  UnusedKeyValidator
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "ai-localize-validators",
+  "version": "1.0.0",
+  "description": "Locale file validation engine",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "ai-localize-shared": "1.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.1"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src --ext .ts"
+  }
+}

package/src/__tests__/missing-key-validator.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { MissingKeyValidator } from '../missing-key-validator.js';
+
+let tmpDir: string;
+
+beforeAll(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ai-localize-test-'));
+  fs.mkdirSync(path.join(tmpDir, 'en'), { recursive: true });
+  fs.mkdirSync(path.join(tmpDir, 'fr'), { recursive: true });
+  fs.writeFileSync(
+    path.join(tmpDir, 'en', 'translation.json'),
+    JSON.stringify({ greeting: 'Hello', farewell: 'Goodbye' })
+  );
+  fs.writeFileSync(
+    path.join(tmpDir, 'fr', 'translation.json'),
+    JSON.stringify({ greeting: 'Bonjour' })
+  );
+});
+
+afterAll(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe('MissingKeyValidator', () => {
+  it('detects missing keys in target language', () => {
+    const validator = new MissingKeyValidator(tmpDir, 'en', ['fr']);
+    const { errors } = validator.validate();
+    expect(errors.length).toBeGreaterThan(0);
+    const missingFarewellInFr = errors.find((e) => e.key.includes('farewell') && e.language === 'fr');
+    expect(missingFarewellInFr).toBeDefined();
+  });
+
+  it('returns no errors when all keys present', () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'fr', 'translation.json'),
+      JSON.stringify({ greeting: 'Bonjour', farewell: 'Au revoir' })
+  );
+    const validator = new MissingKeyValidator(tmpDir, 'en', ['fr']);
+    const { errors } = validator.validate();
+    expect(errors.length).toBe(0);
+  });
+});

package/src/duplicate-key-validator.ts

@@ -0,0 +1,37 @@
+import * as fs from "fs";
+import * as path from "path";
+import type { ValidationError } from "@ai-localize/shared";
+import { readJsonSafe } from "@ai-localize/shared";
+
+export class DuplicateKeyValidator {
+  constructor(private localesDir: string, private defaultLanguage = "en") {}
+
+  validate(): { errors: ValidationError[]; duplicates: string[] } {
+    const errors: ValidationError[] = [];
+    const duplicates: string[] = [];
+    const defaultDir = path.join(this.localesDir, this.defaultLanguage);
+    if (!fs.existsSync(defaultDir)) return { errors, duplicates };
+
+    const nsFiles = fs.readdirSync(defaultDir).filter((f) => f.endsWith(".json"));
+    for (const nsFile of nsFiles) {
+      const entries = readJsonSafe<Record<string, string>>(path.join(defaultDir, nsFile));
+      if (!entries) continue;
+      const namespace = nsFile.replace(".json", "");
+  const valueMap = new Map<string, string[]>();
+      for (const [key, value] of Object.entries(entries)) {
+        if (!value) continue;
+        const existing = valueMap.get(value) || [];
+        existing.push(key);
+        valueMap.set(value, existing);
+      }
+      for (const [value, keys] of valueMap) {
+        if (keys.length > 1) {
+          const fullKeys = keys.map((k) => `${namespace}.${k}`);
+        duplicates.push(...fullKeys);
+          errors.push({ type: "duplicate-key", key: fullKeys.join(", "), message: `Duplicate value "${value}" for: ${fullKeys.join(", ")}` });
+        }
+  }
+    }
+    return { errors, duplicates };
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./missing-key-validator.js";
+export * from "./duplicate-key-validator.js";
+export * from "./placeholder-validator.js";
+export * from "./unused-key-validator.js";
+export * from "./locale-validator.js";

package/src/locale-validator.ts

@@ -0,0 +1,44 @@
+import type { ValidationResult } from "@ai-localize/shared";
+import { MissingKeyValidator } from "./missing-key-validator.js";
+import { DuplicateKeyValidator } from "./duplicate-key-validator.js";
+import { PlaceholderValidator } from "./placeholder-validator.js";
+import { UnusedKeyValidator } from "./unused-key-validator.js";
+
+export interface ValidatorOptions {
+  localesDir: string;
+  sourceDir: string;
+  defaultLanguage?: string;
+  targetLanguages?: string[];
+  checkUnused?: boolean;
+  checkDuplicates?: boolean;
+  checkPlaceholders?: boolean;
+}
+
+export class LocaleValidator {
+  constructor(private options: ValidatorOptions) {}
+
+  validate(): ValidationResult {
+    const errors: ValidationResult["errors"] = [];
+    const warnings: ValidationResult["warnings"] = [];
+    const lang = this.options.defaultLanguage || "en";
+
+    const { errors: missingErrors } = new MissingKeyValidator(this.options.localesDir, lang, this.options.targetLanguages || []).validate();
+    errors.push(...missingErrors);
+
+    if (this.options.checkDuplicates !== false) {
+      const { errors: dupErrors } = new DuplicateKeyValidator(this.options.localesDir, lang).validate();
+      errors.push(...dupErrors);
+    }
+
+    if (this.options.checkPlaceholders !== false) {
+      errors.push(...new PlaceholderValidator(this.options.localesDir, lang).validate());
+    }
+
+    if (this.options.checkUnused !== false) {
+      const { warnings: unusedWarnings } = new UnusedKeyValidator(this.options.localesDir, this.options.sourceDir, lang).validate();
+      warnings.push(...unusedWarnings);
+    }
+
+    return { valid: errors.length === 0, errors, warnings };
+  }
+}

package/src/missing-key-validator.ts

@@ -0,0 +1,46 @@
+import * as fs from "fs";
+import * as path from "path";
+import type { ValidationError } from "@ai-localize/shared";
+import { readJsonSafe } from "@ai-localize/shared";
+
+export class MissingKeyValidator {
+  constructor(
+    private localesDir: string,
+    private defaultLanguage = "en",
+    private targetLanguages: string[] = []
+  ) {}
+
+  validate(): { errors: ValidationError[]; missingByLanguage: Record<string, string[]> } {
+    const errors: ValidationError[] = [];
+    const missingByLanguage: Record<string, string[]> = {};
+
+    const defaultDir = path.join(this.localesDir, this.defaultLanguage);
+    if (!fs.existsSync(defaultDir)) return { errors, missingByLanguage };
+
+    const nsFiles = fs.readdirSync(defaultDir).filter((f) => f.endsWith(".json"));
+    const langs = this.targetLanguages.length > 0
+      ? this.targetLanguages
+    : fs.readdirSync(this.localesDir, { withFileTypes: true })
+          .filter((e) => e.isDirectory() && e.name !== this.defaultLanguage)
+          .map((e) => e.name);
+
+    for (const nsFile of nsFiles) {
+  const defaultEntries = readJsonSafe<Record<string, string>>(path.join(defaultDir, nsFile));
+      if (!defaultEntries) continue;
+      const namespace = nsFile.replace(".json", "");
+      for (const lang of langs) {
+        const targetPath = path.join(this.localesDir, lang, nsFile);
+    const targetEntries = readJsonSafe<Record<string, string>>(targetPath) || {};
+        for (const key of Object.keys(defaultEntries)) {
+    if (!(key in targetEntries) || targetEntries[key] === "") {
+   const fullKey = `${namespace}.${key}`;
+ errors.push({ type: "missing-key", key: fullKey, language: lang, message: `Missing key "${fullKey}" in "${lang}"`, filePath: targetPath });
+      if (!missingByLanguage[lang]) missingByLanguage[lang] = [];
+            missingByLanguage[lang].push(fullKey);
+    }
+        }
+      }
+    }
+    return { errors, missingByLanguage };
+  }
+}

package/src/placeholder-validator.ts

@@ -0,0 +1,48 @@
+import * as fs from "fs";
+import * as path from "path";
+import type { ValidationError } from "@ai-localize/shared";
+import { readJsonSafe } from "@ai-localize/shared";
+
+const PATTERNS = [/\{\{([^}]+)\}\}/g, /\{([^}]+)\}/g, /%\(([^)]+)\)s/g, /%(\w+)/g];
+
+export class PlaceholderValidator {
+  constructor(private localesDir: string, private defaultLanguage = "en") {}
+
+  validate(): ValidationError[] {
+    const errors: ValidationError[] = [];
+    const defaultDir = path.join(this.localesDir, this.defaultLanguage);
+    if (!fs.existsSync(defaultDir)) return errors;
+
+    const nsFiles = fs.readdirSync(defaultDir).filter((f) => f.endsWith(".json"));
+    const langs = fs.readdirSync(this.localesDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && e.name !== this.defaultLanguage)
+      .map((e) => e.name);
+
+    for (const nsFile of nsFiles) {
+      const defaultEntries = readJsonSafe<Record<string, string>>(path.join(defaultDir, nsFile));
+      if (!defaultEntries) continue;
+      const namespace = nsFile.replace(".json", "");
+      for (const lang of langs) {
+   const targetEntries = readJsonSafe<Record<string, string>>(path.join(this.localesDir, lang, nsFile)) || {};
+        for (const [key, defaultVal] of Object.entries(defaultEntries)) {
+      const targetVal = targetEntries[key];
+        if (!targetVal) continue;
+    const defPh = this.extract(defaultVal);
+        const tgtPh = this.extract(targetVal);
+     const missing = defPh.filter((p) => !tgtPh.includes(p));
+   const extra = tgtPh.filter((p) => !defPh.includes(p));
+    if (missing.length > 0 || extra.length > 0) {
+            errors.push({ type: "placeholder-mismatch", key: `${namespace}.${key}`, language: lang, message: `Placeholder mismatch in "${lang}": missing [${missing.join(", ")}], extra [${extra.join(", ")}]` });
+  }
+      }
+  }
+    }
+    return errors;
+  }
+
+  private extract(value: string): string[] {
+    const result: string[] = [];
+    for (const p of PATTERNS) { p.lastIndex = 0; let m; while ((m = p.exec(value)) !== null) result.push(m[0]); }
+    return [...new Set(result)];
+  }
+}

package/src/unused-key-validator.ts

@@ -0,0 +1,50 @@
+import * as fs from "fs";
+import * as path from "path";
+import type { ValidationWarning } from "@ai-localize/shared";
+import { readJsonSafe, collectFiles } from "@ai-localize/shared";
+
+export class UnusedKeyValidator {
+  constructor(
+    private localesDir: string,
+    private sourceDir: string,
+    private defaultLanguage = "en"
+  ) {}
+
+  validate(): { warnings: ValidationWarning[]; unusedKeys: string[] } {
+    const warnings: ValidationWarning[] = [];
+    const unusedKeys: string[] = [];
+    const allKeys = this.collectLocaleKeys();
+ const sourceContent = this.collectSourceContent();
+
+    for (const key of allKeys) {
+      const shortKey = key.includes(".") ? key.split(".").slice(1).join(".") : key;
+      const referenced =
+      sourceContent.includes(`'${key}'`) || sourceContent.includes(`"${key}"`) ||
+   sourceContent.includes(`'${shortKey}'`) || sourceContent.includes(`"${shortKey}"`);
+  if (!referenced) {
+  unusedKeys.push(key);
+ warnings.push({ type: "unused-key", key, message: `Key "${key}" not referenced in source` });
+ }
+    }
+    return { warnings, unusedKeys };
+  }
+
+  private collectLocaleKeys(): string[] {
+    const keys: string[] = [];
+    const defaultDir = path.join(this.localesDir, this.defaultLanguage);
+    if (!fs.existsSync(defaultDir)) return keys;
+    for (const file of fs.readdirSync(defaultDir).filter((f) => f.endsWith(".json"))) {
+      const ns = file.replace(".json", "");
+      const entries = readJsonSafe<Record<string, string>>(path.join(defaultDir, file)) || {};
+      for (const key of Object.keys(entries)) keys.push(`${ns}.${key}`);
+    }
+    return keys;
+  }
+
+  private collectSourceContent(): string {
+const files = collectFiles(this.sourceDir, ["ts", "tsx", "js", "jsx", "vue", "html"], ["node_modules", "dist"]);
+    let content = "";
+    for (const f of files) { try { content += fs.readFileSync(f, 'utf-8') + '\n'; } catch { /**/ } }
+    return content;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "outDir": "./dist", "rootDir": "./src" },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}