@mariokreitz/langsync 0.1.1 → 0.4.0

package/README.md

@@ -18,10 +18,16 @@ chaos of hand-edited JSON or fragile Excel hand-offs.
 
 ## Install
 
+<!-- embedme ../../docs/shared/install.sh -->
+
 ```bash
 pnpm add -D @mariokreitz/langsync
-# or: npm install -D @mariokreitz/langsync
-# or: yarn add -D @mariokreitz/langsync
+# or
+npm install -D @mariokreitz/langsync
+# or
+yarn add -D @mariokreitz/langsync
+
+
 ```
 
 > Requires **Node.js 22+** and an ESM-compatible project.
@@ -38,10 +44,13 @@ npx langsync validate
 # 3. Add missing keys (empty placeholders) to non-reference locales
 npx langsync sync
 
-# 4. Hand off to translators via Excel
+# 4. Optionally fill the gaps with AI
+npx langsync translate
+
+# 5. Hand off to translators via Excel
 npx langsync export excel
 
-# 5. Import their work back
+# 6. Import their work back
 npx langsync import excel
 ```
 
@@ -53,6 +62,8 @@ npx langsync import excel
 | `langsync validate`     | Report missing, extra, and empty keys; exits non-zero on errors.    |
 | `langsync find-missing` | Report missing keys per locale; exits non-zero on errors.           |
 | `langsync sync`         | Synchronize keys from the reference locale into every other locale. |
+| `langsync translate`    | Fill empty values in non-reference locales using an AI provider.    |
+| `langsync watch`        | Watch locale files and run incremental sync + validation on change. |
 | `langsync export excel` | Export all locales into a single `.xlsx` workbook.                  |
 | `langsync import excel` | Import translations from a workbook back into JSON files.           |
 
@@ -61,8 +72,9 @@ All read commands support `--reporter json`. All write commands support
 
 ## Configuration
 
+<!-- embedme ../../docs/shared/config.ts -->
+
 ```ts
-// langsync.config.ts
 import { defineConfig } from '@mariokreitz/langsync';
 
 export default defineConfig({
@@ -71,6 +83,14 @@ export default defineConfig({
   locales: ['en', 'de', 'fr'],
   defaultLocale: 'en',
   framework: 'i18next',
+  excel: {
+    file: 'translations.xlsx',
+    sheetName: 'Translations',
+  },
+  ai: {
+    provider: 'openai',
+    model: 'gpt-5-mini',
+  },
 });
 ```
 

package/dist/cli.js

@@ -9,6 +9,7 @@ import { cosmiconfig } from 'cosmiconfig';
 import { TypeScriptLoader } from 'cosmiconfig-typescript-loader';
 import { z } from 'zod';
 import ExcelJS from 'exceljs';
+import chokidar from 'chokidar';
 
 var PREFIX = chalk.bold.cyan("langsync");
 var logger = {
@@ -44,7 +45,7 @@ function assertNodeVersion(minMajor) {
   }
 }
 var FRAMEWORK_SIGNATURES = [
-  { framework: "i18next", packages: ["i18next", "react-i18next", "vue-i18next"] },
+  { framework: "i18next", packages: ["i18next", "react-i18next", "i18next-vue", "vue-i18next"] },
   { framework: "ngx-translate", packages: ["@ngx-translate/core", "@ngx-translate/http-loader"] },
   { framework: "react-intl", packages: ["react-intl", "@formatjs/intl"] }
 ];
@@ -253,7 +254,12 @@ var LangSyncConfigSchema = z.object({
   excel: z.object({
     file: z.string().default("translations.xlsx"),
     sheetName: z.string().default("Translations")
-  }).optional()
+  }).optional(),
+  ai: z.object({
+    provider: z.enum(["openai", "deepl", "anthropic", "gemini"]).default("openai").describe("AI translation provider."),
+    apiKey: z.string().optional().describe("API key. Falls back to the provider-specific env var."),
+    model: z.string().optional().describe("Provider model id (e.g. gpt-5-mini).")
+  }).optional().describe("AI translation settings.")
 });
 async function loadConfig(cwd = process.cwd()) {
   const explorer = cosmiconfig("langsync", {
@@ -669,8 +675,411 @@ function registerImportCommand(program) {
   });
 }
 
+// ../ai-engine/dist/index.js
+var DEFAULT_MODEL = "gpt-5-mini";
+var ENDPOINT = "https://api.openai.com/v1/chat/completions";
+var OpenAIAdapter = class {
+  provider = "openai";
+  apiKey;
+  model;
+  fetchImpl;
+  constructor(options = {}) {
+    const apiKey = options.apiKey ?? process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+      throw new Error(
+        "OpenAI API key missing. Set `ai.apiKey` in your config or the OPENAI_API_KEY env var."
+      );
+    }
+    this.apiKey = apiKey;
+    this.model = options.model ?? DEFAULT_MODEL;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+  async translate(request) {
+    const response = await this.fetchImpl(ENDPOINT, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify({
+        model: this.model,
+        temperature: 0,
+        messages: [
+          {
+            role: "system",
+            content: `You are a professional software localization engine. Translate the user message from ${request.sourceLocale} to ${request.targetLocale}. Preserve placeholders, ICU syntax, and surrounding punctuation. Respond with the translation only, no quotes or commentary.`
+          },
+          { role: "user", content: request.text }
+        ]
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`OpenAI request failed: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    const content = data.choices?.[0]?.message?.content?.trim();
+    if (!content) {
+      throw new Error("OpenAI returned an empty translation.");
+    }
+    return content;
+  }
+};
+var FREE_ENDPOINT = "https://api-free.deepl.com/v2/translate";
+var PRO_ENDPOINT = "https://api.deepl.com/v2/translate";
+var FREE_KEY_SUFFIX = ":fx";
+function toDeepLLang(locale) {
+  return locale.split("-")[0].toUpperCase();
+}
+var DeepLAdapter = class {
+  provider = "deepl";
+  apiKey;
+  endpoint;
+  fetchImpl;
+  constructor(options = {}) {
+    const apiKey = options.apiKey ?? process.env.DEEPL_API_KEY;
+    if (!apiKey) {
+      throw new Error(
+        "DeepL API key missing. Set `ai.apiKey` in your config or the DEEPL_API_KEY env var."
+      );
+    }
+    this.apiKey = apiKey;
+    const useFreeTier = options.useFreeTier ?? apiKey.endsWith(FREE_KEY_SUFFIX);
+    this.endpoint = useFreeTier ? FREE_ENDPOINT : PRO_ENDPOINT;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+  async translate(request) {
+    const response = await this.fetchImpl(this.endpoint, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `DeepL-Auth-Key ${this.apiKey}`
+      },
+      body: JSON.stringify({
+        text: [request.text],
+        source_lang: toDeepLLang(request.sourceLocale),
+        target_lang: toDeepLLang(request.targetLocale)
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`DeepL request failed: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    const content = data.translations?.[0]?.text?.trim();
+    if (!content) {
+      throw new Error("DeepL returned an empty translation.");
+    }
+    return content;
+  }
+};
+var DEFAULT_MODEL2 = "claude-haiku-4-5";
+var ENDPOINT2 = "https://api.anthropic.com/v1/messages";
+var ANTHROPIC_VERSION = "2023-06-01";
+var MAX_TOKENS = 1024;
+var AnthropicAdapter = class {
+  provider = "anthropic";
+  apiKey;
+  model;
+  fetchImpl;
+  constructor(options = {}) {
+    const apiKey = options.apiKey ?? process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+      throw new Error(
+        "Anthropic API key missing. Set `ai.apiKey` in your config or the ANTHROPIC_API_KEY env var."
+      );
+    }
+    this.apiKey = apiKey;
+    this.model = options.model ?? DEFAULT_MODEL2;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+  async translate(request) {
+    const response = await this.fetchImpl(ENDPOINT2, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-api-key": this.apiKey,
+        "anthropic-version": ANTHROPIC_VERSION
+      },
+      body: JSON.stringify({
+        model: this.model,
+        max_tokens: MAX_TOKENS,
+        system: `You are a professional software localization engine. Translate the user message from ${request.sourceLocale} to ${request.targetLocale}. Preserve placeholders, ICU syntax, and surrounding punctuation. Respond with the translation only, no quotes or commentary.`,
+        messages: [{ role: "user", content: request.text }]
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`Anthropic request failed: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    const content = data.content?.find((block) => block.type === "text" || block.text)?.text?.trim();
+    if (!content) {
+      throw new Error("Anthropic returned an empty translation.");
+    }
+    return content;
+  }
+};
+var DEFAULT_MODEL3 = "gemini-3-flash";
+var BASE_URL = "https://generativelanguage.googleapis.com/v1beta/models";
+var GeminiAdapter = class {
+  provider = "gemini";
+  apiKey;
+  model;
+  fetchImpl;
+  constructor(options = {}) {
+    const apiKey = options.apiKey ?? process.env.GEMINI_API_KEY;
+    if (!apiKey) {
+      throw new Error(
+        "Gemini API key missing. Set `ai.apiKey` in your config or the GEMINI_API_KEY env var."
+      );
+    }
+    this.apiKey = apiKey;
+    this.model = options.model ?? DEFAULT_MODEL3;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+  async translate(request) {
+    const url = `${BASE_URL}/${this.model}:generateContent?key=${this.apiKey}`;
+    const response = await this.fetchImpl(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        systemInstruction: {
+          parts: [
+            {
+              text: `You are a professional software localization engine. Translate the user message from ${request.sourceLocale} to ${request.targetLocale}. Preserve placeholders, ICU syntax, and surrounding punctuation. Respond with the translation only, no quotes or commentary.`
+            }
+          ]
+        },
+        contents: [{ parts: [{ text: request.text }] }],
+        generationConfig: { temperature: 0 }
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`Gemini request failed: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    const content = data.candidates?.[0]?.content?.parts?.[0]?.text?.trim();
+    if (!content) {
+      throw new Error("Gemini returned an empty translation.");
+    }
+    return content;
+  }
+};
+var RELEASED_PROVIDERS = ["openai"];
+var ALL_PROVIDERS = ["openai", "deepl", "anthropic", "gemini"];
+function experimentalEnabled() {
+  return process.env.LANGSYNC_AI_EXPERIMENTAL === "1";
+}
+function availableProviders() {
+  return experimentalEnabled() ? [...ALL_PROVIDERS] : [...RELEASED_PROVIDERS];
+}
+function createAdapter(options) {
+  if (!availableProviders().includes(options.provider)) {
+    if (ALL_PROVIDERS.includes(options.provider)) {
+      throw new Error(
+        `AI provider "${options.provider}" is not yet available. Currently supported: ${availableProviders().join(", ")}.`
+      );
+    }
+    throw new Error(`Unknown AI provider "${options.provider}".`);
+  }
+  const { provider, ...rest } = options;
+  switch (provider) {
+    case "openai":
+      return new OpenAIAdapter(rest);
+    case "deepl":
+      return new DeepLAdapter(rest);
+    case "anthropic":
+      return new AnthropicAdapter(rest);
+    case "gemini":
+      return new GeminiAdapter(rest);
+    default: {
+      const exhaustive = provider;
+      throw new Error(`AI provider "${String(exhaustive)}" has no adapter implementation yet.`);
+    }
+  }
+}
+function isEmpty(value) {
+  return value === void 0 || value.trim() === "";
+}
+async function fillEmptyTranslations(options) {
+  const referenceFlat = flatten(options.reference);
+  const targetFlat = flatten(options.target);
+  const translatedKeys = [];
+  for (const [key, referenceValue] of Object.entries(referenceFlat)) {
+    if (isEmpty(referenceValue)) continue;
+    if (!isEmpty(targetFlat[key])) continue;
+    targetFlat[key] = await options.adapter.translate({
+      text: referenceValue,
+      sourceLocale: options.sourceLocale,
+      targetLocale: options.targetLocale
+    });
+    translatedKeys.push(key);
+  }
+  return { tree: unflatten(targetFlat), translatedKeys };
+}
+
+// src/commands/translate/run.ts
+async function runTranslate(options) {
+  const loaded = await loadConfig(options.cwd);
+  if (!loaded) {
+    throw new Error("No LangSync config found. Run `langsync init` first.");
+  }
+  const { config } = loaded;
+  const referenceLocale = config.defaultLocale ?? config.locales[0];
+  const provider = options.provider ?? config.ai?.provider ?? "openai";
+  const adapter = createAdapter({
+    provider,
+    apiKey: config.ai?.apiKey,
+    model: options.model ?? config.ai?.model
+  });
+  const files = await loadLocaleFiles({
+    cwd: options.cwd,
+    inputDir: config.input,
+    locales: config.locales
+  });
+  const reference = files.find((f) => f.locale === referenceLocale);
+  if (!reference) {
+    throw new Error(`Could not find reference locale file for "${referenceLocale}".`);
+  }
+  const targets = files.filter((f) => f.locale !== referenceLocale);
+  const written = [];
+  const planned = [];
+  const translatedByLocale = {};
+  for (const target of targets) {
+    const { tree, translatedKeys } = await fillEmptyTranslations({
+      reference: reference.translations,
+      target: target.translations,
+      sourceLocale: referenceLocale,
+      targetLocale: target.locale,
+      adapter
+    });
+    translatedByLocale[target.locale] = translatedKeys;
+    if (translatedKeys.length === 0) continue;
+    planned.push(target.path);
+    if (!options.dryRun) {
+      await writeJson(target.path, tree);
+      written.push(target.path);
+    }
+  }
+  return { provider, referenceLocale, written, planned, translatedByLocale };
+}
+
+// src/commands/translate.ts
+function registerTranslateCommand(program) {
+  program.command("translate").description("Fill empty values in non-reference locales using an AI provider.").option("--provider <provider>", "Override the configured AI provider.").option("--model <model>", "Override the configured provider model.").option("--dry-run", "Report what would be translated without writing files.", false).action(async (flags) => {
+    try {
+      const cwd = process.cwd();
+      const result = await runTranslate({
+        cwd,
+        dryRun: flags.dryRun,
+        provider: flags.provider,
+        model: flags.model
+      });
+      const totals = Object.values(result.translatedByLocale).reduce(
+        (sum, keys) => sum + keys.length,
+        0
+      );
+      if (totals === 0) {
+        logger.info(`Nothing to translate with ${chalk.cyan(result.provider)}.`);
+        return;
+      }
+      const verb = flags.dryRun ? "Would translate" : "Translated";
+      for (const [locale, keys] of Object.entries(result.translatedByLocale)) {
+        if (keys.length === 0) continue;
+        logger.success(`${verb} ${chalk.bold(String(keys.length))} key(s) for ${locale}`);
+      }
+      if (!flags.dryRun) {
+        for (const path of result.written) {
+          logger.info(`Wrote ${chalk.bold(relative(cwd, path))}`);
+        }
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.error(message);
+      process.exitCode = 1;
+    }
+  });
+}
+async function resolveWatchDir(cwd) {
+  const loaded = await loadConfig(cwd);
+  if (!loaded) {
+    throw new Error("No LangSync config found. Run `langsync init` first.");
+  }
+  return resolve(cwd, loaded.config.input);
+}
+async function runWatchPass(options) {
+  const { referenceLocale, written } = await runSync({
+    cwd: options.cwd,
+    dryRun: options.dryRun
+  });
+  const loaded = await loadConfig(options.cwd);
+  if (!loaded) {
+    throw new Error("No LangSync config found. Run `langsync init` first.");
+  }
+  const files = await loadLocaleFiles({
+    cwd: options.cwd,
+    inputDir: loaded.config.input,
+    locales: loaded.config.locales
+  });
+  const issues = validateLocales(files, referenceLocale);
+  return { referenceLocale, written, issues };
+}
+
+// src/commands/watch.ts
+function reportPass(cwd, written, issueCount) {
+  if (written.length === 0) {
+    logger.info("No locale changes to sync.");
+  } else {
+    for (const path of written) {
+      logger.success(`Synced ${chalk.bold(relative(cwd, path))}`);
+    }
+  }
+  if (issueCount > 0) {
+    logger.warn(`${chalk.yellow(String(issueCount))} validation issue(s) remaining.`);
+  } else {
+    logger.success("All locales are consistent.");
+  }
+}
+function registerWatchCommand(program) {
+  program.command("watch").description("Watch locale files and run incremental sync + validation on change.").option("--dry-run", "Report planned changes without writing files.", false).option("--debounce <ms>", "Debounce window for rapid file changes.", "200").action(async (flags) => {
+    try {
+      const cwd = process.cwd();
+      const watchDir = await resolveWatchDir(cwd);
+      const debounceMs = Number.parseInt(flags.debounce, 10) || 200;
+      const initial = await runWatchPass({ cwd, dryRun: flags.dryRun });
+      reportPass(cwd, initial.written, initial.issues.length);
+      logger.info(`Watching ${chalk.cyan(relative(cwd, watchDir) || ".")} for changes...`);
+      const watcher = chokidar.watch(join(watchDir, "*.json"), {
+        ignoreInitial: true
+      });
+      let timer;
+      let running = false;
+      const trigger = () => {
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(() => {
+          void (async () => {
+            if (running) return;
+            running = true;
+            try {
+              const pass = await runWatchPass({ cwd, dryRun: flags.dryRun });
+              reportPass(cwd, pass.written, pass.issues.length);
+            } catch (error) {
+              logger.error(error instanceof Error ? error.message : String(error));
+            } finally {
+              running = false;
+            }
+          })();
+        }, debounceMs);
+      };
+      watcher.on("change", trigger).on("add", trigger).on("unlink", trigger);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.error(message);
+      process.exitCode = 1;
+    }
+  });
+}
+
 // src/cli.ts
-var VERSION = "0.0.0";
+var VERSION = "0.4.0" ;
 async function main() {
   assertNodeVersion(22);
   const program = new Command();
@@ -681,6 +1090,8 @@ async function main() {
   registerSyncCommand(program);
   registerValidateCommand(program);
   registerFindMissingCommand(program);
+  registerTranslateCommand(program);
+  registerWatchCommand(program);
   registerExportCommand(program);
   registerImportCommand(program);
   await program.parseAsync(process.argv);

package/dist/index.js

@@ -12,7 +12,12 @@ z.object({
   excel: z.object({
     file: z.string().default("translations.xlsx"),
     sheetName: z.string().default("Translations")
-  }).optional()
+  }).optional(),
+  ai: z.object({
+    provider: z.enum(["openai", "deepl", "anthropic", "gemini"]).default("openai").describe("AI translation provider."),
+    apiKey: z.string().optional().describe("API key. Falls back to the provider-specific env var."),
+    model: z.string().optional().describe("Provider model id (e.g. gpt-5-mini).")
+  }).optional().describe("AI translation settings.")
 });
 function defineConfig(config) {
   return config;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mariokreitz/langsync",
-  "version": "0.1.1",
+  "version": "0.4.0",
   "description": "Modern localization workflow tooling for TypeScript applications.",
   "keywords": [
     "i18n",
@@ -10,7 +10,10 @@
     "cli",
     "i18next",
     "ngx-translate",
-    "react-intl"
+    "react-intl",
+    "ai-translation",
+    "openai",
+    "watch-mode"
   ],
   "license": "MIT",
   "author": "Mario Kreitz",
@@ -19,7 +22,7 @@
     "url": "git+https://github.com/mariokreitz/langsync.git",
     "directory": "packages/cli"
   },
-  "homepage": "https://github.com/mariokreitz/langsync#readme",
+  "homepage": "https://docs.langsync.kreitz-webdev.de",
   "bugs": {
     "url": "https://github.com/mariokreitz/langsync/issues"
   },
@@ -49,6 +52,7 @@
   },
   "dependencies": {
     "chalk": "^5.3.0",
+    "chokidar": "^4.0.3",
     "commander": "^12.1.0",
     "cosmiconfig": "^9.0.0",
     "cosmiconfig-typescript-loader": "^6.1.0",
@@ -60,10 +64,11 @@
   },
   "devDependencies": {
     "@types/prompts": "^2.4.9",
-    "memfs": "^4.15.1",
+    "memfs": "^4.57.3",
+    "@langsync/shared": "0.1.0",
     "@langsync/core": "0.1.0",
     "@langsync/excel-engine": "0.1.0",
-    "@langsync/shared": "0.1.0"
+    "@langsync/ai-engine": "0.1.0"
   },
   "scripts": {
     "build": "tsup",