ai-localize-locale-engine 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # ai-localize-locale-engine
 
+## 2.0.1
+
+### Patch Changes
+
+- Updated dependencies
+  - ai-localize-shared@2.0.1
+
 ## 2.0.0
 
 ### Major Changes

package/dist/index.d.mts

@@ -20,6 +20,20 @@ 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";
 }
 declare class LocaleWriter {
     private options;
@@ -29,7 +43,23 @@ declare class LocaleWriter {
         merged: string[];
         created: string[];
     };
-    private resolveFilePath;
+    private writeNested;
+    private resolveNestedFilePath;
+    /**
+     * 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;
+    /**
+     * 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;
     private mergeEntries;
     private sort;
 }

package/dist/index.d.ts

@@ -20,6 +20,20 @@ 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";
 }
 declare class LocaleWriter {
     private options;
@@ -29,7 +43,23 @@ declare class LocaleWriter {
         merged: string[];
         created: string[];
     };
-    private resolveFilePath;
+    private writeNested;
+    private resolveNestedFilePath;
+    /**
+     * 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;
+    /**
+     * 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;
     private mergeEntries;
     private sort;
 }

package/dist/index.js

@@ -77,7 +77,7 @@ var LocaleExtractor = class {
     const allLanguages = [this.options.defaultLanguage, ...this.options.targetLanguages];
     for (const lang of allLanguages) {
       for (const [namespace, entries] of namespaceMap) {
-        const langEntries = lang === this.options.defaultLanguage ? { ...entries } : Object.fromEntries(Object.keys(entries).map((k) => [k, ""]));
+        const langEntries = { ...entries };
         localeFiles.push({ language: lang, namespace, entries: langEntries, filePath: "" });
       }
     }
@@ -91,14 +91,26 @@ var import_ai_localize_shared2 = require("ai-localize-shared");
 var LocaleWriter = class {
   options;
   constructor(options) {
-    this.options = { localesDir: options.localesDir, merge: options.merge ?? true, sort: options.sort ?? true };
+    this.options = {
+      localesDir: options.localesDir,
+      merge: options.merge ?? true,
+      sort: options.sort ?? true,
+      localeStructure: options.localeStructure ?? "nested"
+    };
   }
   write(localeFiles) {
+    if (this.options.localeStructure === "flat") {
+      return this.writeFlat(localeFiles);
+    }
+    return this.writeNested(localeFiles);
+  }
+  // ─── Nested layout ───────────────────────────────────────────────────────────
+  writeNested(localeFiles) {
     const written = [];
     const merged = [];
     const created = [];
     for (const lf of localeFiles) {
-      const filePath = this.resolveFilePath(lf);
+      const filePath = this.resolveNestedFilePath(lf);
       lf.filePath = filePath;
       (0, import_ai_localize_shared2.ensureDir)(path.dirname(filePath));
       const existing = (0, import_ai_localize_shared2.readJsonSafe)(filePath);
@@ -114,9 +126,67 @@ var LocaleWriter = class {
     }
     return { written, merged, created };
   }
-  resolveFilePath(lf) {
+  resolveNestedFilePath(lf) {
     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.
+    */
+  writeFlat(localeFiles) {
+    const byLanguage = /* @__PURE__ */ new Map();
+    for (const lf of localeFiles) {
+      const list = byLanguage.get(lf.language) ?? [];
+      list.push(lf);
+      byLanguage.set(lf.language, list);
+    }
+    const written = [];
+    const merged = [];
+    const created = [];
+    for (const [language, files] of byLanguage) {
+      const filePath = path.join(this.options.localesDir, `${language}.json`);
+      (0, import_ai_localize_shared2.ensureDir)(path.dirname(filePath));
+      const incomingEntries = {};
+      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 = (0, import_ai_localize_shared2.readJsonSafe)(filePath);
+      if (existing && this.options.merge) {
+        const mergedEntries = this.mergeEntries(existing, incomingEntries);
+        (0, import_ai_localize_shared2.writeJson)(filePath, this.options.sort ? this.sort(mergedEntries) : mergedEntries);
+        merged.push(filePath);
+      } else {
+        (0, import_ai_localize_shared2.writeJson)(filePath, this.options.sort ? this.sort(incomingEntries) : incomingEntries);
+        created.push(filePath);
+      }
+      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).
+    */
+  flattenKey(namespace, key) {
+    if (namespace === "common" || namespace === "translation") {
+      return key;
+    }
+    const prefix = `${namespace}.`;
+    return key.startsWith(prefix) ? key : `${prefix}${key}`;
+  }
+  // ─── Helpers ─────────────────────────────────────────────────────────────────
   mergeEntries(existing, incoming) {
     const result = { ...existing };
     for (const [key, value] of Object.entries(incoming)) {

package/dist/index.mjs

@@ -40,7 +40,7 @@ var LocaleExtractor = class {
     const allLanguages = [this.options.defaultLanguage, ...this.options.targetLanguages];
     for (const lang of allLanguages) {
       for (const [namespace, entries] of namespaceMap) {
-        const langEntries = lang === this.options.defaultLanguage ? { ...entries } : Object.fromEntries(Object.keys(entries).map((k) => [k, ""]));
+        const langEntries = { ...entries };
         localeFiles.push({ language: lang, namespace, entries: langEntries, filePath: "" });
       }
     }
@@ -54,14 +54,26 @@ import { writeJson, readJsonSafe, ensureDir } from "ai-localize-shared";
 var LocaleWriter = class {
   options;
   constructor(options) {
-    this.options = { localesDir: options.localesDir, merge: options.merge ?? true, sort: options.sort ?? true };
+    this.options = {
+      localesDir: options.localesDir,
+      merge: options.merge ?? true,
+      sort: options.sort ?? true,
+      localeStructure: options.localeStructure ?? "nested"
+    };
   }
   write(localeFiles) {
+    if (this.options.localeStructure === "flat") {
+      return this.writeFlat(localeFiles);
+    }
+    return this.writeNested(localeFiles);
+  }
+  // ─── Nested layout ───────────────────────────────────────────────────────────
+  writeNested(localeFiles) {
     const written = [];
     const merged = [];
     const created = [];
     for (const lf of localeFiles) {
-      const filePath = this.resolveFilePath(lf);
+      const filePath = this.resolveNestedFilePath(lf);
       lf.filePath = filePath;
       ensureDir(path.dirname(filePath));
       const existing = readJsonSafe(filePath);
@@ -77,9 +89,67 @@ var LocaleWriter = class {
     }
     return { written, merged, created };
   }
-  resolveFilePath(lf) {
+  resolveNestedFilePath(lf) {
     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.
+    */
+  writeFlat(localeFiles) {
+    const byLanguage = /* @__PURE__ */ new Map();
+    for (const lf of localeFiles) {
+      const list = byLanguage.get(lf.language) ?? [];
+      list.push(lf);
+      byLanguage.set(lf.language, list);
+    }
+    const written = [];
+    const merged = [];
+    const created = [];
+    for (const [language, files] of byLanguage) {
+      const filePath = path.join(this.options.localesDir, `${language}.json`);
+      ensureDir(path.dirname(filePath));
+      const incomingEntries = {};
+      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(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);
+      }
+      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).
+    */
+  flattenKey(namespace, key) {
+    if (namespace === "common" || namespace === "translation") {
+      return key;
+    }
+    const prefix = `${namespace}.`;
+    return key.startsWith(prefix) ? key : `${prefix}${key}`;
+  }
+  // ─── Helpers ─────────────────────────────────────────────────────────────────
   mergeEntries(existing, incoming) {
     const result = { ...existing };
     for (const [key, value] of Object.entries(incoming)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-localize-locale-engine",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Locale file generation, merging, deduplication and synchronization",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -13,7 +13,7 @@
     }
   },
   "dependencies": {
-    "ai-localize-shared": "2.0.0"
+    "ai-localize-shared": "2.0.1"
   },
   "devDependencies": {
     "tsup": "^8.0.1",

package/src/extractor.ts

@@ -38,36 +38,37 @@ export class LocaleExtractor {
         key = resolveKeyCollision(key, existingKeys);
       }
       existingKeys.add(key);
-   keyValueMap.set(key, dt.text);
+      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 };
+     : { 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,
+      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) {
-        const langEntries =
-          lang === this.options.defaultLanguage
-            ? { ...entries }
-            : Object.fromEntries(Object.keys(entries).map((k) => [k, ""]));
+   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/writer.ts

@@ -6,49 +6,154 @@ 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 };
+    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[] } {
-const written: 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.resolveFilePath(lf);
-  lf.filePath = filePath;
+      const filePath = this.resolveNestedFilePath(lf);
+      lf.filePath = filePath;
       ensureDir(path.dirname(filePath));
-      const existing = readJsonSafe<Record<string, string>>(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(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 };
+
+    return { written, merged, created };
   }
 
-  private resolveFilePath(lf: LocaleFile): string {
+  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, "translation.json")
       : path.join(this.options.localesDir, lf.language, `${lf.namespace}.json`);
   }
 
-  private mergeEntries(existing: Record<string, string>, incoming: Record<string, string>): Record<string, string> {
+  // ─── 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;
+    for (const [key, value] of Object.entries(incoming)) {
+      if (!(key in result) || result[key] === "") result[key] = value;
     }
     return result;
   }