ai-localize-locale-engine 2.0.1 → 2.0.4

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # ai-localize-locale-engine
 
+## 2.0.3
+
+### Minor Changes
+
+- **`staticKeys` injection** — `Extractor` and `Writer` now merge `staticKeys` entries from config into every generated locale file; in nested mode they are placed in the default namespace file; in flat mode they are merged at the top level
+- **`keyStyle: "screaming_snake"` support** — `Extractor` honours the new `keyStyle` config field; when set to `"screaming_snake"` all scanned hardcoded text generates UPPER_SNAKE_CASE keys matching the text value
+
+### Patch Changes
+
+- Updated dependencies
+  - ai-localize-shared@2.0.3
+  - ai-localize-config@2.0.3
+
+## 2.0.2
+
+### Minor Changes
+
+- **Copy source value to target languages** — locale extract now initialises target language entries with the English source value instead of an empty string, so translators have immediate context
+- **Flat locale file layout** — `localeStructure: "flat"` writes one `<lang>.json` per language with all namespace keys merged; non-default namespace keys are prefixed with `<namespace>.` to avoid collisions
+
+### Patch Changes
+
+- Updated dependencies
+  - ai-localize-shared@2.0.2
+
 ## 2.0.1
 
 ### Patch Changes

package/dist/index.d.mts

@@ -4,6 +4,26 @@ interface ExtractOptions {
     defaultLanguage?: string;
     targetLanguages?: string[];
     namespaceSplitting?: boolean;
+    /**
+     * Static key/value pairs to inject into every generated locale file,
+     * in addition to the keys discovered by scanning source files.
+     *
+     * These keys are placed in the default namespace (`common` / `translation`)
+     * so they end up in `locales/<lang>/translation.json` (nested mode) or at
+     * the top level of `locales/<lang>.json` (flat mode).
+     *
+     * Static keys that collide with scanned keys are **skipped** — scanned
+     * keys always take precedence so existing translations are never overwritten.
+     *
+     * Example:
+     *   staticKeys: {
+     *     MAX_COUNT: "Max Count",
+     *     ALLOWED:   "Allowed",
+     *     DISABLED:  "Disabled",
+     *     UNLIMITED: "Unlimited",
+     * }
+     */
+    staticKeys?: Record<string, string>;
 }
 interface ExtractionResult {
     localeFiles: LocaleFile[];

package/dist/index.d.ts

@@ -4,6 +4,26 @@ interface ExtractOptions {
     defaultLanguage?: string;
     targetLanguages?: string[];
     namespaceSplitting?: boolean;
+    /**
+     * Static key/value pairs to inject into every generated locale file,
+     * in addition to the keys discovered by scanning source files.
+     *
+     * These keys are placed in the default namespace (`common` / `translation`)
+     * so they end up in `locales/<lang>/translation.json` (nested mode) or at
+     * the top level of `locales/<lang>.json` (flat mode).
+     *
+     * Static keys that collide with scanned keys are **skipped** — scanned
+     * keys always take precedence so existing translations are never overwritten.
+     *
+     * Example:
+     *   staticKeys: {
+     *     MAX_COUNT: "Max Count",
+     *     ALLOWED:   "Allowed",
+     *     DISABLED:  "Disabled",
+     *     UNLIMITED: "Unlimited",
+     * }
+     */
+    staticKeys?: Record<string, string>;
 }
 interface ExtractionResult {
     localeFiles: LocaleFile[];

package/dist/index.js

@@ -47,7 +47,8 @@ var LocaleExtractor = class {
     this.options = {
       defaultLanguage: options.defaultLanguage || "en",
       targetLanguages: options.targetLanguages || [],
-      namespaceSplitting: options.namespaceSplitting ?? true
+      namespaceSplitting: options.namespaceSplitting ?? true,
+      staticKeys: options.staticKeys ?? {}
     };
   }
   extract(detectedTexts) {
@@ -67,6 +68,18 @@ var LocaleExtractor = class {
       if (!namespaceMap.has(namespace)) namespaceMap.set(namespace, {});
       namespaceMap.get(namespace)[localKey] = value;
     }
+    const staticKeys = this.options.staticKeys;
+    if (staticKeys && Object.keys(staticKeys).length > 0) {
+      if (!namespaceMap.has(import_ai_localize_shared.DEFAULT_NAMESPACE)) {
+        namespaceMap.set(import_ai_localize_shared.DEFAULT_NAMESPACE, {});
+      }
+      const defaultNsBucket = namespaceMap.get(import_ai_localize_shared.DEFAULT_NAMESPACE);
+      for (const [key, value] of Object.entries(staticKeys)) {
+        if (!(key in defaultNsBucket)) {
+          defaultNsBucket[key] = value;
+        }
+      }
+    }
     for (const [ns, entries] of namespaceMap) {
       namespaceMap.set(
         ns,
@@ -77,7 +90,8 @@ var LocaleExtractor = class {
     const allLanguages = [this.options.defaultLanguage, ...this.options.targetLanguages];
     for (const lang of allLanguages) {
       for (const [namespace, entries] of namespaceMap) {
-        const langEntries = { ...entries };
+        const isDefault = lang === this.options.defaultLanguage;
+        const langEntries = isDefault ? { ...entries } : Object.fromEntries(Object.keys(entries).map((k) => [k, ""]));
         localeFiles.push({ language: lang, namespace, entries: langEntries, filePath: "" });
       }
     }

package/dist/index.mjs

@@ -10,7 +10,8 @@ var LocaleExtractor = class {
     this.options = {
       defaultLanguage: options.defaultLanguage || "en",
       targetLanguages: options.targetLanguages || [],
-      namespaceSplitting: options.namespaceSplitting ?? true
+      namespaceSplitting: options.namespaceSplitting ?? true,
+      staticKeys: options.staticKeys ?? {}
     };
   }
   extract(detectedTexts) {
@@ -30,6 +31,18 @@ var LocaleExtractor = class {
       if (!namespaceMap.has(namespace)) namespaceMap.set(namespace, {});
       namespaceMap.get(namespace)[localKey] = value;
     }
+    const staticKeys = this.options.staticKeys;
+    if (staticKeys && Object.keys(staticKeys).length > 0) {
+      if (!namespaceMap.has(DEFAULT_NAMESPACE)) {
+        namespaceMap.set(DEFAULT_NAMESPACE, {});
+      }
+      const defaultNsBucket = namespaceMap.get(DEFAULT_NAMESPACE);
+      for (const [key, value] of Object.entries(staticKeys)) {
+        if (!(key in defaultNsBucket)) {
+          defaultNsBucket[key] = value;
+        }
+      }
+    }
     for (const [ns, entries] of namespaceMap) {
       namespaceMap.set(
         ns,
@@ -40,7 +53,8 @@ var LocaleExtractor = class {
     const allLanguages = [this.options.defaultLanguage, ...this.options.targetLanguages];
     for (const lang of allLanguages) {
       for (const [namespace, entries] of namespaceMap) {
-        const langEntries = { ...entries };
+        const isDefault = lang === this.options.defaultLanguage;
+        const langEntries = isDefault ? { ...entries } : Object.fromEntries(Object.keys(entries).map((k) => [k, ""]));
         localeFiles.push({ language: lang, namespace, entries: langEntries, filePath: "" });
       }
     }

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "ai-localize-locale-engine",
-  "version": "2.0.1",
+  "version": "2.0.4",
   "description": "Locale file generation, merging, deduplication and synchronization",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -12,8 +17,23 @@
       "require": "./dist/index.js"
     }
   },
+  "keywords": [
+    "i18n",
+    "localization",
+    "l10n",
+    "internationalization",
+    "ai-localize",
+    "locale",
+    "locale-files",
+    "json",
+    "translation",
+    "extraction"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "dependencies": {
-    "ai-localize-shared": "2.0.1"
+    "ai-localize-shared": "2.0.4"
   },
   "devDependencies": {
     "tsup": "^8.0.1",

package/src/__tests__/extractor.test.ts

@@ -1,52 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { LocaleExtractor } from '../extractor.js';
-import type { DetectedText } from 'ai-localize-shared';
-
-const mockTexts: DetectedText[] = [
-  {
-    filePath: 'src/pages/Home.tsx',
-    line: 5,
-    column: 0,
-    text: 'Welcome to our app',
-    suggestedKey: 'pages.home.welcome_to_our_app',
-    context: 'jsx-text',
-    nodeType: 'JSXText',
-    alreadyTranslated: false,
-  },
-  {
-    filePath: 'src/components/Button.tsx',
-    line: 3,
-    column: 0,
-    text: 'Save',
-    suggestedKey: 'components.button.save',
-    context: 'jsx-text',
-    nodeType: 'JSXText',
-    alreadyTranslated: false,
-  },
-];
-
-describe('LocaleExtractor', () => {
-  it('extracts locale keys into locale files', () => {
-    const extractor = new LocaleExtractor({
-      defaultLanguage: 'en',
-      targetLanguages: ['fr'],
-      namespaceSplitting: true,
-    });
-  const { localeFiles, keyCount } = extractor.extract(mockTexts);
-    expect(keyCount).toBe(2);
-    expect(localeFiles.length).toBeGreaterThan(0);
-  });
-
-  it('creates empty entries for target languages', () => {
-    const extractor = new LocaleExtractor({
-   defaultLanguage: 'en',
-   targetLanguages: ['fr', 'de'],
-      namespaceSplitting: false,
-    });
-    const { localeFiles } = extractor.extract(mockTexts);
-    const frFiles = localeFiles.filter((f) => f.language === 'fr');
-    expect(frFiles.length).toBeGreaterThan(0);
-    const frEntries = Object.values(frFiles[0].entries);
-    expect(frEntries.every((v) => v === '')).toBe(true);
-  });
-});

package/src/deduplicator.ts

@@ -1,19 +0,0 @@
-import type { DetectedText } from "ai-localize-shared";
-
-export function deduplicateTexts(texts: DetectedText[]): DetectedText[] {
-  const seen = new Map<string, DetectedText>();
-  for (const dt of texts) {
-    const key = dt.text.toLowerCase().trim();
-    if (!seen.has(key)) seen.set(key, dt);
-  }
-  return Array.from(seen.values());
-}
-
-export function filterAlreadyTranslated(texts: DetectedText[], existingKeys: Set<string>): DetectedText[] {
-  return texts.filter((dt) => !existingKeys.has(dt.suggestedKey));
-}
-
-export function findUnusedKeys(localeKeys: string[], sourceKeys: string[]): string[] {
-  const sourceSet = new Set(sourceKeys);
-  return localeKeys.filter((k) => !sourceSet.has(k));
-}

package/src/extractor.ts

@@ -1,76 +0,0 @@
-import type { DetectedText, LocaleFile } from "ai-localize-shared";
-import {
-  splitKeyNamespace,
-  resolveKeyCollision,
-  DEFAULT_NAMESPACE,
-} from "ai-localize-shared";
-
-export interface ExtractOptions {
-  defaultLanguage?: string;
-  targetLanguages?: string[];
-  namespaceSplitting?: boolean;
-}
-
-export interface ExtractionResult {
-  localeFiles: LocaleFile[];
-  keyCount: number;
-  namespaces: string[];
-}
-
-export class LocaleExtractor {
-  private options: Required<ExtractOptions>;
-
-  constructor(options: ExtractOptions = {}) {
-    this.options = {
-      defaultLanguage: options.defaultLanguage || "en",
-      targetLanguages: options.targetLanguages || [],
-      namespaceSplitting: options.namespaceSplitting ?? true,
-    };
-  }
-
-  extract(detectedTexts: DetectedText[]): ExtractionResult {
-    const keyValueMap = new Map<string, string>();
-    const existingKeys = new Set<string>();
-
-    for (const dt of detectedTexts) {
-      let key = dt.suggestedKey;
-      if (keyValueMap.has(key) && keyValueMap.get(key) !== dt.text) {
-        key = resolveKeyCollision(key, existingKeys);
-      }
-      existingKeys.add(key);
-      keyValueMap.set(key, dt.text);
-    }
-
-    const namespaceMap = new Map<string, Record<string, string>>();
-    for (const [key, value] of keyValueMap) {
-      const { namespace, localKey } = this.options.namespaceSplitting
-        ? splitKeyNamespace(key)
-     : { namespace: DEFAULT_NAMESPACE, localKey: key };
-      if (!namespaceMap.has(namespace)) namespaceMap.set(namespace, {});
-      namespaceMap.get(namespace)![localKey] = value;
-    }
-
-    for (const [ns, entries] of namespaceMap) {
-      namespaceMap.set(
-      ns,
-        Object.fromEntries(Object.entries(entries).sort(([a], [b]) => a.localeCompare(b)))
-   );
-    }
-
-    const localeFiles: LocaleFile[] = [];
-    const allLanguages = [this.options.defaultLanguage, ...this.options.targetLanguages];
-
-    for (const lang of allLanguages) {
-   for (const [namespace, entries] of namespaceMap) {
-        // All languages get the source (English) value as the initial translation.
-     // This makes locale files immediately usable without blank values, and human
-     // translators can identify untranslated strings by comparing them to the
-      // default language file.
-  const langEntries = { ...entries };
-        localeFiles.push({ language: lang, namespace, entries: langEntries, filePath: "" });
- }
-    }
-
-    return { localeFiles, keyCount: keyValueMap.size, namespaces: Array.from(namespaceMap.keys()) };
-  }
-}

package/src/index.ts

@@ -1,4 +0,0 @@
-export * from "./extractor.js";
-export * from "./writer.js";
-export * from "./deduplicator.js";
-export * from "./synchronizer.js";

package/src/synchronizer.ts

@@ -1,36 +0,0 @@
-import * as fs from "fs";
-import * as path from "path";
-import { readJsonSafe, writeJson, ensureDir } from "ai-localize-shared";
-
-export class LocaleSynchronizer {
-  constructor(private localesDir: string, private defaultLanguage = "en") {}
-
-  sync(): { updated: string[]; addedKeys: number } {
-    const updated: string[] = [];
-    let addedKeys = 0;
-    const defaultDir = path.join(this.localesDir, this.defaultLanguage);
-    if (!fs.existsSync(defaultDir)) return { updated, addedKeys };
-
-    const defaultFiles = fs.readdirSync(defaultDir).filter((f) => f.endsWith(".json"));
-    const langDirs = fs
-      .readdirSync(this.localesDir, { withFileTypes: true })
- .filter((e) => e.isDirectory() && e.name !== this.defaultLanguage)
-      .map((e) => e.name);
-
-    for (const namespace of defaultFiles) {
-      const defaultEntries = readJsonSafe<Record<string, string>>(path.join(defaultDir, namespace));
-if (!defaultEntries) continue;
-      for (const lang of langDirs) {
-  const targetPath = path.join(this.localesDir, lang, namespace);
-        ensureDir(path.dirname(targetPath));
-        const existing = readJsonSafe<Record<string, string>>(targetPath) || {};
-        let changed = false;
-        for (const key of Object.keys(defaultEntries)) {
-    if (!(key in existing)) { existing[key] = ""; addedKeys++; changed = true; }
-        }
-        if (changed) { writeJson(targetPath, existing); updated.push(targetPath); }
-      }
-    }
-  return { updated, addedKeys };
-  }
-}

package/src/writer.ts

@@ -1,164 +0,0 @@
-import * as path from "path";
-import type { LocaleFile } from "ai-localize-shared";
-import { writeJson, readJsonSafe, ensureDir } from "ai-localize-shared";
-
-export interface WriteOptions {
-  localesDir: string;
-  merge?: boolean;
-  sort?: boolean;
-  /**
-   * Locale file layout.
-   *
-   * - `"nested"` (default) — one JSON file per language + namespace:
-   *     `locales/en/common.json`, `locales/en/dashboard.json`
-   *   For the "common" / default namespace the file is named `translation.json`.
-   *
-   * - `"flat"` — one JSON file per language, all namespaces merged:
-   *     `locales/en.json`, `locales/fr.json`
-   *     Namespace prefixes are prepended to keys to avoid collisions:
-   *     `common.button.save`, `dashboard.header.title`
-   *     (keys that already start with the namespace prefix are left as-is).
-   */
-  localeStructure?: "nested" | "flat";
-}
-
-export class LocaleWriter {
-  private options: Required<WriteOptions>;
-
-  constructor(options: WriteOptions) {
-    this.options = {
-localesDir: options.localesDir,
-      merge: options.merge ?? true,
-      sort: options.sort ?? true,
-      localeStructure: options.localeStructure ?? "nested",
-    };
-  }
-
-  write(localeFiles: LocaleFile[]): { written: string[]; merged: string[]; created: string[] } {
-    if (this.options.localeStructure === "flat") {
-      return this.writeFlat(localeFiles);
-    }
-    return this.writeNested(localeFiles);
-  }
-
-  // ─── Nested layout ───────────────────────────────────────────────────────────
-
-  private writeNested(localeFiles: LocaleFile[]): { written: string[]; merged: string[]; created: string[] } {
-    const written: string[] = [];
-    const merged: string[] = [];
-    const created: string[] = [];
-
-    for (const lf of localeFiles) {
-      const filePath = this.resolveNestedFilePath(lf);
-      lf.filePath = filePath;
-      ensureDir(path.dirname(filePath));
-    const existing = readJsonSafe<Record<string, string>>(filePath);
-
-      if (existing && this.options.merge) {
-        const mergedEntries = this.mergeEntries(existing, lf.entries);
-      writeJson(filePath, this.options.sort ? this.sort(mergedEntries) : mergedEntries);
-        merged.push(filePath);
-   } else {
-        writeJson(filePath, this.options.sort ? this.sort(lf.entries) : lf.entries);
-        created.push(filePath);
-      }
-      written.push(filePath);
-    }
-
-    return { written, merged, created };
-  }
-
-  private resolveNestedFilePath(lf: LocaleFile): string {
-    return lf.namespace === "common"
-    ? path.join(this.options.localesDir, lf.language, "translation.json")
-      : path.join(this.options.localesDir, lf.language, `${lf.namespace}.json`);
-  }
-
-  // ─── Flat layout ─────────────────────────────────────────────────────────────
-
-  /**
-   * In flat mode all LocaleFile entries for the same language are merged into
-   * a single `<localesDir>/<language>.json` file.
-   *
-   * To avoid key collisions between namespaces, each key is prefixed with its
- * namespace name (e.g. `common.button.save`, `dashboard.header.title`).
-   * Keys that already start with the namespace prefix are left unchanged.
-   */
-  private writeFlat(localeFiles: LocaleFile[]): { written: string[]; merged: string[]; created: string[] } {
-    // Group locale files by language
-    const byLanguage = new Map<string, LocaleFile[]>();
- for (const lf of localeFiles) {
-      const list = byLanguage.get(lf.language) ?? [];
-      list.push(lf);
- byLanguage.set(lf.language, list);
-    }
-
-    const written: string[] = [];
-    const merged: string[] = [];
-    const created: string[] = [];
-
-    for (const [language, files] of byLanguage) {
-      const filePath = path.join(this.options.localesDir, `${language}.json`);
-      ensureDir(path.dirname(filePath));
-
-      // Merge all namespace entries into a single flat object
-      const incomingEntries: Record<string, string> = {};
-      for (const lf of files) {
-        for (const [key, value] of Object.entries(lf.entries)) {
-          const flatKey = this.flattenKey(lf.namespace, key);
-          incomingEntries[flatKey] = value;
-        }
-      }
-
-      const existing = readJsonSafe<Record<string, string>>(filePath);
-      if (existing && this.options.merge) {
-        const mergedEntries = this.mergeEntries(existing, incomingEntries);
-        writeJson(filePath, this.options.sort ? this.sort(mergedEntries) : mergedEntries);
-        merged.push(filePath);
-    } else {
-    writeJson(filePath, this.options.sort ? this.sort(incomingEntries) : incomingEntries);
-        created.push(filePath);
-    }
-
-      // Update filePath on each LocaleFile for reference
-      for (const lf of files) {
-        lf.filePath = filePath;
-  }
-
-      written.push(filePath);
-    }
-
-    return { written, merged, created };
-  }
-
-  /**
-   * Produces a flat key with the namespace prepended.
-   * If the key already starts with `<namespace>.` it is returned as-is
- * to avoid double-prefixing (e.g. when namespace splitting already embedded it).
-   */
-  private flattenKey(namespace: string, key: string): string {
-    // "common" is the default namespace — don't prepend to avoid verbose keys
-    if (namespace === "common" || namespace === "translation") {
-      return key;
-    }
-    const prefix = `${namespace}.`;
-    return key.startsWith(prefix) ? key : `${prefix}${key}`;
-  }
-
-  // ─── Helpers ─────────────────────────────────────────────────────────────────
-
-  private mergeEntries(
-    existing: Record<string, string>,
-    incoming: Record<string, string>
-  ): Record<string, string> {
-    const result = { ...existing };
-    for (const [key, value] of Object.entries(incoming)) {
-      if (!(key in result) || result[key] === "") result[key] = value;
-    }
-    return result;
-  }
-
-  private sort(entries: Record<string, string>): Record<string, string> {
-    return Object.fromEntries(Object.entries(entries).sort(([a], [b]) => a.localeCompare(b)));
-  }
-}

package/tsconfig.json

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