ai-localize-locale-engine 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # ai-localize-locale-engine
 
+## 3.1.0
+
+### Minor Changes
+
+- **`copyDefaultValues` option in `LocaleExtractor`** — Added `copyDefaultValues?: boolean` to `ExtractOptions`. When `true`, target language locale files are pre-populated with the default language's source text values instead of empty strings. Defaults to `false` for backward compatibility.
+- **`copyDefaultValues` option in `LocaleSynchronizer`** — Added `SyncOptions` interface with `copyDefaultValues?: boolean`. When `true`, newly added keys in target language files are seeded from the default language file instead of using empty strings.
+
 ## 3.0.0
 
 ### Major Changes

package/dist/index.d.mts

@@ -24,6 +24,18 @@ interface ExtractOptions {
      * }
      */
     staticKeys?: Record<string, string>;
+    /**
+     * When `true`, target language locale files are pre-populated with the same
+     * source text values as the default language instead of empty strings.
+     *
+     * This ensures the app always has a visible fallback value while translators
+     * work on proper translations. Empty-string values cause the UI to show
+     * nothing at all for untranslated keys.
+     *
+     * Defaults to `false` to preserve backward-compatible behaviour (empty
+     * strings for target languages).
+     */
+    copyDefaultValues?: boolean;
 }
 interface ExtractionResult {
     localeFiles: LocaleFile[];
@@ -88,14 +100,29 @@ declare function deduplicateTexts(texts: DetectedText[]): DetectedText[];
 declare function filterAlreadyTranslated(texts: DetectedText[], existingKeys: Set<string>): DetectedText[];
 declare function findUnusedKeys(localeKeys: string[], sourceKeys: string[]): string[];
 
+interface SyncOptions {
+    /**
+     * When `true`, newly added keys in target language files are pre-populated
+     * with the same source text value from the default language file instead of
+     * an empty string.
+     *
+     * This ensures the app always has a visible fallback value while translators
+     * work on proper translations. Empty-string values cause the UI to show
+     * nothing at all for untranslated keys.
+     *
+     * Defaults to `false` to preserve backward-compatible behaviour.
+     */
+    copyDefaultValues?: boolean;
+}
 declare class LocaleSynchronizer {
     private localesDir;
     private defaultLanguage;
-    constructor(localesDir: string, defaultLanguage?: string);
+    private options;
+    constructor(localesDir: string, defaultLanguage?: string, options?: SyncOptions);
     sync(): {
         updated: string[];
         addedKeys: number;
     };
 }
 
-export { type ExtractOptions, type ExtractionResult, LocaleExtractor, LocaleSynchronizer, LocaleWriter, type WriteOptions, deduplicateTexts, filterAlreadyTranslated, findUnusedKeys };
+export { type ExtractOptions, type ExtractionResult, LocaleExtractor, LocaleSynchronizer, LocaleWriter, type SyncOptions, type WriteOptions, deduplicateTexts, filterAlreadyTranslated, findUnusedKeys };

package/dist/index.d.ts

@@ -24,6 +24,18 @@ interface ExtractOptions {
      * }
      */
     staticKeys?: Record<string, string>;
+    /**
+     * When `true`, target language locale files are pre-populated with the same
+     * source text values as the default language instead of empty strings.
+     *
+     * This ensures the app always has a visible fallback value while translators
+     * work on proper translations. Empty-string values cause the UI to show
+     * nothing at all for untranslated keys.
+     *
+     * Defaults to `false` to preserve backward-compatible behaviour (empty
+     * strings for target languages).
+     */
+    copyDefaultValues?: boolean;
 }
 interface ExtractionResult {
     localeFiles: LocaleFile[];
@@ -88,14 +100,29 @@ declare function deduplicateTexts(texts: DetectedText[]): DetectedText[];
 declare function filterAlreadyTranslated(texts: DetectedText[], existingKeys: Set<string>): DetectedText[];
 declare function findUnusedKeys(localeKeys: string[], sourceKeys: string[]): string[];
 
+interface SyncOptions {
+    /**
+     * When `true`, newly added keys in target language files are pre-populated
+     * with the same source text value from the default language file instead of
+     * an empty string.
+     *
+     * This ensures the app always has a visible fallback value while translators
+     * work on proper translations. Empty-string values cause the UI to show
+     * nothing at all for untranslated keys.
+     *
+     * Defaults to `false` to preserve backward-compatible behaviour.
+     */
+    copyDefaultValues?: boolean;
+}
 declare class LocaleSynchronizer {
     private localesDir;
     private defaultLanguage;
-    constructor(localesDir: string, defaultLanguage?: string);
+    private options;
+    constructor(localesDir: string, defaultLanguage?: string, options?: SyncOptions);
     sync(): {
         updated: string[];
         addedKeys: number;
     };
 }
 
-export { type ExtractOptions, type ExtractionResult, LocaleExtractor, LocaleSynchronizer, LocaleWriter, type WriteOptions, deduplicateTexts, filterAlreadyTranslated, findUnusedKeys };
+export { type ExtractOptions, type ExtractionResult, LocaleExtractor, LocaleSynchronizer, LocaleWriter, type SyncOptions, type WriteOptions, deduplicateTexts, filterAlreadyTranslated, findUnusedKeys };

package/dist/index.js

@@ -48,7 +48,8 @@ var LocaleExtractor = class {
       defaultLanguage: options.defaultLanguage || "en",
       targetLanguages: options.targetLanguages || [],
       namespaceSplitting: options.namespaceSplitting ?? true,
-      staticKeys: options.staticKeys ?? {}
+      staticKeys: options.staticKeys ?? {},
+      copyDefaultValues: options.copyDefaultValues ?? false
     };
   }
   extract(detectedTexts) {
@@ -91,7 +92,7 @@ var LocaleExtractor = class {
     for (const lang of allLanguages) {
       for (const [namespace, entries] of namespaceMap) {
         const isDefault = lang === this.options.defaultLanguage;
-        const langEntries = isDefault ? { ...entries } : Object.fromEntries(Object.keys(entries).map((k) => [k, ""]));
+        const langEntries = isDefault || this.options.copyDefaultValues ? { ...entries } : Object.fromEntries(Object.keys(entries).map((k) => [k, ""]));
         localeFiles.push({ language: lang, namespace, entries: langEntries, filePath: "" });
       }
     }
@@ -235,15 +236,18 @@ var fs = __toESM(require("fs"));
 var path2 = __toESM(require("path"));
 var import_ai_localize_shared3 = require("ai-localize-shared");
 var LocaleSynchronizer = class {
-  constructor(localesDir, defaultLanguage = "en") {
+  constructor(localesDir, defaultLanguage = "en", options = {}) {
     this.localesDir = localesDir;
     this.defaultLanguage = defaultLanguage;
+    this.options = options;
   }
   localesDir;
   defaultLanguage;
+  options;
   sync() {
     const updated = [];
     let addedKeys = 0;
+    const copyDefaultValues = this.options.copyDefaultValues ?? false;
     const defaultDir = path2.join(this.localesDir, this.defaultLanguage);
     if (!fs.existsSync(defaultDir)) return { updated, addedKeys };
     const defaultFiles = fs.readdirSync(defaultDir).filter((f) => f.endsWith(".json"));
@@ -258,7 +262,7 @@ var LocaleSynchronizer = class {
         let changed = false;
         for (const key of Object.keys(defaultEntries)) {
           if (!(key in existing)) {
-            existing[key] = "";
+            existing[key] = copyDefaultValues ? defaultEntries[key] ?? "" : "";
             addedKeys++;
             changed = true;
           }

package/dist/index.mjs

@@ -11,7 +11,8 @@ var LocaleExtractor = class {
       defaultLanguage: options.defaultLanguage || "en",
       targetLanguages: options.targetLanguages || [],
       namespaceSplitting: options.namespaceSplitting ?? true,
-      staticKeys: options.staticKeys ?? {}
+      staticKeys: options.staticKeys ?? {},
+      copyDefaultValues: options.copyDefaultValues ?? false
     };
   }
   extract(detectedTexts) {
@@ -54,7 +55,7 @@ var LocaleExtractor = class {
     for (const lang of allLanguages) {
       for (const [namespace, entries] of namespaceMap) {
         const isDefault = lang === this.options.defaultLanguage;
-        const langEntries = isDefault ? { ...entries } : Object.fromEntries(Object.keys(entries).map((k) => [k, ""]));
+        const langEntries = isDefault || this.options.copyDefaultValues ? { ...entries } : Object.fromEntries(Object.keys(entries).map((k) => [k, ""]));
         localeFiles.push({ language: lang, namespace, entries: langEntries, filePath: "" });
       }
     }
@@ -198,15 +199,18 @@ import * as fs from "fs";
 import * as path2 from "path";
 import { readJsonSafe as readJsonSafe2, writeJson as writeJson2, ensureDir as ensureDir2 } from "ai-localize-shared";
 var LocaleSynchronizer = class {
-  constructor(localesDir, defaultLanguage = "en") {
+  constructor(localesDir, defaultLanguage = "en", options = {}) {
     this.localesDir = localesDir;
     this.defaultLanguage = defaultLanguage;
+    this.options = options;
   }
   localesDir;
   defaultLanguage;
+  options;
   sync() {
     const updated = [];
     let addedKeys = 0;
+    const copyDefaultValues = this.options.copyDefaultValues ?? false;
     const defaultDir = path2.join(this.localesDir, this.defaultLanguage);
     if (!fs.existsSync(defaultDir)) return { updated, addedKeys };
     const defaultFiles = fs.readdirSync(defaultDir).filter((f) => f.endsWith(".json"));
@@ -221,7 +225,7 @@ var LocaleSynchronizer = class {
         let changed = false;
         for (const key of Object.keys(defaultEntries)) {
           if (!(key in existing)) {
-            existing[key] = "";
+            existing[key] = copyDefaultValues ? defaultEntries[key] ?? "" : "";
             addedKeys++;
             changed = true;
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-localize-locale-engine",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Locale file generation, merging, deduplication and synchronization",
   "author": "ai-localize-core contributors",
   "license": "MIT",