ai-localize-validators 2.0.5 → 2.0.7

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # ai-localize-validators
 
+## 2.0.7
+
+### Minor Changes
+
+- **Two-pass `MissingKeyValidator`** — now validates both the default language file (checks
+  all keys exist and have non-empty values) and each target language file (checks keys exist,
+  are non-empty, and don't equal the source placeholder). Catches missing translations in the
+  source language itself.
+- **`UnusedKeyValidator` guards missing `sourceDir`** — no longer throws when `sourceDir`
+  does not exist; returns an empty unused-keys list instead.
+- **Backtick + last-segment key matching** — translation call detection now handles
+  template-literal keys and matches by last dot-separated segment for namespaced keys.
+
+### Patch Changes
+
+- Added `repository`, `homepage`, `bugs`, `author` fields to `package.json` for npm registry display.
+- Added `sideEffects: false` to enable tree-shaking in bundlers.
+- Added `prepublishOnly` script to ensure the package is built before publishing.
+
+## 2.0.6
+
+### Patch Changes
+
+- Add per-package README.md files so each package displays documentation on npmjs.com
+- Update README version badge to 2.0.6
+
 ## 2.0.5
 
 ### Patch Changes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 ai-localize-core contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# ai-localize-validators
+
+> Locale file validation — missing keys, duplicate values, placeholder mismatches, and unused keys — for the [ai-localize-core](https://github.com/ai-localize/ai-localize-core) platform.
+
+[![npm version](https://img.shields.io/npm/v/ai-localize-validators.svg)](https://www.npmjs.com/package/ai-localize-validators)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## What it does
+
+| Validator | Type | Description |
+|---|---|---|
+| `MissingKeyValidator` | Error | Finds keys absent in target languages **or** where the translated value still equals the English source placeholder |
+| `DuplicateKeyValidator` | Error | Finds keys sharing the same translated value within a namespace |
+| `PlaceholderValidator` | Error | Detects `{{var}}` / `{var}` / `%(var)s` / `%var` mismatches between source and target |
+| `UnusedKeyValidator` | Warning | Finds locale keys not referenced anywhere in source code |
+
+## Installation
+
+```bash
+npm install ai-localize-validators
+```
+
+## Usage
+
+```ts
+import { LocaleValidator } from 'ai-localize-validators';
+
+const validator = new LocaleValidator({
+  localesDir: './locales',
+  sourceDir: './src',
+  defaultLanguage: 'en',
+  targetLanguages: ['fr', 'de'],
+  checkUnused: true,
+  checkDuplicates: true,
+  checkPlaceholders: true,
+});
+
+const result = validator.validate();
+// result.valid    — boolean
+// result.errors   — ValidationError[]
+// result.warnings — ValidationWarning[]
+```
+
+## Missing key detection (v2.0.5+)
+
+A translation key is flagged as **missing** when ANY of these is true:
+
+1. The key is absent from the target language file
+2. The target value is an empty string `""`
+3. **The target value equals the source (English) value** — indicating it was auto-seeded by the extractor and not yet translated
+
+This third condition correctly catches keys seeded by `ai-localize extract` which copies the English value into target files as a placeholder. Error message:
+
+```
+[missing-key] Missing translation for "common.save" in "fr" (value equals source)
+```
+
+> **Intentionally identical values:** If a key is supposed to be the same across all languages (brand names, units, etc.), use `staticKeys` in your config instead of hardcoding the value. Static keys bypass the validator entirely.
+
+## Individual validators
+
+```ts
+import {
+  MissingKeyValidator,
+  DuplicateKeyValidator,
+  PlaceholderValidator,
+  UnusedKeyValidator,
+} from 'ai-localize-validators';
+
+const { errors, missingByLanguage } = new MissingKeyValidator(
+  './locales', 'en', ['fr', 'de']
+).validate();
+```
+
+---
+
+## Part of ai-localize-core
+
+Install the CLI for the complete toolset: `npm install -g ai-localize-cli`
+
+MIT © ai-localize-core contributors

package/dist/index.js

@@ -57,6 +57,28 @@ var MissingKeyValidator = class {
     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"));
+    for (const nsFile of nsFiles) {
+      const defaultFilePath = path.join(defaultDir, nsFile);
+      const defaultEntries = (0, import_ai_localize_shared.readJsonSafe)(defaultFilePath);
+      if (!defaultEntries) continue;
+      const namespace = nsFile.replace(".json", "");
+      for (const [key, value] of Object.entries(defaultEntries)) {
+        const isEmpty = value === null || value === void 0 || typeof value === "string" && value.trim() === "";
+        if (isEmpty) {
+          const fullKey = `${namespace}.${key}`;
+          errors.push({
+            type: "missing-key",
+            key: fullKey,
+            language: this.defaultLanguage,
+            message: `Default locale "${this.defaultLanguage}" has empty value for key "${fullKey}"`,
+            filePath: defaultFilePath
+          });
+          if (!missingByLanguage[this.defaultLanguage])
+            missingByLanguage[this.defaultLanguage] = [];
+          missingByLanguage[this.defaultLanguage].push(fullKey);
+        }
+      }
+    }
     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_ai_localize_shared.readJsonSafe)(path.join(defaultDir, nsFile));
@@ -75,7 +97,7 @@ var MissingKeyValidator = class {
               type: "missing-key",
               key: fullKey,
               language: lang,
-              message: `Missing translation for "${fullKey}" in "${lang}" (value equals source)`,
+              message: `Missing translation for "${fullKey}" in "${lang}"`,
               filePath: targetPath
             });
             if (!missingByLanguage[lang]) missingByLanguage[lang] = [];
@@ -194,11 +216,18 @@ var UnusedKeyValidator = class {
   validate() {
     const warnings = [];
     const unusedKeys = [];
+    if (!this.sourceDir || !fs4.existsSync(this.sourceDir)) {
+      return { warnings, unusedKeys };
+    }
     const allKeys = this.collectLocaleKeys();
+    if (allKeys.length === 0) return { warnings, unusedKeys };
     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}"`);
+      const parts = key.split(".");
+      const shortKey = parts.length > 1 ? parts.slice(1).join(".") : key;
+      const lastSegment = parts[parts.length - 1];
+      const referenced = sourceContent.includes(`'${key}'`) || sourceContent.includes(`"${key}"`) || sourceContent.includes("`" + key + "`") || sourceContent.includes(`'${shortKey}'`) || sourceContent.includes(`"${shortKey}"`) || sourceContent.includes("`" + shortKey + "`") || // Also match the last dot-segment alone (e.g. t('submitButton'))
+      lastSegment !== key && (sourceContent.includes(`'${lastSegment}'`) || sourceContent.includes(`"${lastSegment}"`) || sourceContent.includes("`" + lastSegment + "`"));
       if (!referenced) {
         unusedKeys.push(key);
         warnings.push({ type: "unused-key", key, message: `Key "${key}" not referenced in source` });

package/dist/index.mjs

@@ -17,6 +17,28 @@ var MissingKeyValidator = class {
     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"));
+    for (const nsFile of nsFiles) {
+      const defaultFilePath = path.join(defaultDir, nsFile);
+      const defaultEntries = readJsonSafe(defaultFilePath);
+      if (!defaultEntries) continue;
+      const namespace = nsFile.replace(".json", "");
+      for (const [key, value] of Object.entries(defaultEntries)) {
+        const isEmpty = value === null || value === void 0 || typeof value === "string" && value.trim() === "";
+        if (isEmpty) {
+          const fullKey = `${namespace}.${key}`;
+          errors.push({
+            type: "missing-key",
+            key: fullKey,
+            language: this.defaultLanguage,
+            message: `Default locale "${this.defaultLanguage}" has empty value for key "${fullKey}"`,
+            filePath: defaultFilePath
+          });
+          if (!missingByLanguage[this.defaultLanguage])
+            missingByLanguage[this.defaultLanguage] = [];
+          missingByLanguage[this.defaultLanguage].push(fullKey);
+        }
+      }
+    }
     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));
@@ -35,7 +57,7 @@ var MissingKeyValidator = class {
               type: "missing-key",
               key: fullKey,
               language: lang,
-              message: `Missing translation for "${fullKey}" in "${lang}" (value equals source)`,
+              message: `Missing translation for "${fullKey}" in "${lang}"`,
               filePath: targetPath
             });
             if (!missingByLanguage[lang]) missingByLanguage[lang] = [];
@@ -154,11 +176,18 @@ var UnusedKeyValidator = class {
   validate() {
     const warnings = [];
     const unusedKeys = [];
+    if (!this.sourceDir || !fs4.existsSync(this.sourceDir)) {
+      return { warnings, unusedKeys };
+    }
     const allKeys = this.collectLocaleKeys();
+    if (allKeys.length === 0) return { warnings, unusedKeys };
     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}"`);
+      const parts = key.split(".");
+      const shortKey = parts.length > 1 ? parts.slice(1).join(".") : key;
+      const lastSegment = parts[parts.length - 1];
+      const referenced = sourceContent.includes(`'${key}'`) || sourceContent.includes(`"${key}"`) || sourceContent.includes("`" + key + "`") || sourceContent.includes(`'${shortKey}'`) || sourceContent.includes(`"${shortKey}"`) || sourceContent.includes("`" + shortKey + "`") || // Also match the last dot-segment alone (e.g. t('submitButton'))
+      lastSegment !== key && (sourceContent.includes(`'${lastSegment}'`) || sourceContent.includes(`"${lastSegment}"`) || sourceContent.includes("`" + lastSegment + "`"));
       if (!referenced) {
         unusedKeys.push(key);
         warnings.push({ type: "unused-key", key, message: `Key "${key}" not referenced in source` });

package/package.json

@@ -1,10 +1,22 @@
 {
   "name": "ai-localize-validators",
-  "version": "2.0.5",
+  "version": "2.0.7",
   "description": "Locale file validation engine — missing, duplicate, placeholder and unused key validators",
+  "author": "ai-localize-core contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ai-localize/ai-localize-core.git",
+    "directory": "packages/validators"
+  },
+  "homepage": "https://github.com/ai-localize/ai-localize-core/tree/main/packages/validators#readme",
+  "bugs": {
+    "url": "https://github.com/ai-localize/ai-localize-core/issues"
+  },
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
+  "sideEffects": false,
   "files": [
     "dist",
     "README.md",
@@ -33,14 +45,13 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "ai-localize-shared": "2.0.5"
+    "ai-localize-shared": "2.0.7"
   },
   "devDependencies": {
     "tsup": "^8.0.1",
     "typescript": "^5.3.3",
     "vitest": "^1.2.1"
   },
-  "license": "MIT",
   "publishConfig": {
     "access": "public"
   },