ai-localize-validators 2.0.4 → 2.0.6

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # ai-localize-validators
 
+## 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
+
+- **Bug fix — `validate` always reported "valid"**: `MissingKeyValidator` now correctly
+  detects un-translated keys when the extractor has seeded target language files with the
+  English source value (the `localeStructure` default behaviour introduced in 2.0.3).
+  Previously the check `targetValue === ""` never fired because values were non-empty strings;
+  the validator now adds a third condition — `targetValue === sourceValue` — so a key that
+  still holds its English placeholder is flagged as "Missing translation (value equals source)".
+  (`packages/validators/src/missing-key-validator.ts`)
+
+## 2.0.4
+
+### Patch Changes
+
+- Updated dependencies
+  - ai-localize-shared@2.0.4
+
 ## 2.0.3
 
 ### Patch Changes

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

@@ -66,9 +66,18 @@ var MissingKeyValidator = class {
         const targetPath = path.join(this.localesDir, lang, nsFile);
         const targetEntries = (0, import_ai_localize_shared.readJsonSafe)(targetPath) || {};
         for (const key of Object.keys(defaultEntries)) {
-          if (!(key in targetEntries) || targetEntries[key] === "") {
+          const sourceValue = defaultEntries[key];
+          const targetValue = targetEntries[key];
+          const isMissing = !(key in targetEntries) || targetValue === "" || targetValue !== void 0 && targetValue === sourceValue;
+          if (isMissing) {
             const fullKey = `${namespace}.${key}`;
-            errors.push({ type: "missing-key", key: fullKey, language: lang, message: `Missing key "${fullKey}" in "${lang}"`, filePath: targetPath });
+            errors.push({
+              type: "missing-key",
+              key: fullKey,
+              language: lang,
+              message: `Missing translation for "${fullKey}" in "${lang}" (value equals source)`,
+              filePath: targetPath
+            });
             if (!missingByLanguage[lang]) missingByLanguage[lang] = [];
             missingByLanguage[lang].push(fullKey);
           }

package/dist/index.mjs

@@ -26,9 +26,18 @@ var MissingKeyValidator = class {
         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 sourceValue = defaultEntries[key];
+          const targetValue = targetEntries[key];
+          const isMissing = !(key in targetEntries) || targetValue === "" || targetValue !== void 0 && targetValue === sourceValue;
+          if (isMissing) {
             const fullKey = `${namespace}.${key}`;
-            errors.push({ type: "missing-key", key: fullKey, language: lang, message: `Missing key "${fullKey}" in "${lang}"`, filePath: targetPath });
+            errors.push({
+              type: "missing-key",
+              key: fullKey,
+              language: lang,
+              message: `Missing translation for "${fullKey}" in "${lang}" (value equals source)`,
+              filePath: targetPath
+            });
             if (!missingByLanguage[lang]) missingByLanguage[lang] = [];
             missingByLanguage[lang].push(fullKey);
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-localize-validators",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Locale file validation engine — missing, duplicate, placeholder and unused key validators",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -33,7 +33,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "ai-localize-shared": "2.0.4"
+    "ai-localize-shared": "2.0.6"
   },
   "devDependencies": {
     "tsup": "^8.0.1",