@mariokreitz/langsync-sdk 0.2.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Mario Kreitz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,68 @@
+# @mariokreitz/langsync-sdk
+
+> The programmatic SDK for [LangSync](https://github.com/mariokreitz/langsync) —
+> drive validate, sync, find-missing, and translate workflows in-process from
+> Node.js.
+
+[![npm version](https://img.shields.io/npm/v/@mariokreitz/langsync-sdk?style=flat-square&color=7c3aed)](https://www.npmjs.com/package/@mariokreitz/langsync-sdk)
+[![CI](https://img.shields.io/github/actions/workflow/status/mariokreitz/langsync/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/mariokreitz/langsync/actions/workflows/ci.yml)
+[![codecov](https://img.shields.io/codecov/c/github/mariokreitz/langsync?style=flat-square)](https://codecov.io/gh/mariokreitz/langsync)
+[![Node](https://img.shields.io/node/v/@mariokreitz/langsync-sdk?style=flat-square&color=7c3aed)](https://nodejs.org)
+[![License](https://img.shields.io/npm/l/@mariokreitz/langsync-sdk?style=flat-square)](https://github.com/mariokreitz/langsync/blob/main/LICENSE)
+
+The LangSync SDK exposes the same command runners that power the `langsync` CLI
+and the official VS Code extension. Every runner takes an explicit `cwd`,
+returns a structured result object, and never logs, prompts, or calls
+`process.exit` — so it is safe to embed in long-running hosts such as editors,
+dev servers, and CI pipelines.
+
+## Installation
+
+```bash
+npm install @mariokreitz/langsync-sdk
+```
+
+```bash
+pnpm add @mariokreitz/langsync-sdk
+```
+
+## Usage
+
+```ts
+import { loadConfig, runValidate, runSync } from '@mariokreitz/langsync-sdk';
+
+const loaded = await loadConfig(process.cwd());
+if (!loaded) {
+  throw new Error('No LangSync config found. Run `langsync init` first.');
+}
+
+const validation = await runValidate({ cwd: process.cwd() });
+if (validation.exitCode !== 0) {
+  await runSync({ cwd: process.cwd() });
+}
+```
+
+## API
+
+- `loadConfig(cwd?)` — resolve and validate the LangSync config; returns `null`
+  when no config is found.
+- `defineConfig(config)` — typed helper for authoring `langsync.config.ts`.
+- `runValidate(options)` — report missing, extra, and empty translation keys.
+- `runSync(options)` — add missing keys to non-reference locales (supports
+  `dryRun`).
+- `runFindMissing(options)` — list missing keys per locale.
+- `runTranslate(options)` — fill missing keys via an AI provider (supports
+  `dryRun`, `maxKeys`, and provider/model overrides).
+
+See the [SDK reference](https://docs.langsync.kreitz-webdev.de/docs/sdk) for the
+full surface, options, and result types.
+
+## Testing
+
+```bash
+pnpm --filter @mariokreitz/langsync-sdk test
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,124 @@
+export { LangSyncConfig, LangSyncConfigInput, LoadedConfig, defineConfig, loadConfig } from './config/index.js';
+
+interface ValidationIssue {
+    type: 'missing' | 'extra' | 'empty';
+    locale: string;
+    key: string;
+}
+
+interface TreeDiff {
+    /** Keys present in `next` but not in `prev`. */
+    added: string[];
+    /** Keys present in `prev` but not in `next`. */
+    removed: string[];
+    /** Keys present in both whose value changed. */
+    changed: string[];
+}
+
+interface RunValidateOptions {
+    cwd: string;
+}
+type NamespacedValidationIssue = ValidationIssue & {
+    namespace: string | null;
+    path: string;
+};
+interface RunValidateResult {
+    referenceLocale: string;
+    issues: NamespacedValidationIssue[];
+    exitCode: 0 | 1;
+}
+/**
+ * Validate the locale files configured in the LangSync config at `cwd`.
+ *
+ * - `missing` and `extra` issues are treated as errors (exit code 1).
+ * - `empty` issues are treated as warnings only (exit code 0).
+ */
+declare function runValidate(options: RunValidateOptions): Promise<RunValidateResult>;
+
+interface RunSyncOptions {
+    cwd: string;
+    dryRun?: boolean;
+}
+interface RunSyncResult {
+    referenceLocale: string;
+    /** Paths that were written to disk. Empty in dry-run. */
+    written: string[];
+    /** Paths that were planned to be written (subset of targets with changes). */
+    planned: string[];
+    /** Paths skipped because the locale was already in sync with the reference. */
+    unchanged: string[];
+    /**
+     * Per-path diff keyed by absolute file path.
+     * Only contains entries for files that had changes (i.e. entries in `planned`).
+     */
+    diffsByPath: Record<string, TreeDiff>;
+}
+/**
+ * Synchronize keys from the reference locale into every other locale,
+ * preserving existing translations and adding empty placeholders for new keys.
+ * Files whose content would not change after sync are skipped — no unnecessary
+ * disk writes are performed.
+ */
+declare function runSync(options: RunSyncOptions): Promise<RunSyncResult>;
+
+interface RunFindMissingOptions {
+    cwd: string;
+}
+interface MissingEntry {
+    namespace: string | null;
+    key: string;
+    path: string;
+}
+interface RunFindMissingResult {
+    referenceLocale: string;
+    missingByLocale: Record<string, MissingEntry[]>;
+    exitCode: 0 | 1;
+}
+/**
+ * Report missing translation keys per locale, relative to the reference locale.
+ */
+declare function runFindMissing(options: RunFindMissingOptions): Promise<RunFindMissingResult>;
+
+type AIProvider = 'openai' | 'deepl' | 'anthropic' | 'gemini';
+
+interface RunTranslateOptions {
+    cwd: string;
+    dryRun?: boolean;
+    /** Override the provider configured in `langsync.config.ts`. */
+    provider?: AIProvider;
+    /** Override the model configured in `langsync.config.ts`. */
+    model?: string;
+    /**
+     * Maximum total number of keys to translate across all target locales.
+     * Keys are selected deterministically (same order on every run) by
+     * iterating target locales in config order, then namespaces in order, then
+     * keys in reference order. Remaining untranslated keys are reported.
+     */
+    maxKeys?: number;
+}
+interface TranslationEntry {
+    namespace: string | null;
+    key: string;
+    path: string;
+}
+interface RunTranslateResult {
+    provider: AIProvider;
+    referenceLocale: string;
+    /** Files written to disk. */
+    written: string[];
+    /** Files that have at least one translated key (the change candidates). */
+    planned: string[];
+    /** Translated dot-notated keys per locale. */
+    translatedByLocale: Record<string, TranslationEntry[]>;
+    /** Keys that were skipped due to the `maxKeys` cap, grouped by locale. */
+    skippedByLocale: Record<string, TranslationEntry[]>;
+    /** Total number of keys that could be translated before any cap is applied. */
+    totalTranslatableKeys: number;
+}
+/**
+ * Fill empty values in every non-reference locale using the configured AI
+ * provider, preserving existing translations.
+ */
+declare function runTranslate(options: RunTranslateOptions): Promise<RunTranslateResult>;
+
+export { type AIProvider, type MissingEntry, type NamespacedValidationIssue, type RunFindMissingOptions, type RunFindMissingResult, type RunSyncOptions, type RunSyncResult, type RunTranslateOptions, type RunTranslateResult, type RunValidateOptions, type RunValidateResult, type TranslationEntry, type TreeDiff, type ValidationIssue, runFindMissing, runSync, runTranslate, runValidate };

package/dist/index.js

@@ -0,0 +1,916 @@
+import chalk from 'chalk';
+import { cosmiconfig } from 'cosmiconfig';
+import { TypeScriptLoader } from 'cosmiconfig-typescript-loader';
+import { z } from 'zod';
+import { mkdir, writeFile, readFile, readdir } from 'fs/promises';
+import { resolve, relative, sep, basename, dirname, join } from 'path';
+
+// ../shared/dist/index.js
+chalk.bold.cyan("langsync");
+var NamespaceConfigSchema = z.object({
+  structure: z.enum(["locale-dir", "locale-prefix"]).describe(
+    "Optional namespace layout. `locale-dir` resolves <input>/<locale>/<namespace>.json recursively. `locale-prefix` resolves <input>/<locale>.<namespace>.json."
+  )
+});
+var LangSyncConfigSchema = z.object({
+  input: z.string().describe("Path to the source i18n directory."),
+  output: z.string().default("./translations").describe(
+    'Base directory for translated output. Defaults to "./translations". Reserved for report and export output in future releases.'
+  ),
+  locales: z.array(z.string()).min(1).describe('List of supported locales (e.g. ["en", "de", "fr"]).'),
+  defaultLocale: z.string().optional().describe(
+    "Reference locale. Keys from this locale are synced into all other locales. Defaults to the first entry in `locales`."
+  ),
+  framework: z.enum(["i18next", "ngx-translate", "react-intl", "none"]).optional().describe("i18n framework integration. Use `none` to opt out explicitly."),
+  namespaces: NamespaceConfigSchema.optional().describe(
+    "Optional namespace settings. Omit this block to keep the default single-file layout at <input>/<locale>.json."
+  ),
+  excel: z.object({
+    file: z.string().default("translations.xlsx"),
+    sheetName: z.string().default("Translations")
+  }).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 formatZodError(error) {
+  const issues = error.issues.map((issue) => {
+    const path = issue.path.length > 0 ? `  ${issue.path.join(".")}: ` : "  ";
+    return `${path}${issue.message}`;
+  });
+  return `Invalid LangSync configuration:
+${issues.join("\n")}`;
+}
+function defineConfig(config) {
+  return config;
+}
+async function loadConfig(cwd = process.cwd()) {
+  const explorer = cosmiconfig("langsync", {
+    searchPlaces: [
+      "langsync.config.ts",
+      "langsync.config.js",
+      "langsync.config.mjs",
+      "langsync.config.json",
+      ".langsyncrc",
+      ".langsyncrc.json",
+      "package.json"
+    ],
+    loaders: {
+      ".ts": TypeScriptLoader()
+    }
+  });
+  const result = await explorer.search(cwd);
+  if (!result) return null;
+  const parsed = LangSyncConfigSchema.safeParse(result.config);
+  if (!parsed.success) {
+    throw new Error(formatZodError(parsed.error));
+  }
+  return { config: parsed.data, filepath: result.filepath };
+}
+
+// ../core/dist/index.js
+function flatten(tree, prefix = "") {
+  const out = {};
+  for (const [key, value] of Object.entries(tree)) {
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+    if (typeof value === "string") {
+      out[fullKey] = value;
+    } else {
+      Object.assign(out, flatten(value, fullKey));
+    }
+  }
+  return out;
+}
+function unflatten(flat) {
+  const result = {};
+  for (const [key, value] of Object.entries(flat)) {
+    const parts = key.split(".");
+    let cursor = result;
+    for (let i = 0; i < parts.length - 1; i++) {
+      const part = parts[i];
+      const next = cursor[part];
+      if (typeof next !== "object" || next === null) {
+        const fresh = {};
+        cursor[part] = fresh;
+        cursor = fresh;
+      } else {
+        cursor = next;
+      }
+    }
+    cursor[parts[parts.length - 1]] = value;
+  }
+  return result;
+}
+function validateLocales(files, referenceLocale) {
+  const issues = [];
+  const reference = files.find((f) => f.locale === referenceLocale);
+  if (!reference) return issues;
+  const referenceKeys = new Set(Object.keys(flatten(reference.translations)));
+  for (const file of files) {
+    const flat = flatten(file.translations);
+    const fileKeys = new Set(Object.keys(flat));
+    if (file.locale !== referenceLocale) {
+      for (const key of referenceKeys) {
+        if (!fileKeys.has(key)) issues.push({ type: "missing", locale: file.locale, key });
+      }
+      for (const key of fileKeys) {
+        if (!referenceKeys.has(key)) issues.push({ type: "extra", locale: file.locale, key });
+      }
+    }
+    for (const [key, value] of Object.entries(flat)) {
+      if (!value || value.trim() === "") issues.push({ type: "empty", locale: file.locale, key });
+    }
+  }
+  return issues;
+}
+function syncTrees(source, target) {
+  const sourceFlat = flatten(source);
+  const targetFlat = flatten(target);
+  const merged = {};
+  for (const key of Object.keys(sourceFlat)) {
+    merged[key] = targetFlat[key] ?? "";
+  }
+  return unflatten(merged);
+}
+function diffTrees(prev, next) {
+  const prevFlat = flatten(prev);
+  const nextFlat = flatten(next);
+  const prevKeys = new Set(Object.keys(prevFlat));
+  const nextKeys = new Set(Object.keys(nextFlat));
+  const added = [];
+  const removed = [];
+  const changed = [];
+  for (const key of nextKeys) {
+    if (!prevKeys.has(key)) added.push(key);
+    else if (prevFlat[key] !== nextFlat[key]) changed.push(key);
+  }
+  for (const key of prevKeys) {
+    if (!nextKeys.has(key)) removed.push(key);
+  }
+  return { added, removed, changed };
+}
+function hasChanges(diff) {
+  return diff.added.length > 0 || diff.removed.length > 0 || diff.changed.length > 0;
+}
+var NamespaceConfigSchema2 = z.object({
+  structure: z.enum(["locale-dir", "locale-prefix"]).describe(
+    "Optional namespace layout. `locale-dir` resolves <input>/<locale>/<namespace>.json recursively. `locale-prefix` resolves <input>/<locale>.<namespace>.json."
+  )
+});
+var LangSyncConfigSchema2 = z.object({
+  input: z.string().describe("Path to the source i18n directory."),
+  output: z.string().default("./translations").describe(
+    'Base directory for translated output. Defaults to "./translations". Reserved for report and export output in future releases.'
+  ),
+  locales: z.array(z.string()).min(1).describe('List of supported locales (e.g. ["en", "de", "fr"]).'),
+  defaultLocale: z.string().optional().describe(
+    "Reference locale. Keys from this locale are synced into all other locales. Defaults to the first entry in `locales`."
+  ),
+  framework: z.enum(["i18next", "ngx-translate", "react-intl", "none"]).optional().describe("i18n framework integration. Use `none` to opt out explicitly."),
+  namespaces: NamespaceConfigSchema2.optional().describe(
+    "Optional namespace settings. Omit this block to keep the default single-file layout at <input>/<locale>.json."
+  ),
+  excel: z.object({
+    file: z.string().default("translations.xlsx"),
+    sheetName: z.string().default("Translations")
+  }).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 formatZodError2(error) {
+  const issues = error.issues.map((issue) => {
+    const path = issue.path.length > 0 ? `  ${issue.path.join(".")}: ` : "  ";
+    return `${path}${issue.message}`;
+  });
+  return `Invalid LangSync configuration:
+${issues.join("\n")}`;
+}
+async function loadConfig2(cwd = process.cwd()) {
+  const explorer = cosmiconfig("langsync", {
+    searchPlaces: [
+      "langsync.config.ts",
+      "langsync.config.js",
+      "langsync.config.mjs",
+      "langsync.config.json",
+      ".langsyncrc",
+      ".langsyncrc.json",
+      "package.json"
+    ],
+    loaders: {
+      ".ts": TypeScriptLoader()
+    }
+  });
+  const result = await explorer.search(cwd);
+  if (!result) return null;
+  const parsed = LangSyncConfigSchema2.safeParse(result.config);
+  if (!parsed.success) {
+    throw new Error(formatZodError2(parsed.error));
+  }
+  return { config: parsed.data, filepath: result.filepath };
+}
+async function writeJson(filePath, data, { indent = 2 } = {}) {
+  const absolute = resolve(filePath);
+  await mkdir(dirname(absolute), { recursive: true });
+  await writeFile(absolute, JSON.stringify(data, null, indent) + "\n", "utf-8");
+}
+function isWithinDirectory(path, directory) {
+  return path === directory || path.startsWith(directory + sep);
+}
+function validateNamespace(namespace, structure) {
+  if (namespace.trim() === "") {
+    throw new Error('Invalid namespace "": namespace must not be empty.');
+  }
+  if (namespace.includes("\\")) {
+    throw new Error(`Invalid namespace "${namespace}": backslashes are not allowed.`);
+  }
+  if (namespace.startsWith("/")) {
+    throw new Error(`Invalid namespace "${namespace}": absolute namespace paths are not allowed.`);
+  }
+  if (structure === "locale-prefix" && namespace.includes("/")) {
+    throw new Error(
+      `Invalid namespace "${namespace}": locale-prefix namespaces must not contain '/'.`
+    );
+  }
+  if (namespace.split("/").some((segment) => segment === "." || segment === "..")) {
+    throw new Error(`Invalid namespace "${namespace}": path traversal segments are not allowed.`);
+  }
+}
+function resolveLocaleFilePath(args) {
+  const inputAbs = resolve(args.cwd, args.inputDir);
+  if (!args.namespaces) {
+    if (args.namespace !== null) {
+      throw new Error(
+        `Invalid namespace "${args.namespace}": single-file mode cannot resolve a namespace.`
+      );
+    }
+    const path2 = resolve(inputAbs, `${args.locale}.json`);
+    if (!isWithinDirectory(path2, inputAbs)) {
+      throw new Error(
+        `Resolved locale file path escapes input directory for locale "${args.locale}".`
+      );
+    }
+    return path2;
+  }
+  if (args.namespace === null) {
+    throw new Error("Namespaced mode requires a non-null namespace.");
+  }
+  validateNamespace(args.namespace, args.namespaces.structure);
+  const path = args.namespaces.structure === "locale-dir" ? resolve(inputAbs, args.locale, `${args.namespace}.json`) : resolve(inputAbs, `${args.locale}.${args.namespace}.json`);
+  if (!isWithinDirectory(path, inputAbs)) {
+    throw new Error(
+      `Resolved locale file path escapes input directory for namespace "${args.namespace}".`
+    );
+  }
+  return path;
+}
+async function readTranslationFile(path, logicalPath) {
+  const content = await readFile(path, "utf-8");
+  try {
+    return JSON.parse(content);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to parse ${logicalPath}: ${message}`, { cause: error });
+  }
+}
+async function listJsonFilesRecursive(directory) {
+  let entries;
+  try {
+    entries = await readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    const errno = error.code;
+    if (errno === "ENOENT") return [];
+    throw error;
+  }
+  const files = [];
+  for (const entry of entries) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await listJsonFilesRecursive(path));
+    } else if (entry.isFile() && entry.name.endsWith(".json")) {
+      files.push(path);
+    }
+  }
+  return files.sort();
+}
+async function listDirectJsonFiles(directory) {
+  let entries;
+  try {
+    entries = await readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    const errno = error.code;
+    if (errno === "ENOENT") return [];
+    throw error;
+  }
+  return entries.filter((entry) => entry.isFile() && entry.name.endsWith(".json")).map((entry) => join(directory, entry.name)).sort();
+}
+function orderAndSynthesizeFiles(loaded, options) {
+  const namespaces = [
+    ...new Set(loaded.map((file) => file.namespace).filter((ns) => ns !== null))
+  ].sort();
+  if (namespaces.length === 0) return [];
+  const byKey = new Map(loaded.map((file) => [`${file.locale}\0${file.namespace}`, file]));
+  const ordered = [];
+  for (const locale of options.locales) {
+    for (const namespace of namespaces) {
+      const key = `${locale}\0${namespace}`;
+      const existing = byKey.get(key);
+      if (existing) {
+        ordered.push(existing);
+        continue;
+      }
+      ordered.push({
+        locale,
+        namespace,
+        path: resolveLocaleFilePath({
+          cwd: options.cwd,
+          inputDir: options.inputDir,
+          locale,
+          namespace,
+          namespaces: options.namespaces
+        }),
+        translations: {},
+        exists: false
+      });
+    }
+  }
+  return ordered;
+}
+async function loadLocaleFiles(options) {
+  const inputAbs = resolve(options.cwd, options.inputDir);
+  if (!options.namespaces) {
+    const out = [];
+    for (const locale of options.locales) {
+      const path = resolveLocaleFilePath({
+        cwd: options.cwd,
+        inputDir: options.inputDir,
+        locale,
+        namespace: null
+      });
+      let translations = {};
+      let exists = false;
+      try {
+        translations = await readTranslationFile(path, `${locale}.json`);
+        exists = true;
+      } catch (error) {
+        const errno = error.code;
+        if (errno !== "ENOENT") throw error;
+      }
+      out.push({ locale, namespace: null, path, translations, exists });
+    }
+    return out;
+  }
+  const loaded = [];
+  if (options.namespaces.structure === "locale-dir") {
+    for (const locale of options.locales) {
+      const localeDir = resolve(inputAbs, locale);
+      if (!isWithinDirectory(localeDir, inputAbs)) {
+        throw new Error(`Locale "${locale}" resolves outside the input directory.`);
+      }
+      const paths2 = await listJsonFilesRecursive(localeDir);
+      for (const path of paths2) {
+        const namespace = relative(localeDir, path).slice(0, -".json".length).split(sep).join("/");
+        validateNamespace(namespace, "locale-dir");
+        loaded.push({
+          locale,
+          namespace,
+          path,
+          translations: await readTranslationFile(path, `${locale}/${namespace}.json`),
+          exists: true
+        });
+      }
+    }
+    return orderAndSynthesizeFiles(loaded, options);
+  }
+  const sortedLocales = [...options.locales].sort((a, b) => b.length - a.length);
+  const paths = await listDirectJsonFiles(inputAbs);
+  for (const path of paths) {
+    const fileName = basename(path);
+    const locale = sortedLocales.find((candidate) => fileName.startsWith(`${candidate}.`));
+    if (!locale) continue;
+    const namespace = fileName.slice(locale.length + 1, -".json".length);
+    if (namespace.trim() === "") continue;
+    validateNamespace(namespace, "locale-prefix");
+    loaded.push({
+      locale,
+      namespace,
+      path,
+      translations: await readTranslationFile(path, fileName),
+      exists: true
+    });
+  }
+  return orderAndSynthesizeFiles(loaded, options);
+}
+function indexLocaleFiles(files) {
+  const byLocale = {};
+  const namespaceSet = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    byLocale[file.locale] ??= /* @__PURE__ */ new Map();
+    byLocale[file.locale].set(file.namespace, file);
+    if (file.namespace !== null) namespaceSet.add(file.namespace);
+  }
+  return {
+    files,
+    namespaces: [...namespaceSet].sort(),
+    byLocale
+  };
+}
+
+// ../shared/dist/errors/index.js
+function noNamespacesError(referenceLocale, inputDir) {
+  return new Error(
+    `No namespace files found under "${inputDir}". Run \`langsync init\` or create at least one namespace file for "${referenceLocale}".`
+  );
+}
+
+// src/validate.ts
+async function runValidate(options) {
+  const loaded = await loadConfig2(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 files = await loadLocaleFiles({
+    cwd: options.cwd,
+    inputDir: config.input,
+    locales: config.locales,
+    namespaces: config.namespaces
+  });
+  const index = indexLocaleFiles(files);
+  const namespaced = config.namespaces !== void 0;
+  if (namespaced && index.namespaces.length === 0) {
+    throw noNamespacesError(referenceLocale, config.input);
+  }
+  const nsKeys = namespaced ? index.namespaces : [null];
+  const issues = [];
+  for (const nsKey of nsKeys) {
+    const namespaceFiles = config.locales.map((locale) => index.byLocale[locale]?.get(nsKey)).filter((file) => file !== void 0);
+    const namespaceIssues = validateLocales(namespaceFiles, referenceLocale);
+    for (const issue of namespaceIssues) {
+      const file = index.byLocale[issue.locale]?.get(nsKey);
+      if (!file) continue;
+      issues.push({ ...issue, namespace: nsKey, path: file.path });
+    }
+  }
+  issues.sort((a, b) => {
+    const namespaceA = a.namespace ?? "";
+    const namespaceB = b.namespace ?? "";
+    return a.locale.localeCompare(b.locale) || namespaceA.localeCompare(namespaceB) || a.key.localeCompare(b.key) || a.type.localeCompare(b.type);
+  });
+  const hasErrors = issues.some((i) => i.type === "missing" || i.type === "extra");
+  return {
+    referenceLocale,
+    issues,
+    exitCode: hasErrors ? 1 : 0
+  };
+}
+
+// src/sync.ts
+async function runSync(options) {
+  const loaded = await loadConfig2(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 files = await loadLocaleFiles({
+    cwd: options.cwd,
+    inputDir: config.input,
+    locales: config.locales,
+    namespaces: config.namespaces
+  });
+  const index = indexLocaleFiles(files);
+  const namespaced = config.namespaces !== void 0;
+  if (namespaced && index.namespaces.length === 0) {
+    throw noNamespacesError(referenceLocale, config.input);
+  }
+  const nsKeys = namespaced ? index.namespaces : [null];
+  const referenceBucket = index.byLocale[referenceLocale];
+  if (!referenceBucket) {
+    throw new Error(`Could not find reference locale file for "${referenceLocale}".`);
+  }
+  const planned = [];
+  const written = [];
+  const unchanged = [];
+  const diffsByPath = {};
+  for (const targetLocale of config.locales) {
+    if (targetLocale === referenceLocale) continue;
+    const targetBucket = index.byLocale[targetLocale];
+    if (!targetBucket) continue;
+    for (const nsKey of nsKeys) {
+      const source = referenceBucket.get(nsKey);
+      const target = targetBucket.get(nsKey);
+      if (!source || !target) continue;
+      const merged = syncTrees(source.translations, target.translations);
+      const diff = diffTrees(target.translations, merged);
+      if (!hasChanges(diff)) {
+        unchanged.push(target.path);
+        continue;
+      }
+      diffsByPath[target.path] = diff;
+      planned.push(target.path);
+      if (!options.dryRun) {
+        await writeJson(target.path, merged);
+        written.push(target.path);
+      }
+    }
+  }
+  return { referenceLocale, written, planned, unchanged, diffsByPath };
+}
+
+// src/find-missing.ts
+async function runFindMissing(options) {
+  const { issues, referenceLocale } = await runValidate({ cwd: options.cwd });
+  const missingByLocale = {};
+  for (const issue of issues) {
+    if (issue.type !== "missing") continue;
+    (missingByLocale[issue.locale] ??= []).push({
+      namespace: issue.namespace,
+      key: issue.key,
+      path: issue.path
+    });
+  }
+  for (const entries of Object.values(missingByLocale)) {
+    entries.sort(
+      (a, b) => (a.namespace ?? "").localeCompare(b.namespace ?? "") || a.key.localeCompare(b.key)
+    );
+  }
+  const exitCode = Object.keys(missingByLocale).length === 0 ? 0 : 1;
+  return { referenceLocale, missingByLocale, exitCode };
+}
+
+// ../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", "deepl"];
+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 = [];
+  const skippedKeys = [];
+  for (const [key, referenceValue] of Object.entries(referenceFlat)) {
+    if (isEmpty(referenceValue)) continue;
+    if (!isEmpty(targetFlat[key])) continue;
+    if (options.maxKeys !== void 0 && translatedKeys.length >= options.maxKeys) {
+      skippedKeys.push(key);
+      continue;
+    }
+    targetFlat[key] = await options.adapter.translate({
+      text: referenceValue,
+      sourceLocale: options.sourceLocale,
+      targetLocale: options.targetLocale
+    });
+    translatedKeys.push(key);
+  }
+  return { tree: unflatten(targetFlat), translatedKeys, skippedKeys };
+}
+
+// src/translate.ts
+function isEmpty2(value) {
+  return value === void 0 || value.trim() === "";
+}
+function candidateEntry(candidate) {
+  return { namespace: candidate.namespace, key: candidate.key, path: candidate.path };
+}
+async function runTranslate(options) {
+  const loaded = await loadConfig2(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 files = await loadLocaleFiles({
+    cwd: options.cwd,
+    inputDir: config.input,
+    locales: config.locales,
+    namespaces: config.namespaces
+  });
+  const index = indexLocaleFiles(files);
+  const namespaced = config.namespaces !== void 0;
+  if (namespaced && index.namespaces.length === 0) {
+    throw noNamespacesError(referenceLocale, config.input);
+  }
+  const nsKeys = namespaced ? index.namespaces : [null];
+  const referenceBucket = index.byLocale[referenceLocale];
+  if (!referenceBucket) {
+    throw new Error(`Could not find reference locale file for "${referenceLocale}".`);
+  }
+  const adapter = createAdapter({
+    provider,
+    apiKey: config.ai?.apiKey,
+    model: options.model ?? config.ai?.model
+  });
+  const allCandidates = [];
+  for (const targetLocale of config.locales) {
+    if (targetLocale === referenceLocale) continue;
+    const targetBucket = index.byLocale[targetLocale];
+    if (!targetBucket) continue;
+    for (const nsKey of nsKeys) {
+      const reference = referenceBucket.get(nsKey);
+      const target = targetBucket.get(nsKey);
+      if (!reference || !target) continue;
+      const refFlat = flatten(reference.translations);
+      const targetFlat = flatten(target.translations);
+      for (const [key, value] of Object.entries(refFlat)) {
+        if (isEmpty2(value)) continue;
+        if (!isEmpty2(targetFlat[key])) continue;
+        allCandidates.push({
+          locale: targetLocale,
+          namespace: nsKey,
+          path: target.path,
+          key,
+          sourceValue: value
+        });
+      }
+    }
+  }
+  const totalTranslatableKeys = allCandidates.length;
+  const limited = options.maxKeys ? allCandidates.slice(0, options.maxKeys) : allCandidates;
+  const limitedByPath = /* @__PURE__ */ new Map();
+  const skippedCandidates = options.maxKeys ? allCandidates.slice(options.maxKeys) : [];
+  for (const candidate of limited) {
+    const entries = limitedByPath.get(candidate.path) ?? [];
+    entries.push(candidate);
+    limitedByPath.set(candidate.path, entries);
+  }
+  const written = [];
+  const planned = [];
+  const translatedByLocale = {};
+  const skippedByLocale = {};
+  for (const candidate of skippedCandidates) {
+    if (limitedByPath.has(candidate.path)) continue;
+    (skippedByLocale[candidate.locale] ??= []).push(candidateEntry(candidate));
+  }
+  for (const targetLocale of config.locales) {
+    if (targetLocale === referenceLocale) continue;
+    const targetBucket = index.byLocale[targetLocale];
+    if (!targetBucket) continue;
+    for (const nsKey of nsKeys) {
+      const reference = referenceBucket.get(nsKey);
+      const target = targetBucket.get(nsKey);
+      if (!reference || !target) continue;
+      const budget = limitedByPath.get(target.path)?.length;
+      if (budget === void 0) continue;
+      const { tree, translatedKeys, skippedKeys } = await fillEmptyTranslations({
+        reference: reference.translations,
+        target: target.translations,
+        sourceLocale: referenceLocale,
+        targetLocale,
+        adapter,
+        maxKeys: budget
+      });
+      if (translatedKeys.length > 0) {
+        (translatedByLocale[targetLocale] ??= []).push(
+          ...translatedKeys.map((key) => ({ namespace: nsKey, key, path: target.path }))
+        );
+        planned.push(target.path);
+        if (!options.dryRun) {
+          await writeJson(target.path, tree);
+          written.push(target.path);
+        }
+      }
+      if (skippedKeys.length > 0) {
+        (skippedByLocale[targetLocale] ??= []).push(
+          ...skippedKeys.map((key) => ({ namespace: nsKey, key, path: target.path }))
+        );
+      }
+    }
+  }
+  return {
+    provider,
+    referenceLocale,
+    written,
+    planned,
+    translatedByLocale,
+    skippedByLocale,
+    totalTranslatableKeys
+  };
+}
+
+export { defineConfig, loadConfig, runFindMissing, runSync, runTranslate, runValidate };

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@mariokreitz/langsync-sdk",
+  "version": "0.2.0",
+  "description": "Programmatic SDK for LangSync — run validate, sync, find-missing, and translate localization workflows in-process from Node.js.",
+  "keywords": [
+    "langsync",
+    "sdk",
+    "i18n",
+    "l10n",
+    "localization",
+    "internationalization",
+    "translation",
+    "locales"
+  ],
+  "license": "MIT",
+  "author": "Mario Kreitz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mariokreitz/langsync.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://docs.langsync.kreitz-webdev.de/docs/sdk",
+  "bugs": {
+    "url": "https://github.com/mariokreitz/langsync/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "cosmiconfig": "^9.0.1",
+    "cosmiconfig-typescript-loader": "^6.1.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@langsync/ai-engine": "0.2.2",
+    "@langsync/core": "0.1.3",
+    "@langsync/shared": "0.2.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rm -rf dist .turbo"
+  }
+}