ai-localize-locale-engine 2.0.0 → 2.0.3

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # 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
+
+- Updated dependencies
+  - ai-localize-shared@2.0.1
+
 ## 2.0.0
 
 ### Major 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[];
@@ -20,6 +40,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 +63,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

@@ -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[];
@@ -20,6 +40,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 +63,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

@@ -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,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 +104,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 +139,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

@@ -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,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 +67,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 +102,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.3",
   "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.3"
   },
   "devDependencies": {
     "tsup": "^8.0.1",

package/src/extractor.ts

@@ -9,6 +9,26 @@ 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 {
@@ -20,16 +40,17 @@ export interface ExtractionResult {
 export class LocaleExtractor {
   private options: Required<ExtractOptions>;
 
-  constructor(options: 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 keyValueMap = new Map<string, string>();
     const existingKeys = new Set<string>();
 
     for (const dt of detectedTexts) {
@@ -38,22 +59,38 @@ 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;
     }
 
+    // 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(
+ namespaceMap.set(
         ns,
-        Object.fromEntries(Object.entries(entries).sort(([a], [b]) => a.localeCompare(b)))
+ Object.fromEntries(Object.entries(entries).sort(([a], [b]) => a.localeCompare(b)))
       );
     }
 
@@ -62,12 +99,14 @@ export class LocaleExtractor {
 
     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, ""]));
+        // 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/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;
   }