ai-localize-locale-engine 2.0.3 → 2.0.5

package/dist/index.js

@@ -90,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

@@ -53,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.3",
+  "version": "2.0.5",
   "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.3"
+    "ai-localize-shared": "2.0.5"
   },
   "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,114 +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;
-  /**
-   * 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>;
-}
-
-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,
-      staticKeys: options.staticKeys ?? {},
-    };
-  }
-
-  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;
-    }
-
-    // Inject static keys into the default namespace.
-    // Scanned keys take precedence — static keys are only added when the key
-    // does not already exist in the default namespace bucket.
-    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,
- 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) {
-        // Default language gets the source text values.
-        // Target languages get empty string values so translators can fill them in.
-        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: "" });
-      }
-    }
-
-    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"]
-}