ai-localize-locale-engine 2.0.1 → 2.0.3

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,

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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-localize-locale-engine",
-  "version": "2.0.1",
+  "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.1"
+    "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) {
@@ -45,30 +66,47 @@ export class LocaleExtractor {
     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(
-      ns,
-        Object.fromEntries(Object.entries(entries).sort(([a], [b]) => a.localeCompare(b)))
-   );
+ 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 };
+      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()) };