@mariokreitz/langsync 0.5.0 → 0.6.0

package/README.md

@@ -14,7 +14,7 @@ chaos of hand-edited JSON or fragile Excel hand-offs.
 - **Bidirectional Excel I/O** for non-technical translators.
 - **Strict validation** with CI-friendly exit codes and JSON output.
 - **Auto-detected integrations** for `i18next`, `ngx-translate`, `react-intl`.
-- **Interactive setup** that scaffolds your config and locale files.
+- **Interactive setup** that scaffolds your config and single-file or namespaced locale files.
 
 ## Install
 
@@ -59,16 +59,16 @@ npx langsync import excel
 | Command                 | Description                                                         |
 | ----------------------- | ------------------------------------------------------------------- |
 | `langsync init`         | Initialize a typed `langsync.config.ts` and scaffold locale files.  |
-| `langsync validate`     | Report missing, extra, and empty keys; exits non-zero on errors.    |
+| `langsync validate`     | Report missing, extra, and empty keys across locales/namespaces.    |
 | `langsync find-missing` | Report missing keys per locale; exits non-zero on errors.           |
-| `langsync sync`         | Synchronize keys from the reference locale into every other locale. |
+| `langsync sync`         | Synchronize reference keys into each target locale or namespace.    |
 | `langsync translate`    | Fill empty values in non-reference locales using an AI provider.    |
 | `langsync watch`        | Watch locale files and run incremental sync + validation on change. |
-| `langsync export excel` | Export all locales into a single `.xlsx` workbook.                  |
-| `langsync import excel` | Import translations from a workbook back into JSON files.           |
+| `langsync export excel` | Export locales/namespaces into a single `.xlsx` workbook.           |
+| `langsync import excel` | Import workbook translations back into configured JSON files.       |
 
-All read commands support `--reporter json`. All write commands support
-`--dry-run`.
+The `validate` and `find-missing` commands support `--reporter json`. The
+`sync`, `translate`, and `import excel` commands support `--dry-run`.
 
 ## Configuration
 
@@ -83,6 +83,9 @@ export default defineConfig({
   locales: ['en', 'de', 'fr'],
   defaultLocale: 'en',
   framework: 'i18next',
+  // Opt in to namespaced files when your project outgrows one file per locale.
+  // namespaces: { structure: 'locale-dir' }, // ./src/i18n/en/common.json
+  // namespaces: { structure: 'locale-prefix' }, // ./src/i18n/en.common.json
   excel: {
     file: 'translations.xlsx',
     sheetName: 'Translations',
@@ -95,7 +98,9 @@ export default defineConfig({
 ```
 
 JSON, JS, and MJS configs are also supported via cosmiconfig. Omit `framework`
-or set `framework: 'none'` for custom setups.
+or set `framework: 'none'` for custom setups. Omit `namespaces` for the default
+`<input>/<locale>.json` layout, or set `namespaces.structure` to `locale-dir`
+or `locale-prefix` for per-namespace files.
 
 ## Documentation
 

package/dist/cli.js

@@ -2,8 +2,8 @@
 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 { cosmiconfig } from 'cosmiconfig';
 import { TypeScriptLoader } from 'cosmiconfig-typescript-loader';
@@ -73,12 +73,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 +116,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 +167,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 +204,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 +214,7 @@ export default defineConfig({
   output: '${answers.output}',
   locales: [${localesArr}],
   defaultLocale: '${answers.defaultLocale}',
-${frameworkLine}});
+${frameworkLine}${namespacesLine}});
 `;
 }
 function renderJsonConfig(answers) {
@@ -180,8 +225,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 +258,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,6 +305,11 @@ function registerInitCommand(program) {
     }
   });
 }
+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(
@@ -255,6 +320,9 @@ var LangSyncConfigSchema = z.object({
     "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")
@@ -301,27 +369,206 @@ async function writeJson(filePath, data, { indent = 2 } = {}) {
   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);
-  const out = [];
-  for (const locale of options.locales) {
-    const path = join(inputAbs, `${locale}.json`);
-    let translations = {};
-    try {
-      const content = await readFile(path, "utf-8");
+  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 = JSON.parse(content);
+        translations = await readTranslationFile(path, `${locale}.json`);
+        exists = true;
       } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`Failed to parse ${locale}.json: ${message}`, { cause: error });
+        const errno = error.code;
+        if (errno !== "ENOENT") throw error;
       }
-    } catch (error) {
-      const errno = error.code;
-      if (errno !== "ENOENT") throw error;
+      out.push({ locale, namespace: null, path, translations, exists });
     }
-    out.push({ locale, path, translations });
+    return out;
   }
-  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
+  };
 }
 
 // ../core/dist/index.js
@@ -409,6 +656,13 @@ function hasChanges(diff) {
   return diff.added.length > 0 || diff.removed.length > 0 || diff.changed.length > 0;
 }
 
+// src/commands/shared/namespace-error.ts
+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/sync/run.ts
 async function runSync(options) {
   const loaded = await loadConfig(options.cwd);
@@ -420,29 +674,43 @@ async function runSync(options) {
   const files = await loadLocaleFiles({
     cwd: options.cwd,
     inputDir: config.input,
-    locales: config.locales
+    locales: config.locales,
+    namespaces: config.namespaces
   });
-  const reference = files.find((f) => f.locale === referenceLocale);
-  if (!reference) {
+  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 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);
+  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 };
@@ -485,9 +753,30 @@ async function runValidate(options) {
   const files = await loadLocaleFiles({
     cwd: options.cwd,
     inputDir: config.input,
-    locales: config.locales
+    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 issues = validateLocales(files, referenceLocale);
   const hasErrors = issues.some((i) => i.type === "missing" || i.type === "extra");
   return {
     referenceLocale,
@@ -497,6 +786,9 @@ async function runValidate(options) {
 }
 
 // src/commands/validate.ts
+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 {
@@ -511,7 +803,7 @@ function registerValidateCommand(program) {
           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}`);
+            logger.info(`${colored}  ${chalk.cyan(issue.locale)}  ${formatIssueKey(issue)}`);
           }
           console.log();
           logger.info(
@@ -534,16 +826,25 @@ async function runFindMissing(options) {
   const missingByLocale = {};
   for (const issue of issues) {
     if (issue.type !== "missing") continue;
-    (missingByLocale[issue.locale] ??= []).push(issue.key);
+    (missingByLocale[issue.locale] ??= []).push({
+      namespace: issue.namespace,
+      key: issue.key,
+      path: issue.path
+    });
   }
-  for (const locale of Object.keys(missingByLocale)) {
-    missingByLocale[locale].sort();
+  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 };
 }
 
 // src/commands/find-missing.ts
+function formatMissingEntry(entry) {
+  return entry.namespace === null ? entry.key : `${entry.namespace}:${entry.key}`;
+}
 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 {
@@ -557,7 +858,7 @@ function registerFindMissingCommand(program) {
       } 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}`);
+          for (const entry of keys) console.log(`  - ${formatMissingEntry(entry)}`);
         }
       }
       process.exitCode = exitCode;
@@ -568,49 +869,159 @@ function registerFindMissingCommand(program) {
     }
   });
 }
+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 locales;
+}
+function cellText(value) {
+  return typeof value === "string" ? value : "";
+}
+function addHeader(sheet, header) {
+  sheet.addRow(header);
+  sheet.getRow(1).font = { bold: true };
+}
+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 [...allKeys].sort()) {
+    sheet.addRow([key, ...locales.map((locale) => flatByLocale.get(locale)?.[key] ?? "")]);
+  }
+}
+function namespacedKey(namespace, locale) {
+  return `${namespace}\0${locale}`;
+}
+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 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] ?? ""
+      )
+    ]);
+  }
+}
 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);
+  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.");
   }
-  for (const key of [...allKeys].sort()) {
-    sheet.addRow([key, ...flatPerLocale.map((flat) => flat[key] ?? "")]);
+  if (allSingleFile) {
+    exportSingleFile(sheet, options.files);
+  } else {
+    exportNamespaced(sheet, options.files);
   }
-  sheet.getRow(1).font = { bold: true };
   await workbook.xlsx.writeFile(options.file);
 }
-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");
+function importSingleFile(sheet, header) {
+  const locales = header.slice(2).filter((value) => typeof value === "string");
   const flatPerLocale = Object.fromEntries(
-    locales.map((l) => [l, {}])
+    locales.map((locale) => [locale, {}])
   );
   sheet.eachRow({ includeEmpty: false }, (row, rowNumber) => {
     if (rowNumber === 1) return;
     const values = row.values;
-    const key = values[1];
+    const key = cellText(values[1]);
     if (!key) return;
     locales.forEach((locale, idx) => {
-      const value = values[idx + 2];
-      flatPerLocale[locale][key] = typeof value === "string" ? value : "";
+      flatPerLocale[locale][key] = cellText(values[idx + 2]);
     });
   });
   return {
+    format: "single-file",
     locales: locales.map((locale) => ({
       locale,
+      namespace: null,
       translations: unflatten(flatPerLocale[locale])
     }))
   };
 }
+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]);
+    });
+  });
+  return {
+    format: "namespaced",
+    locales: locales.flatMap(
+      (locale) => [...namespaces].map((namespace) => ({
+        locale,
+        namespace,
+        translations: unflatten(flatByLocaleNamespace.get(namespacedKey(namespace, locale)) ?? {})
+      }))
+    )
+  };
+}
+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).'
+  );
+}
 
 // src/commands/export/run.ts
 var DEFAULT_FILE = "translations.xlsx";
@@ -621,19 +1032,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 +1063,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 +1091,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 +1111,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);
@@ -973,6 +1410,12 @@ async function fillEmptyTranslations(options) {
 }
 
 // src/commands/translate/run.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 loadConfig(options.cwd);
   if (!loaded) {
@@ -981,62 +1424,101 @@ async function runTranslate(options) {
   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
+    locales: config.locales,
+    namespaces: config.namespaces
   });
-  const reference = files.find((f) => f.locale === referenceLocale);
-  if (!reference) {
+  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 targets = files.filter((f) => f.locale !== referenceLocale);
-  const refFlat = flatten(reference.translations);
+  const adapter = createAdapter({
+    provider,
+    apiKey: config.ai?.apiKey,
+    model: options.model ?? config.ai?.model
+  });
   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 });
+  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 perLocaleMaxKeys = {};
+  const limitedByPath = /* @__PURE__ */ new Map();
+  const skippedCandidates = options.maxKeys ? allCandidates.slice(options.maxKeys) : [];
   for (const candidate of limited) {
-    perLocaleMaxKeys[candidate.file.locale] = (perLocaleMaxKeys[candidate.file.locale] ?? 0) + 1;
+    const entries = limitedByPath.get(candidate.path) ?? [];
+    entries.push(candidate);
+    limitedByPath.set(candidate.path, entries);
   }
   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);
+  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 {
@@ -1134,21 +1616,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 +1724,7 @@ function registerWatchCommand(program) {
 }
 
 // src/cli.ts
-var VERSION = "0.5.0" ;
+var VERSION = "0.6.0" ;
 async function main() {
   assertNodeVersion(22);
   const program = new Command();

package/dist/index.js

@@ -3,6 +3,11 @@ import 'cosmiconfig';
 import 'cosmiconfig-typescript-loader';
 import { z } from 'zod';
 
+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."
+  )
+});
 z.object({
   input: z.string().describe("Path to the source i18n directory."),
   output: z.string().default("./translations").describe(
@@ -13,6 +18,9 @@ z.object({
     "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")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mariokreitz/langsync",
-  "version": "0.5.0",
+  "version": "0.6.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.2.0",
-    "@langsync/excel-engine": "0.1.1",
-    "@langsync/core": "0.1.1",
-    "@langsync/ai-engine": "0.2.0"
+    "@langsync/shared": "0.2.1",
+    "@langsync/core": "0.1.2",
+    "@langsync/ai-engine": "0.2.1",
+    "@langsync/excel-engine": "0.2.0"
   },
   "scripts": {
     "build": "tsup",