ai-localize-locale-engine 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,51 @@
+import { LocaleFile, DetectedText } from '@ai-localize/shared';
+
+interface ExtractOptions {
+    defaultLanguage?: string;
+    targetLanguages?: string[];
+    namespaceSplitting?: boolean;
+}
+interface ExtractionResult {
+    localeFiles: LocaleFile[];
+    keyCount: number;
+    namespaces: string[];
+}
+declare class LocaleExtractor {
+    private options;
+    constructor(options?: ExtractOptions);
+    extract(detectedTexts: DetectedText[]): ExtractionResult;
+}
+
+interface WriteOptions {
+    localesDir: string;
+    merge?: boolean;
+    sort?: boolean;
+}
+declare class LocaleWriter {
+    private options;
+    constructor(options: WriteOptions);
+    write(localeFiles: LocaleFile[]): {
+        written: string[];
+        merged: string[];
+        created: string[];
+    };
+    private resolveFilePath;
+    private mergeEntries;
+    private sort;
+}
+
+declare function deduplicateTexts(texts: DetectedText[]): DetectedText[];
+declare function filterAlreadyTranslated(texts: DetectedText[], existingKeys: Set<string>): DetectedText[];
+declare function findUnusedKeys(localeKeys: string[], sourceKeys: string[]): string[];
+
+declare class LocaleSynchronizer {
+    private localesDir;
+    private defaultLanguage;
+    constructor(localesDir: string, defaultLanguage?: string);
+    sync(): {
+        updated: string[];
+        addedKeys: number;
+    };
+}
+
+export { type ExtractOptions, type ExtractionResult, LocaleExtractor, LocaleSynchronizer, LocaleWriter, type WriteOptions, deduplicateTexts, filterAlreadyTranslated, findUnusedKeys };

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+import { LocaleFile, DetectedText } from '@ai-localize/shared';
+
+interface ExtractOptions {
+    defaultLanguage?: string;
+    targetLanguages?: string[];
+    namespaceSplitting?: boolean;
+}
+interface ExtractionResult {
+    localeFiles: LocaleFile[];
+    keyCount: number;
+    namespaces: string[];
+}
+declare class LocaleExtractor {
+    private options;
+    constructor(options?: ExtractOptions);
+    extract(detectedTexts: DetectedText[]): ExtractionResult;
+}
+
+interface WriteOptions {
+    localesDir: string;
+    merge?: boolean;
+    sort?: boolean;
+}
+declare class LocaleWriter {
+    private options;
+    constructor(options: WriteOptions);
+    write(localeFiles: LocaleFile[]): {
+        written: string[];
+        merged: string[];
+        created: string[];
+    };
+    private resolveFilePath;
+    private mergeEntries;
+    private sort;
+}
+
+declare function deduplicateTexts(texts: DetectedText[]): DetectedText[];
+declare function filterAlreadyTranslated(texts: DetectedText[], existingKeys: Set<string>): DetectedText[];
+declare function findUnusedKeys(localeKeys: string[], sourceKeys: string[]): string[];
+
+declare class LocaleSynchronizer {
+    private localesDir;
+    private defaultLanguage;
+    constructor(localesDir: string, defaultLanguage?: string);
+    sync(): {
+        updated: string[];
+        addedKeys: number;
+    };
+}
+
+export { type ExtractOptions, type ExtractionResult, LocaleExtractor, LocaleSynchronizer, LocaleWriter, type WriteOptions, deduplicateTexts, filterAlreadyTranslated, findUnusedKeys };

package/dist/index.js

@@ -0,0 +1,199 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  LocaleExtractor: () => LocaleExtractor,
+  LocaleSynchronizer: () => LocaleSynchronizer,
+  LocaleWriter: () => LocaleWriter,
+  deduplicateTexts: () => deduplicateTexts,
+  filterAlreadyTranslated: () => filterAlreadyTranslated,
+  findUnusedKeys: () => findUnusedKeys
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/extractor.ts
+var import_shared = require("@ai-localize/shared");
+var LocaleExtractor = class {
+  options;
+  constructor(options = {}) {
+    this.options = {
+      defaultLanguage: options.defaultLanguage || "en",
+      targetLanguages: options.targetLanguages || [],
+      namespaceSplitting: options.namespaceSplitting ?? true
+    };
+  }
+  extract(detectedTexts) {
+    const keyValueMap = /* @__PURE__ */ new Map();
+    const existingKeys = /* @__PURE__ */ new Set();
+    for (const dt of detectedTexts) {
+      let key = dt.suggestedKey;
+      if (keyValueMap.has(key) && keyValueMap.get(key) !== dt.text) {
+        key = (0, import_shared.resolveKeyCollision)(key, existingKeys);
+      }
+      existingKeys.add(key);
+      keyValueMap.set(key, dt.text);
+    }
+    const namespaceMap = /* @__PURE__ */ new Map();
+    for (const [key, value] of keyValueMap) {
+      const { namespace, localKey } = this.options.namespaceSplitting ? (0, import_shared.splitKeyNamespace)(key) : { namespace: import_shared.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,
+        Object.fromEntries(Object.entries(entries).sort(([a], [b]) => a.localeCompare(b)))
+      );
+    }
+    const localeFiles = [];
+    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, ""]));
+        localeFiles.push({ language: lang, namespace, entries: langEntries, filePath: "" });
+      }
+    }
+    return { localeFiles, keyCount: keyValueMap.size, namespaces: Array.from(namespaceMap.keys()) };
+  }
+};
+
+// src/writer.ts
+var path = __toESM(require("path"));
+var import_shared2 = require("@ai-localize/shared");
+var LocaleWriter = class {
+  options;
+  constructor(options) {
+    this.options = { localesDir: options.localesDir, merge: options.merge ?? true, sort: options.sort ?? true };
+  }
+  write(localeFiles) {
+    const written = [];
+    const merged = [];
+    const created = [];
+    for (const lf of localeFiles) {
+      const filePath = this.resolveFilePath(lf);
+      lf.filePath = filePath;
+      (0, import_shared2.ensureDir)(path.dirname(filePath));
+      const existing = (0, import_shared2.readJsonSafe)(filePath);
+      if (existing && this.options.merge) {
+        const mergedEntries = this.mergeEntries(existing, lf.entries);
+        (0, import_shared2.writeJson)(filePath, this.options.sort ? this.sort(mergedEntries) : mergedEntries);
+        merged.push(filePath);
+      } else {
+        (0, import_shared2.writeJson)(filePath, this.options.sort ? this.sort(lf.entries) : lf.entries);
+        created.push(filePath);
+      }
+      written.push(filePath);
+    }
+    return { written, merged, created };
+  }
+  resolveFilePath(lf) {
+    return lf.namespace === "common" ? path.join(this.options.localesDir, lf.language, "translation.json") : path.join(this.options.localesDir, lf.language, `${lf.namespace}.json`);
+  }
+  mergeEntries(existing, incoming) {
+    const result = { ...existing };
+    for (const [key, value] of Object.entries(incoming)) {
+      if (!(key in result) || result[key] === "") result[key] = value;
+    }
+    return result;
+  }
+  sort(entries) {
+    return Object.fromEntries(Object.entries(entries).sort(([a], [b]) => a.localeCompare(b)));
+  }
+};
+
+// src/deduplicator.ts
+function deduplicateTexts(texts) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const dt of texts) {
+    const key = dt.text.toLowerCase().trim();
+    if (!seen.has(key)) seen.set(key, dt);
+  }
+  return Array.from(seen.values());
+}
+function filterAlreadyTranslated(texts, existingKeys) {
+  return texts.filter((dt) => !existingKeys.has(dt.suggestedKey));
+}
+function findUnusedKeys(localeKeys, sourceKeys) {
+  const sourceSet = new Set(sourceKeys);
+  return localeKeys.filter((k) => !sourceSet.has(k));
+}
+
+// src/synchronizer.ts
+var fs = __toESM(require("fs"));
+var path2 = __toESM(require("path"));
+var import_shared3 = require("@ai-localize/shared");
+var LocaleSynchronizer = class {
+  constructor(localesDir, defaultLanguage = "en") {
+    this.localesDir = localesDir;
+    this.defaultLanguage = defaultLanguage;
+  }
+  localesDir;
+  defaultLanguage;
+  sync() {
+    const updated = [];
+    let addedKeys = 0;
+    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"));
+    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 = (0, import_shared3.readJsonSafe)(path2.join(defaultDir, namespace));
+      if (!defaultEntries) continue;
+      for (const lang of langDirs) {
+        const targetPath = path2.join(this.localesDir, lang, namespace);
+        (0, import_shared3.ensureDir)(path2.dirname(targetPath));
+        const existing = (0, import_shared3.readJsonSafe)(targetPath) || {};
+        let changed = false;
+        for (const key of Object.keys(defaultEntries)) {
+          if (!(key in existing)) {
+            existing[key] = "";
+            addedKeys++;
+            changed = true;
+          }
+        }
+        if (changed) {
+          (0, import_shared3.writeJson)(targetPath, existing);
+          updated.push(targetPath);
+        }
+      }
+    }
+    return { updated, addedKeys };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LocaleExtractor,
+  LocaleSynchronizer,
+  LocaleWriter,
+  deduplicateTexts,
+  filterAlreadyTranslated,
+  findUnusedKeys
+});

package/dist/index.mjs

@@ -0,0 +1,161 @@
+// src/extractor.ts
+import {
+  splitKeyNamespace,
+  resolveKeyCollision,
+  DEFAULT_NAMESPACE
+} from "@ai-localize/shared";
+var LocaleExtractor = class {
+  options;
+  constructor(options = {}) {
+    this.options = {
+      defaultLanguage: options.defaultLanguage || "en",
+      targetLanguages: options.targetLanguages || [],
+      namespaceSplitting: options.namespaceSplitting ?? true
+    };
+  }
+  extract(detectedTexts) {
+    const keyValueMap = /* @__PURE__ */ new Map();
+    const existingKeys = /* @__PURE__ */ new Set();
+    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 = /* @__PURE__ */ new Map();
+    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;
+    }
+    for (const [ns, entries] of namespaceMap) {
+      namespaceMap.set(
+        ns,
+        Object.fromEntries(Object.entries(entries).sort(([a], [b]) => a.localeCompare(b)))
+      );
+    }
+    const localeFiles = [];
+    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, ""]));
+        localeFiles.push({ language: lang, namespace, entries: langEntries, filePath: "" });
+      }
+    }
+    return { localeFiles, keyCount: keyValueMap.size, namespaces: Array.from(namespaceMap.keys()) };
+  }
+};
+
+// src/writer.ts
+import * as path from "path";
+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 };
+  }
+  write(localeFiles) {
+    const written = [];
+    const merged = [];
+    const created = [];
+    for (const lf of localeFiles) {
+      const filePath = this.resolveFilePath(lf);
+      lf.filePath = filePath;
+      ensureDir(path.dirname(filePath));
+      const existing = readJsonSafe(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 };
+  }
+  resolveFilePath(lf) {
+    return lf.namespace === "common" ? path.join(this.options.localesDir, lf.language, "translation.json") : path.join(this.options.localesDir, lf.language, `${lf.namespace}.json`);
+  }
+  mergeEntries(existing, incoming) {
+    const result = { ...existing };
+    for (const [key, value] of Object.entries(incoming)) {
+      if (!(key in result) || result[key] === "") result[key] = value;
+    }
+    return result;
+  }
+  sort(entries) {
+    return Object.fromEntries(Object.entries(entries).sort(([a], [b]) => a.localeCompare(b)));
+  }
+};
+
+// src/deduplicator.ts
+function deduplicateTexts(texts) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const dt of texts) {
+    const key = dt.text.toLowerCase().trim();
+    if (!seen.has(key)) seen.set(key, dt);
+  }
+  return Array.from(seen.values());
+}
+function filterAlreadyTranslated(texts, existingKeys) {
+  return texts.filter((dt) => !existingKeys.has(dt.suggestedKey));
+}
+function findUnusedKeys(localeKeys, sourceKeys) {
+  const sourceSet = new Set(sourceKeys);
+  return localeKeys.filter((k) => !sourceSet.has(k));
+}
+
+// src/synchronizer.ts
+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") {
+    this.localesDir = localesDir;
+    this.defaultLanguage = defaultLanguage;
+  }
+  localesDir;
+  defaultLanguage;
+  sync() {
+    const updated = [];
+    let addedKeys = 0;
+    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"));
+    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 = readJsonSafe2(path2.join(defaultDir, namespace));
+      if (!defaultEntries) continue;
+      for (const lang of langDirs) {
+        const targetPath = path2.join(this.localesDir, lang, namespace);
+        ensureDir2(path2.dirname(targetPath));
+        const existing = readJsonSafe2(targetPath) || {};
+        let changed = false;
+        for (const key of Object.keys(defaultEntries)) {
+          if (!(key in existing)) {
+            existing[key] = "";
+            addedKeys++;
+            changed = true;
+          }
+        }
+        if (changed) {
+          writeJson2(targetPath, existing);
+          updated.push(targetPath);
+        }
+      }
+    }
+    return { updated, addedKeys };
+  }
+};
+export {
+  LocaleExtractor,
+  LocaleSynchronizer,
+  LocaleWriter,
+  deduplicateTexts,
+  filterAlreadyTranslated,
+  findUnusedKeys
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "ai-localize-locale-engine",
+  "version": "1.0.0",
+  "description": "Locale file generation, merging, deduplication and synchronization",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "ai-localize-shared": "1.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.1"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src --ext .ts"
+  }
+}

package/src/__tests__/extractor.test.ts

@@ -0,0 +1,52 @@
+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

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,75 @@
+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;
+}
+
+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,
+    };
+  }
+
+  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;
+    }
+
+    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) {
+        const langEntries =
+          lang === this.options.defaultLanguage
+            ? { ...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

@@ -0,0 +1,4 @@
+export * from "./extractor.js";
+export * from "./writer.js";
+export * from "./deduplicator.js";
+export * from "./synchronizer.js";

package/src/synchronizer.ts

@@ -0,0 +1,36 @@
+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

@@ -0,0 +1,59 @@
+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;
+}
+
+export class LocaleWriter {
+  private options: Required<WriteOptions>;
+
+  constructor(options: WriteOptions) {
+this.options = { localesDir: options.localesDir, merge: options.merge ?? true, sort: options.sort ?? true };
+  }
+
+  write(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;
+      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 resolveFilePath(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`);
+  }
+
+  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

@@ -0,0 +1,6 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "outDir": "./dist", "rootDir": "./src" },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}