@mariokreitz/langsync 0.4.1 → 0.5.0

package/dist/cli.js

@@ -247,9 +247,13 @@ function registerInitCommand(program) {
 }
 var LangSyncConfigSchema = z.object({
   input: z.string().describe("Path to the source i18n directory."),
-  output: z.string().describe("Path to the output/translations directory."),
-  locales: z.array(z.string()).min(1).describe("List of supported locales."),
-  defaultLocale: z.string().optional(),
+  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."),
   excel: z.object({
     file: z.string().default("translations.xlsx"),
@@ -261,6 +265,14 @@ var LangSyncConfigSchema = z.object({
     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")}`;
+}
 async function loadConfig(cwd = process.cwd()) {
   const explorer = cosmiconfig("langsync", {
     searchPlaces: [
@@ -278,8 +290,11 @@ async function loadConfig(cwd = process.cwd()) {
   });
   const result = await explorer.search(cwd);
   if (!result) return null;
-  const parsed = LangSyncConfigSchema.parse(result.config);
-  return { config: parsed, filepath: result.filepath };
+  const parsed = LangSyncConfigSchema.safeParse(result.config);
+  if (!parsed.success) {
+    throw new Error(formatZodError(parsed.error));
+  }
+  return { config: parsed.data, filepath: result.filepath };
 }
 async function writeJson(filePath, data, { indent = 2 } = {}) {
   const absolute = resolve(filePath);
@@ -373,6 +388,26 @@ function syncTrees(source, target) {
   }
   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;
+}
 
 // src/commands/sync/run.ts
 async function runSync(options) {
@@ -394,15 +429,23 @@ async function runSync(options) {
   const targets = files.filter((f) => f.locale !== referenceLocale);
   const planned = [];
   const written = [];
+  const unchanged = [];
+  const diffsByPath = {};
   for (const target of targets) {
     const merged = syncTrees(reference.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 };
+  return { referenceLocale, written, planned, unchanged, diffsByPath };
 }
 
 // src/commands/sync.ts
@@ -676,6 +719,14 @@ function registerImportCommand(program) {
 }
 
 // ../ai-engine/dist/index.js
+var TranslationAdapterError = class extends Error {
+  constructor(message, provider, statusCode, options) {
+    super(message, options);
+    this.provider = provider;
+    this.statusCode = statusCode;
+    this.name = "TranslationAdapterError";
+  }
+};
 var DEFAULT_MODEL = "gpt-5-mini";
 var ENDPOINT = "https://api.openai.com/v1/chat/completions";
 var OpenAIAdapter = class {
@@ -863,7 +914,7 @@ var GeminiAdapter = class {
     return content;
   }
 };
-var RELEASED_PROVIDERS = ["openai"];
+var RELEASED_PROVIDERS = ["openai", "deepl"];
 var ALL_PROVIDERS = ["openai", "deepl", "anthropic", "gemini"];
 function experimentalEnabled() {
   return process.env.LANGSYNC_AI_EXPERIMENTAL === "1";
@@ -903,9 +954,14 @@ 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,
@@ -913,7 +969,7 @@ async function fillEmptyTranslations(options) {
     });
     translatedKeys.push(key);
   }
-  return { tree: unflatten(targetFlat), translatedKeys };
+  return { tree: unflatten(targetFlat), translatedKeys, skippedKeys };
 }
 
 // src/commands/translate/run.ts
@@ -940,18 +996,42 @@ async function runTranslate(options) {
     throw new Error(`Could not find reference locale file for "${referenceLocale}".`);
   }
   const targets = files.filter((f) => f.locale !== referenceLocale);
+  const refFlat = flatten(reference.translations);
+  const allCandidates = [];
+  for (const target of targets) {
+    const targetFlat = flatten(target.translations);
+    for (const [key, value] of Object.entries(refFlat)) {
+      if (!value || value.trim() === "") continue;
+      if (targetFlat[key] && targetFlat[key].trim() !== "") continue;
+      allCandidates.push({ file: target, key, sourceValue: value });
+    }
+  }
+  const totalTranslatableKeys = allCandidates.length;
+  const limited = options.maxKeys ? allCandidates.slice(0, options.maxKeys) : allCandidates;
+  const perLocaleMaxKeys = {};
+  for (const candidate of limited) {
+    perLocaleMaxKeys[candidate.file.locale] = (perLocaleMaxKeys[candidate.file.locale] ?? 0) + 1;
+  }
   const written = [];
   const planned = [];
   const translatedByLocale = {};
+  const skippedByLocale = {};
   for (const target of targets) {
-    const { tree, translatedKeys } = await fillEmptyTranslations({
+    const localeMax = perLocaleMaxKeys[target.locale];
+    if (options.maxKeys !== void 0 && !localeMax) {
+      skippedByLocale[target.locale] = allCandidates.filter((c) => c.file.locale === target.locale).map((c) => c.key);
+      continue;
+    }
+    const { tree, translatedKeys, skippedKeys } = await fillEmptyTranslations({
       reference: reference.translations,
       target: target.translations,
       sourceLocale: referenceLocale,
       targetLocale: target.locale,
-      adapter
+      adapter,
+      maxKeys: localeMax
     });
     translatedByLocale[target.locale] = translatedKeys;
+    if (skippedKeys.length > 0) skippedByLocale[target.locale] = skippedKeys;
     if (translatedKeys.length === 0) continue;
     planned.push(target.path);
     if (!options.dryRun) {
@@ -959,41 +1039,92 @@ async function runTranslate(options) {
       written.push(target.path);
     }
   }
-  return { provider, referenceLocale, written, planned, translatedByLocale };
+  return {
+    provider,
+    referenceLocale,
+    written,
+    planned,
+    translatedByLocale,
+    skippedByLocale,
+    totalTranslatableKeys
+  };
 }
 
 // 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) => {
+  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(
+    "--max-keys <n>",
+    "Limit the total number of keys translated per run. Keys are selected deterministically: target locales in config order, then keys in reference order. Useful for controlling API spend."
+  ).option("--dry-run", "Report what would be translated without writing files.", false).action(async (flags) => {
     try {
       const cwd = process.cwd();
+      const maxKeys = flags.maxKeys ? Number.parseInt(flags.maxKeys, 10) : void 0;
+      if (maxKeys !== void 0 && (Number.isNaN(maxKeys) || maxKeys <= 0)) {
+        logger.error("--max-keys must be a positive integer.");
+        process.exitCode = 1;
+        return;
+      }
       const result = await runTranslate({
         cwd,
         dryRun: flags.dryRun,
         provider: flags.provider,
-        model: flags.model
+        model: flags.model,
+        maxKeys
       });
       const totals = Object.values(result.translatedByLocale).reduce(
         (sum, keys) => sum + keys.length,
         0
       );
+      if (flags.dryRun) {
+        if (result.totalTranslatableKeys === 0) {
+          logger.info(`Nothing to translate with ${chalk.cyan(result.provider)}.`);
+        } else {
+          const capped = maxKeys !== void 0 && maxKeys < result.totalTranslatableKeys;
+          logger.info(
+            `[dry-run] Would translate ${chalk.bold(String(totals))} key(s) across ${Object.keys(result.translatedByLocale).length} locale(s) using ${chalk.cyan(result.provider)}.`
+          );
+          if (capped) {
+            logger.info(
+              `[dry-run] ${result.totalTranslatableKeys - totals} key(s) skipped due to --max-keys ${String(maxKeys)}.`
+            );
+          }
+          for (const [locale, keys] of Object.entries(result.translatedByLocale)) {
+            if (keys.length === 0) continue;
+            logger.info(`[dry-run]   ${locale}: ${String(keys.length)} key(s)`);
+          }
+        }
+        return;
+      }
       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}`);
+        logger.success(`Translated ${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))}`);
-        }
+      for (const path of result.written) {
+        logger.info(`Wrote ${chalk.bold(relative(cwd, path))}`);
+      }
+      const totalSkipped = Object.values(result.skippedByLocale).reduce(
+        (sum, keys) => sum + keys.length,
+        0
+      );
+      if (totalSkipped > 0) {
+        logger.warn(
+          `${chalk.yellow(String(totalSkipped))} key(s) skipped due to --max-keys. Run again to translate remaining keys.`
+        );
       }
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      logger.error(message);
+      if (error instanceof TranslationAdapterError) {
+        const statusInfo = error.statusCode ? ` (${String(error.statusCode)})` : "";
+        logger.error(`${error.provider} translation failed${statusInfo}: ${error.message}`);
+        if (error.statusCode === 429) {
+          logger.info("Rate limited. Retry in a moment, or use --max-keys to reduce requests.");
+        }
+      } else {
+        logger.error(error instanceof Error ? error.message : String(error));
+      }
       process.exitCode = 1;
     }
   });
@@ -1006,7 +1137,7 @@ async function resolveWatchDir(cwd) {
   return resolve(cwd, loaded.config.input);
 }
 async function runWatchPass(options) {
-  const { referenceLocale, written } = await runSync({
+  const { referenceLocale, written, unchanged, diffsByPath } = await runSync({
     cwd: options.cwd,
     dryRun: options.dryRun
   });
@@ -1020,16 +1151,31 @@ async function runWatchPass(options) {
     locales: loaded.config.locales
   });
   const issues = validateLocales(files, referenceLocale);
-  return { referenceLocale, written, issues };
+  return { referenceLocale, written, unchanged, diffsByPath, issues };
 }
 
 // src/commands/watch.ts
-function reportPass(cwd, written, issueCount) {
-  if (written.length === 0) {
-    logger.info("No locale changes to sync.");
+function formatDiff(diff) {
+  const parts = [];
+  if (diff.added.length > 0) parts.push(chalk.green(`+${diff.added.length}`));
+  if (diff.removed.length > 0) parts.push(chalk.red(`-${diff.removed.length}`));
+  if (diff.changed.length > 0) parts.push(chalk.yellow(`~${diff.changed.length}`));
+  return parts.join(", ");
+}
+function reportPass(cwd, written, unchanged, diffsByPath, issueCount) {
+  if (written.length === 0 && unchanged.length === 0) {
+    logger.info("No locale files found to sync.");
+  } else if (written.length === 0) {
+    logger.info("All locales are already in sync.");
   } else {
     for (const path of written) {
-      logger.success(`Synced ${chalk.bold(relative(cwd, path))}`);
+      const rel = relative(cwd, path);
+      const diff = diffsByPath[path];
+      const summary = diff ? ` (${formatDiff(diff)})` : "";
+      logger.success(`Synced ${chalk.bold(rel)}${summary}`);
+    }
+    for (const path of unchanged) {
+      logger.info(`No changes: ${chalk.dim(relative(cwd, path))}`);
     }
   }
   if (issueCount > 0) {
@@ -1045,7 +1191,13 @@ function registerWatchCommand(program) {
       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);
+      reportPass(
+        cwd,
+        initial.written,
+        initial.unchanged,
+        initial.diffsByPath,
+        initial.issues.length
+      );
       logger.info(`Watching ${chalk.cyan(relative(cwd, watchDir) || ".")} for changes...`);
       const watcher = chokidar.watch(join(watchDir, "*.json"), {
         ignoreInitial: true
@@ -1060,7 +1212,7 @@ function registerWatchCommand(program) {
             running = true;
             try {
               const pass = await runWatchPass({ cwd, dryRun: flags.dryRun });
-              reportPass(cwd, pass.written, pass.issues.length);
+              reportPass(cwd, pass.written, pass.unchanged, pass.diffsByPath, pass.issues.length);
             } catch (error) {
               logger.error(error instanceof Error ? error.message : String(error));
             } finally {
@@ -1079,7 +1231,7 @@ function registerWatchCommand(program) {
 }
 
 // src/cli.ts
-var VERSION = "0.4.1" ;
+var VERSION = "0.5.0" ;
 async function main() {
   assertNodeVersion(22);
   const program = new Command();

package/dist/index.d.ts

@@ -1 +1 @@
-export { LangSyncConfig, defineConfig } from '@langsync/shared/config';
+export { LangSyncConfig, LangSyncConfigInput, defineConfig } from '@langsync/shared/config';

package/dist/index.js

@@ -5,9 +5,13 @@ import { z } from 'zod';
 
 z.object({
   input: z.string().describe("Path to the source i18n directory."),
-  output: z.string().describe("Path to the output/translations directory."),
-  locales: z.array(z.string()).min(1).describe("List of supported locales."),
-  defaultLocale: z.string().optional(),
+  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."),
   excel: z.object({
     file: z.string().default("translations.xlsx"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mariokreitz/langsync",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Modern localization workflow tooling for TypeScript applications.",
   "keywords": [
     "i18n",
@@ -65,10 +65,10 @@
   "devDependencies": {
     "@types/prompts": "^2.4.9",
     "memfs": "^4.57.3",
-    "@langsync/shared": "0.1.0",
-    "@langsync/ai-engine": "0.1.0",
-    "@langsync/core": "0.1.0",
-    "@langsync/excel-engine": "0.1.0"
+    "@langsync/shared": "0.2.0",
+    "@langsync/excel-engine": "0.1.1",
+    "@langsync/core": "0.1.1",
+    "@langsync/ai-engine": "0.2.0"
   },
   "scripts": {
     "build": "tsup",