@mariokreitz/langsync 0.5.0 → 0.7.0

package/dist/cli.js

@@ -2,13 +2,14 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
 import ora from 'ora';
-import { relative, join, resolve, dirname } from 'path';
-import { readFile, mkdir, writeFile, access } from 'fs/promises';
+import { relative, join, resolve, dirname, sep, basename } from 'path';
+import { readFile, mkdir, writeFile, access, readdir } from 'fs/promises';
 import prompts from 'prompts';
+import { runSync, runValidate, runFindMissing, runTranslate } from '@mariokreitz/langsync-sdk';
+import ExcelJS from 'exceljs';
 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");
@@ -73,12 +74,30 @@ var FRAMEWORK_CHOICES = [
   { title: "react-intl", value: "react-intl" },
   { title: "None / Custom", value: "none" }
 ];
+var LOCALE_LAYOUT_CHOICES = [
+  {
+    title: "Single file per locale (<input>/<locale>.json)",
+    value: "single-file"
+  },
+  {
+    title: "Namespace folders per locale (<input>/<locale>/<namespace>.json)",
+    value: "locale-dir"
+  },
+  {
+    title: "Flat namespace-prefixed files (<input>/<locale>.<namespace>.json)",
+    value: "locale-prefix"
+  }
+];
 var DEFAULTS = {
   input: "./src/i18n",
   output: "./translations",
   locales: "en,de",
   defaultLocale: "en"
 };
+function parseNamespaces(value) {
+  const namespaces = value.split(",").map((namespace) => namespace.trim()).filter(Boolean);
+  return namespaces.length > 0 ? namespaces : ["common"];
+}
 async function runInitPrompts(options) {
   const framework = options.detectedFramework ?? "none";
   if (options.yes) {
@@ -98,6 +117,20 @@ async function runInitPrompts(options) {
         message: "Where are your source i18n files?",
         initial: DEFAULTS.input
       },
+      {
+        type: "select",
+        name: "localeLayout",
+        message: "How should locale files be organized?",
+        choices: LOCALE_LAYOUT_CHOICES,
+        initial: 0
+      },
+      {
+        type: (prev) => prev === "single-file" ? null : "text",
+        name: "initialNamespaces",
+        message: "Initial namespaces? (comma-separated)",
+        initial: "common",
+        format: parseNamespaces
+      },
       {
         type: "text",
         name: "output",
@@ -135,7 +168,18 @@ async function runInitPrompts(options) {
       }
     }
   );
-  return response;
+  const answers = {
+    input: response.input,
+    output: response.output,
+    locales: response.locales,
+    defaultLocale: response.defaultLocale,
+    framework: response.framework
+  };
+  if (response.localeLayout !== "single-file") {
+    answers.namespaces = { structure: response.localeLayout };
+    answers.initialNamespaces = response.initialNamespaces?.length ? response.initialNamespaces : ["common"];
+  }
+  return answers;
 }
 var CANDIDATE_CONFIG_FILES = [
   "langsync.config.ts",
@@ -161,6 +205,8 @@ async function findExistingConfig(cwd) {
 function renderTsConfig(answers) {
   const frameworkLine = answers.framework === "none" ? "" : `  framework: '${answers.framework}',
 `;
+  const namespacesLine = answers.namespaces ? `  namespaces: { structure: '${answers.namespaces.structure}' },
+` : "";
   const localesArr = answers.locales.map((l) => `'${l}'`).join(", ");
   return `import { defineConfig } from '@mariokreitz/langsync';
 
@@ -169,7 +215,7 @@ export default defineConfig({
   output: '${answers.output}',
   locales: [${localesArr}],
   defaultLocale: '${answers.defaultLocale}',
-${frameworkLine}});
+${frameworkLine}${namespacesLine}});
 `;
 }
 function renderJsonConfig(answers) {
@@ -180,8 +226,23 @@ function renderJsonConfig(answers) {
     defaultLocale: answers.defaultLocale
   };
   if (answers.framework !== "none") obj.framework = answers.framework;
+  if (answers.namespaces) obj.namespaces = answers.namespaces;
   return JSON.stringify(obj, null, 2) + "\n";
 }
+function getLocaleStubPaths(inputDir, answers) {
+  if (!answers.namespaces) {
+    return answers.locales.map((locale) => join(inputDir, `${locale}.json`));
+  }
+  const initialNamespaces = answers.initialNamespaces?.length ? answers.initialNamespaces : ["common"];
+  return answers.locales.flatMap(
+    (locale) => initialNamespaces.map((namespace) => {
+      if (answers.namespaces?.structure === "locale-dir") {
+        return join(inputDir, locale, `${namespace}.json`);
+      }
+      return join(inputDir, `${locale}.${namespace}.json`);
+    })
+  );
+}
 async function writeConfig(options) {
   const { cwd, answers, format, force } = options;
   const existing = await findExistingConfig(cwd);
@@ -198,9 +259,9 @@ async function writeConfig(options) {
   const inputDir = resolve(cwd, answers.input);
   await mkdir(inputDir, { recursive: true });
   const createdLocaleFiles = [];
-  for (const locale of answers.locales) {
-    const localePath = join(inputDir, `${locale}.json`);
+  for (const localePath of getLocaleStubPaths(inputDir, answers)) {
     if (!await pathExists(localePath)) {
+      await mkdir(dirname(localePath), { recursive: true });
       await writeFile(localePath, "{}\n", "utf-8");
       createdLocaleFiles.push(localePath);
     }
@@ -245,83 +306,89 @@ function registerInitCommand(program) {
     }
   });
 }
-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."),
-  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}`;
+function registerSyncCommand(program) {
+  program.command("sync").description("Synchronize translation keys across all configured locales.").option("--dry-run", "Report planned changes without writing files.", false).action(async (flags) => {
+    try {
+      const cwd = process.cwd();
+      const { written, planned, referenceLocale } = await runSync({
+        cwd,
+        dryRun: flags.dryRun
+      });
+      const targets = flags.dryRun ? planned : written;
+      if (targets.length === 0) {
+        logger.info(`Nothing to sync against ${chalk.cyan(referenceLocale)}.`);
+      } else {
+        const verb = flags.dryRun ? "Would update" : "Updated";
+        for (const path of targets) {
+          logger.success(`${verb} ${chalk.bold(relative(cwd, path))}`);
+        }
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.error(message);
+      process.exitCode = 1;
+    }
   });
-  return `Invalid LangSync configuration:
-${issues.join("\n")}`;
 }
-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()
+function formatIssueKey(issue) {
+  return issue.namespace === null ? issue.key : `${issue.namespace}:${issue.key}`;
+}
+function registerValidateCommand(program) {
+  program.command("validate").description("Validate locale consistency, structure and missing keys.").option("--reporter <kind>", "Output format: pretty | json.", "pretty").action(async (flags) => {
+    try {
+      const { issues, exitCode, referenceLocale } = await runValidate({ cwd: process.cwd() });
+      if (flags.reporter === "json") {
+        console.log(JSON.stringify({ referenceLocale, issues }, null, 2));
+      } else {
+        if (issues.length === 0) {
+          logger.success(`All locales are consistent with ${chalk.cyan(referenceLocale)}.`);
+        } else {
+          const byType = { missing: 0, extra: 0, empty: 0 };
+          for (const issue of issues) {
+            byType[issue.type]++;
+            const colored = issue.type === "empty" ? chalk.yellow(issue.type) : chalk.red(issue.type);
+            logger.info(`${colored}  ${chalk.cyan(issue.locale)}  ${formatIssueKey(issue)}`);
+          }
+          console.log();
+          logger.info(
+            `Summary: ${byType.missing} missing, ${byType.extra} extra, ${byType.empty} empty`
+          );
+        }
+      }
+      process.exitCode = exitCode;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.error(message);
+      process.exitCode = 1;
     }
   });
-  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 };
 }
-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 formatMissingEntry(entry) {
+  return entry.namespace === null ? entry.key : `${entry.namespace}:${entry.key}`;
 }
-async function loadLocaleFiles(options) {
-  const inputAbs = resolve(options.cwd, options.inputDir);
-  const out = [];
-  for (const locale of options.locales) {
-    const path = join(inputAbs, `${locale}.json`);
-    let translations = {};
+function registerFindMissingCommand(program) {
+  program.command("find-missing").description("Find missing translation keys across locales.").option("--reporter <kind>", "Output format: pretty | json.", "pretty").action(async (flags) => {
     try {
-      const content = await readFile(path, "utf-8");
-      try {
-        translations = JSON.parse(content);
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`Failed to parse ${locale}.json: ${message}`, { cause: error });
+      const { referenceLocale, missingByLocale, exitCode } = await runFindMissing({
+        cwd: process.cwd()
+      });
+      if (flags.reporter === "json") {
+        console.log(JSON.stringify({ referenceLocale, missingByLocale }, null, 2));
+      } else if (Object.keys(missingByLocale).length === 0) {
+        logger.success(`No missing keys relative to ${chalk.cyan(referenceLocale)}.`);
+      } else {
+        for (const [locale, keys] of Object.entries(missingByLocale)) {
+          logger.warn(`${chalk.cyan(locale)} is missing ${keys.length} key(s):`);
+          for (const entry of keys) console.log(`  - ${formatMissingEntry(entry)}`);
+        }
       }
+      process.exitCode = exitCode;
     } catch (error) {
-      const errno = error.code;
-      if (errno !== "ENOENT") throw error;
+      const message = error instanceof Error ? error.message : String(error);
+      logger.error(message);
+      process.exitCode = 1;
     }
-    out.push({ locale, path, translations });
-  }
-  return out;
+  });
 }
 
 // ../core/dist/index.js
@@ -379,239 +446,434 @@ function validateLocales(files, referenceLocale) {
   }
   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] ?? "";
+
+// ../excel-engine/dist/index.js
+function distinctLocales(files) {
+  const seen = /* @__PURE__ */ new Set();
+  const locales = [];
+  for (const file of files) {
+    if (seen.has(file.locale)) continue;
+    seen.add(file.locale);
+    locales.push(file.locale);
   }
-  return unflatten(merged);
+  return locales;
+}
+function cellText(value) {
+  return typeof value === "string" ? value : "";
+}
+function addHeader(sheet, header) {
+  sheet.addRow(header);
+  sheet.getRow(1).font = { bold: true };
 }
-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);
+function exportSingleFile(sheet, files) {
+  const locales = distinctLocales(files);
+  addHeader(sheet, ["key", ...locales]);
+  const flatByLocale = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    flatByLocale.set(file.locale, flatten(file.translations));
+  }
+  const allKeys = /* @__PURE__ */ new Set();
+  for (const flat of flatByLocale.values()) {
+    for (const key of Object.keys(flat)) allKeys.add(key);
   }
-  for (const key of prevKeys) {
-    if (!nextKeys.has(key)) removed.push(key);
+  for (const key of [...allKeys].sort()) {
+    sheet.addRow([key, ...locales.map((locale) => flatByLocale.get(locale)?.[key] ?? "")]);
   }
-  return { added, removed, changed };
 }
-function hasChanges(diff) {
-  return diff.added.length > 0 || diff.removed.length > 0 || diff.changed.length > 0;
+function namespacedKey(namespace, locale) {
+  return `${namespace}\0${locale}`;
 }
-
-// src/commands/sync/run.ts
-async function runSync(options) {
-  const loaded = await loadConfig(options.cwd);
-  if (!loaded) {
-    throw new Error("No LangSync config found. Run `langsync init` first.");
+function exportNamespaced(sheet, files) {
+  const locales = distinctLocales(files);
+  addHeader(sheet, ["namespace", "key", ...locales]);
+  const flatByNamespaceLocale = /* @__PURE__ */ new Map();
+  const rowKeys = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    if (file.namespace === null) continue;
+    const flat = flatten(file.translations);
+    flatByNamespaceLocale.set(namespacedKey(file.namespace, file.locale), flat);
+    for (const key of Object.keys(flat)) rowKeys.add(`${file.namespace}\0${key}`);
   }
-  const { config } = loaded;
-  const referenceLocale = config.defaultLocale ?? config.locales[0];
-  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 sortedRows = [...rowKeys].map((rowKey) => {
+    const [namespace, key] = rowKey.split("\0");
+    return { namespace, key };
+  }).sort((a, b) => a.namespace.localeCompare(b.namespace) || a.key.localeCompare(b.key));
+  for (const { namespace, key } of sortedRows) {
+    sheet.addRow([
+      namespace,
+      key,
+      ...locales.map(
+        (locale) => flatByNamespaceLocale.get(namespacedKey(namespace, locale))?.[key] ?? ""
+      )
+    ]);
   }
-  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);
-    }
+}
+async function exportToExcel(options) {
+  const workbook = new ExcelJS.Workbook();
+  const sheet = workbook.addWorksheet(options.sheetName ?? "Translations");
+  const allSingleFile = options.files.every((file) => file.namespace === null);
+  const allNamespaced = options.files.every((file) => file.namespace !== null);
+  if (!allSingleFile && !allNamespaced) {
+    throw new Error("exportToExcel: files must be uniformly single-file or namespaced.");
+  }
+  if (allSingleFile) {
+    exportSingleFile(sheet, options.files);
+  } else {
+    exportNamespaced(sheet, options.files);
   }
-  return { referenceLocale, written, planned, unchanged, diffsByPath };
+  await workbook.xlsx.writeFile(options.file);
 }
-
-// src/commands/sync.ts
-function registerSyncCommand(program) {
-  program.command("sync").description("Synchronize translation keys across all configured locales.").option("--dry-run", "Report planned changes without writing files.", false).action(async (flags) => {
-    try {
-      const cwd = process.cwd();
-      const { written, planned, referenceLocale } = await runSync({
-        cwd,
-        dryRun: flags.dryRun
-      });
-      const targets = flags.dryRun ? planned : written;
-      if (targets.length === 0) {
-        logger.info(`Nothing to sync against ${chalk.cyan(referenceLocale)}.`);
-      } else {
-        const verb = flags.dryRun ? "Would update" : "Updated";
-        for (const path of targets) {
-          logger.success(`${verb} ${chalk.bold(relative(cwd, path))}`);
-        }
-      }
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      logger.error(message);
-      process.exitCode = 1;
-    }
+function importSingleFile(sheet, header) {
+  const locales = header.slice(2).filter((value) => typeof value === "string");
+  const flatPerLocale = Object.fromEntries(
+    locales.map((locale) => [locale, {}])
+  );
+  sheet.eachRow({ includeEmpty: false }, (row, rowNumber) => {
+    if (rowNumber === 1) return;
+    const values = row.values;
+    const key = cellText(values[1]);
+    if (!key) return;
+    locales.forEach((locale, idx) => {
+      flatPerLocale[locale][key] = cellText(values[idx + 2]);
+    });
   });
+  return {
+    format: "single-file",
+    locales: locales.map((locale) => ({
+      locale,
+      namespace: null,
+      translations: unflatten(flatPerLocale[locale])
+    }))
+  };
 }
-
-// src/commands/validate/run.ts
-async function runValidate(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 files = await loadLocaleFiles({
-    cwd: options.cwd,
-    inputDir: config.input,
-    locales: config.locales
+function importNamespaced(sheet, header) {
+  const locales = header.slice(3).filter((value) => typeof value === "string");
+  const namespaces = /* @__PURE__ */ new Set();
+  const flatByLocaleNamespace = /* @__PURE__ */ new Map();
+  const seenRows = /* @__PURE__ */ new Set();
+  sheet.eachRow({ includeEmpty: false }, (row, rowNumber) => {
+    if (rowNumber === 1) return;
+    const values = row.values;
+    const namespace = cellText(values[1]).trim();
+    const key = cellText(values[2]);
+    if (!key) return;
+    if (!namespace) {
+      throw new Error(
+        `Row ${rowNumber}: namespace cell must not be empty in a namespaced workbook.`
+      );
+    }
+    const rowKey = `${namespace}\0${key}`;
+    if (seenRows.has(rowKey)) {
+      throw new Error(`Duplicate (namespace, key) row: "${namespace}" / "${key}".`);
+    }
+    seenRows.add(rowKey);
+    namespaces.add(namespace);
+    locales.forEach((locale, idx) => {
+      const mapKey = namespacedKey(namespace, locale);
+      let flat = flatByLocaleNamespace.get(mapKey);
+      if (!flat) {
+        flat = {};
+        flatByLocaleNamespace.set(mapKey, flat);
+      }
+      flat[key] = cellText(values[idx + 3]);
+    });
   });
-  const issues = validateLocales(files, referenceLocale);
-  const hasErrors = issues.some((i) => i.type === "missing" || i.type === "extra");
   return {
-    referenceLocale,
-    issues,
-    exitCode: hasErrors ? 1 : 0
+    format: "namespaced",
+    locales: locales.flatMap(
+      (locale) => [...namespaces].map((namespace) => ({
+        locale,
+        namespace,
+        translations: unflatten(flatByLocaleNamespace.get(namespacedKey(namespace, locale)) ?? {})
+      }))
+    )
   };
 }
-
-// src/commands/validate.ts
-function registerValidateCommand(program) {
-  program.command("validate").description("Validate locale consistency, structure and missing keys.").option("--reporter <kind>", "Output format: pretty | json.", "pretty").action(async (flags) => {
-    try {
-      const { issues, exitCode, referenceLocale } = await runValidate({ cwd: process.cwd() });
-      if (flags.reporter === "json") {
-        console.log(JSON.stringify({ referenceLocale, issues }, null, 2));
-      } else {
-        if (issues.length === 0) {
-          logger.success(`All locales are consistent with ${chalk.cyan(referenceLocale)}.`);
-        } else {
-          const byType = { missing: 0, extra: 0, empty: 0 };
-          for (const issue of issues) {
-            byType[issue.type]++;
-            const colored = issue.type === "empty" ? chalk.yellow(issue.type) : chalk.red(issue.type);
-            logger.info(`${colored}  ${chalk.cyan(issue.locale)}  ${issue.key}`);
-          }
-          console.log();
-          logger.info(
-            `Summary: ${byType.missing} missing, ${byType.extra} extra, ${byType.empty} empty`
-          );
-        }
-      }
-      process.exitCode = exitCode;
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      logger.error(message);
-      process.exitCode = 1;
+async function importFromExcel(file, sheetName) {
+  const workbook = new ExcelJS.Workbook();
+  await workbook.xlsx.readFile(file);
+  const sheet = sheetName ? workbook.getWorksheet(sheetName) : workbook.worksheets[0];
+  if (!sheet) throw new Error(`Worksheet not found: ${sheetName ?? "<first>"}`);
+  const header = sheet.getRow(1).values;
+  if (header[1] === "key") return importSingleFile(sheet, header);
+  if (header[1] === "namespace" && header[2] === "key") return importNamespaced(sheet, header);
+  throw new Error(
+    'Unrecognized workbook header. Expected "key" (single-file) or "namespace","key" (namespaced).'
+  );
+}
+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")}`;
+}
+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 };
 }
-
-// src/commands/find-missing/run.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(issue.key);
+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.`);
   }
-  for (const locale of Object.keys(missingByLocale)) {
-    missingByLocale[locale].sort();
+  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.`);
   }
-  const exitCode = Object.keys(missingByLocale).length === 0 ? 0 : 1;
-  return { referenceLocale, missingByLocale, exitCode };
 }
-
-// src/commands/find-missing.ts
-function registerFindMissingCommand(program) {
-  program.command("find-missing").description("Find missing translation keys across locales.").option("--reporter <kind>", "Output format: pretty | json.", "pretty").action(async (flags) => {
-    try {
-      const { referenceLocale, missingByLocale, exitCode } = await runFindMissing({
-        cwd: process.cwd()
-      });
-      if (flags.reporter === "json") {
-        console.log(JSON.stringify({ referenceLocale, missingByLocale }, null, 2));
-      } else if (Object.keys(missingByLocale).length === 0) {
-        logger.success(`No missing keys relative to ${chalk.cyan(referenceLocale)}.`);
-      } else {
-        for (const [locale, keys] of Object.entries(missingByLocale)) {
-          logger.warn(`${chalk.cyan(locale)} is missing ${keys.length} key(s):`);
-          for (const key of keys) console.log(`  - ${key}`);
-        }
-      }
-      process.exitCode = exitCode;
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      logger.error(message);
-      process.exitCode = 1;
+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 exportToExcel(options) {
-  const workbook = new ExcelJS.Workbook();
-  const sheet = workbook.addWorksheet(options.sheetName ?? "Translations");
-  const localeKeys = options.locales.map((l) => l.locale);
-  sheet.addRow(["key", ...localeKeys]);
-  const allKeys = /* @__PURE__ */ new Set();
-  const flatPerLocale = options.locales.map((l) => flatten(l.translations));
-  for (const flat of flatPerLocale) {
-    for (const k of Object.keys(flat)) allKeys.add(k);
+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 });
   }
-  for (const key of [...allKeys].sort()) {
-    sheet.addRow([key, ...flatPerLocale.map((flat) => flat[key] ?? "")]);
+}
+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;
   }
-  sheet.getRow(1).font = { bold: true };
-  await workbook.xlsx.writeFile(options.file);
+  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 importFromExcel(file, sheetName) {
-  const workbook = new ExcelJS.Workbook();
-  await workbook.xlsx.readFile(file);
-  const sheet = sheetName ? workbook.getWorksheet(sheetName) : workbook.worksheets[0];
-  if (!sheet) throw new Error(`Worksheet not found: ${sheetName ?? "<first>"}`);
-  const header = sheet.getRow(1).values;
-  const locales = header.slice(2).filter((v) => typeof v === "string");
-  const flatPerLocale = Object.fromEntries(
-    locales.map((l) => [l, {}])
-  );
-  sheet.eachRow({ includeEmpty: false }, (row, rowNumber) => {
-    if (rowNumber === 1) return;
-    const values = row.values;
-    const key = values[1];
-    if (!key) return;
-    locales.forEach((locale, idx) => {
-      const value = values[idx + 2];
-      flatPerLocale[locale][key] = typeof value === "string" ? value : "";
+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 {
-    locales: locales.map((locale) => ({
-      locale,
-      translations: unflatten(flatPerLocale[locale])
-    }))
+    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/commands/export/run.ts
 var DEFAULT_FILE = "translations.xlsx";
 var DEFAULT_SHEET = "Translations";
@@ -621,19 +883,29 @@ async function runExportExcel(options) {
     throw new Error("No LangSync config found. Run `langsync init` first.");
   }
   const { config } = loaded;
+  const referenceLocale = config.defaultLocale ?? config.locales[0];
   const file = resolve(options.cwd, options.file ?? config.excel?.file ?? DEFAULT_FILE);
   const sheetName = options.sheetName ?? config.excel?.sheetName ?? DEFAULT_SHEET;
   const files = await loadLocaleFiles({
     cwd: options.cwd,
     inputDir: config.input,
-    locales: config.locales
+    locales: config.locales,
+    namespaces: config.namespaces
   });
+  const index = indexLocaleFiles(files);
+  if (config.namespaces !== void 0 && index.namespaces.length === 0) {
+    throw noNamespacesError(referenceLocale, config.input);
+  }
   await exportToExcel({
     file,
     sheetName,
-    locales: files.map((f) => ({ locale: f.locale, translations: f.translations }))
+    files: files.map((f) => ({
+      locale: f.locale,
+      namespace: f.namespace,
+      translations: f.translations
+    }))
   });
-  return { file, sheetName, locales: files.map((f) => f.locale) };
+  return { file, sheetName, locales: config.locales, namespaces: index.namespaces };
 }
 
 // src/commands/export.ts
@@ -642,13 +914,14 @@ function registerExportCommand(program) {
   cmd.command("excel").description("Export translations to an Excel workbook.").option("--file <path>", "Output Excel file (overrides config).").option("--sheet <name>", "Worksheet name (overrides config).").action(async (flags) => {
     try {
       const cwd = process.cwd();
-      const { file, locales } = await runExportExcel({
+      const { file, locales, namespaces } = await runExportExcel({
         cwd,
         file: flags.file,
         sheetName: flags.sheet
       });
+      const namespaceSummary = namespaces.length > 0 ? ` across ${chalk.cyan(String(namespaces.length))} namespace(s)` : "";
       logger.success(
-        `Exported ${chalk.cyan(String(locales.length))} locale(s) to ${chalk.bold(
+        `Exported ${chalk.cyan(String(locales.length))} locale(s)${namespaceSummary} to ${chalk.bold(
           relative(cwd, file)
         )}`
       );
@@ -669,9 +942,18 @@ async function runImportExcel(options) {
   const { config } = loaded;
   const file = resolve(options.cwd, options.file ?? config.excel?.file ?? DEFAULT_FILE2);
   const sheetName = options.sheetName ?? config.excel?.sheetName ?? DEFAULT_SHEET2;
-  const inputAbs = resolve(options.cwd, config.input);
   const configuredLocales = new Set(config.locales);
   const result = await importFromExcel(file, sheetName);
+  if (!config.namespaces && result.format === "namespaced") {
+    throw new Error(
+      "Cannot import a namespaced workbook into a single-file project. Configure a `namespaces` block first."
+    );
+  }
+  if (config.namespaces && result.format === "single-file") {
+    throw new Error(
+      "Cannot import a single-file workbook into a namespaced project. Export a namespaced workbook or remove the `namespaces` block."
+    );
+  }
   const planned = [];
   const written = [];
   const skipped = [];
@@ -680,7 +962,13 @@ async function runImportExcel(options) {
       skipped.push(entry.locale);
       continue;
     }
-    const path = join(inputAbs, `${entry.locale}.json`);
+    const path = resolveLocaleFilePath({
+      cwd: options.cwd,
+      inputDir: config.input,
+      locale: entry.locale,
+      namespace: entry.namespace,
+      namespaces: config.namespaces
+    });
     planned.push(path);
     if (!options.dryRun) {
       await writeJson(path, entry.translations);
@@ -727,330 +1015,6 @@ var TranslationAdapterError = class extends Error {
     this.name = "TranslationAdapterError";
   }
 };
-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/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 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 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,
-      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) {
-      await writeJson(target.path, tree);
-      written.push(target.path);
-    }
-  }
-  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(
     "--max-keys <n>",
@@ -1134,21 +1098,32 @@ async function resolveWatchDir(cwd) {
   if (!loaded) {
     throw new Error("No LangSync config found. Run `langsync init` first.");
   }
+  if (loaded.config.namespaces) {
+    throw new Error(
+      "Namespace support for this command is coming in a follow-up release. Remove the `namespaces` block from your config to use single-file mode."
+    );
+  }
   return resolve(cwd, loaded.config.input);
 }
 async function runWatchPass(options) {
-  const { referenceLocale, written, unchanged, diffsByPath } = 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.");
   }
+  if (loaded.config.namespaces) {
+    throw new Error(
+      "Namespace support for this command is coming in a follow-up release. Remove the `namespaces` block from your config to use single-file mode."
+    );
+  }
+  const { referenceLocale, written, unchanged, diffsByPath } = await runSync({
+    cwd: options.cwd,
+    dryRun: options.dryRun
+  });
   const files = await loadLocaleFiles({
     cwd: options.cwd,
     inputDir: loaded.config.input,
-    locales: loaded.config.locales
+    locales: loaded.config.locales,
+    namespaces: loaded.config.namespaces
   });
   const issues = validateLocales(files, referenceLocale);
   return { referenceLocale, written, unchanged, diffsByPath, issues };
@@ -1231,7 +1206,7 @@ function registerWatchCommand(program) {
 }
 
 // src/cli.ts
-var VERSION = "0.5.0" ;
+var VERSION = "0.7.0" ;
 async function main() {
   assertNodeVersion(22);
   const program = new Command();