@xndrjs/i18n 0.3.3 → 0.5.0-alpha.0

package/src/codegen/generate-i18n-types.ts

@@ -1,6 +1,11 @@
 import fs from "node:fs";
 import path from "node:path";
-import { loadConfig, resolveLoadOnInit, resolveNamespaces } from "./config.js";
+import {
+  loadConfig,
+  resolveDeliveryOutputDir,
+  resolveLoadOnInit,
+  resolveNamespaces,
+} from "./config.js";
 import { formatDictionaryFile } from "./emit/dictionary-file.js";
 import {
   formatDictionarySchemaFile,
@@ -10,11 +15,18 @@ import { formatInstanceFile } from "./emit/instance-file.js";
 import { formatNamespaceLoadersFile } from "./emit/namespace-loaders-file.js";
 import { formatTypesFile } from "./emit/types-file.js";
 import { analyzeDictionaries } from "./icu-analysis.js";
-import { collectRequestLocales, validateCodegenLocaleFallback } from "./locale-fallback.js";
+import { getDeliveryArtifactsIssues } from "./delivery-artifacts.js";
+import { collectRequestLocales, getCodegenLocaleFallbackIssues } from "./locale-fallback.js";
 import { enrichLocaleFallback } from "./locale-policy.js";
-import { fail, resolveImportExtension, toModuleBasename } from "./paths.js";
+import { reportCodegenIssues, resolveImportExtension, toModuleBasename } from "./paths.js";
 import { prepareDictionaryEntries } from "./read-dictionary.js";
+import { writeFileIfChanged } from "./write-file-if-changed.js";
 
+/**
+ * Codegen CLI entry point. Pipeline:
+ * config → analyze (ICU + types input) → validate locale/delivery policy →
+ * prepare artifacts (YAML→JSON, split) → resolve lazy/eager → emit generated .ts files.
+ */
 function main() {
   const configArgIndex = process.argv.indexOf("--config");
   const configPath = path.resolve(
@@ -24,47 +36,29 @@ function main() {
   const projectRoot = path.dirname(configPath);
 
   if (!fs.existsSync(configPath)) {
-    fail(`[Codegen Error] Config file not found: ${configPath}`);
+    throw new Error(`[Codegen Error] Config file not found: ${configPath}`);
   }
 
   const config = loadConfig(configPath);
   const sourceEntries = resolveNamespaces(config);
-  const generatedDirRelative = path.dirname(config.typesOutput);
-  let resolvedEntries;
-  let compiledFiles: string[];
-
-  try {
-    const prepared = prepareDictionaryEntries(projectRoot, sourceEntries, generatedDirRelative);
-    resolvedEntries = prepared.resolvedEntries;
-    compiledFiles = prepared.compiledFiles;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    fail(message);
-  }
-
-  const entries = resolvedEntries;
+  const deliveryOutputRelative = resolveDeliveryOutputDir(config);
+  const delivery = config.delivery ?? "canonical";
   const isSingle = Boolean(config.dictionary);
-  const { loadOnInitSet, lazyEntries, hasLazy } = resolveLoadOnInit(config, entries, isSingle);
-
-  if (hasLazy && !config.dictionarySchemaOutput) {
-    fail(
-      '[Codegen Error] Lazy namespaces require "dictionarySchemaOutput" for validateExternalNamespace.'
-    );
-  }
-
-  const typesOutputPath = path.resolve(projectRoot, config.typesOutput);
-  const dictionaryOutputPath = path.resolve(projectRoot, config.dictionaryOutput);
-  const instanceOutputPath = path.resolve(projectRoot, config.instanceOutput);
 
-  const analysisResult = analyzeDictionaries(projectRoot, entries);
+  const analysisResult = analyzeDictionaries(projectRoot, sourceEntries);
   if (!analysisResult.ok) {
     process.exit(1);
   }
 
-  const { paramsByNamespace, argsSpecByNamespace, locales } = analysisResult.analysis;
+  const { paramsByNamespace, argsSpecByNamespace, locales, dictionariesByNamespace } =
+    analysisResult.analysis;
 
-  if (config.localeFallback && validateCodegenLocaleFallback(config.localeFallback, locales)) {
-    process.exit(1);
+  if (config.localeFallback) {
+    const localeFallbackIssues = getCodegenLocaleFallbackIssues(config.localeFallback, locales);
+    if (localeFallbackIssues.length > 0) {
+      reportCodegenIssues(localeFallbackIssues);
+      process.exit(1);
+    }
   }
 
   const paramsTypeName = config.paramsTypeName;
@@ -74,14 +68,55 @@ function main() {
   const localeFallbackTypeName = `${localeTypeName}Fallback`;
   const factoryName = config.factoryName ?? "createI18n";
   const importExtension = resolveImportExtension(config);
-  const typesModule = toModuleBasename(typesOutputPath);
 
   const requestLocales = collectRequestLocales(locales, config.localeFallback);
-  const requestLocaleUnion = [...requestLocales]
+  const requestLocalesList = [...requestLocales].sort();
+
+  if (delivery === "custom" && config.deliveryArtifacts) {
+    const deliveryArtifactsIssues = getDeliveryArtifactsIssues(
+      config.deliveryArtifacts,
+      requestLocales
+    );
+    if (deliveryArtifactsIssues.length > 0) {
+      reportCodegenIssues(deliveryArtifactsIssues);
+      process.exit(1);
+    }
+  }
+
+  const {
+    resolvedEntries: entries,
+    splitPathsByNamespace,
+    compiledFiles,
+  } = prepareDictionaryEntries(projectRoot, sourceEntries, deliveryOutputRelative, {
+    dictionariesByNamespace,
+    delivery,
+    localeFallback: config.localeFallback,
+    requestLocales: delivery === "split-by-locale" ? requestLocalesList : undefined,
+    deliveryArtifacts: delivery === "custom" ? config.deliveryArtifacts : undefined,
+  });
+
+  const { loadOnInitSet, lazyEntries, hasLazy } = resolveLoadOnInit(config, entries, isSingle);
+
+  const typesOutputPath = path.resolve(projectRoot, config.typesOutput);
+  const dictionaryOutputPath = path.resolve(projectRoot, config.dictionaryOutput);
+  const instanceOutputPath = path.resolve(projectRoot, config.instanceOutput);
+  const typesModule = toModuleBasename(typesOutputPath);
+
+  const requestLocaleUnion = requestLocalesList
     .sort()
     .map((locale) => `'${locale}'`)
     .join(" | ");
 
+  const deliveryAreaNames =
+    delivery === "custom" && config.deliveryArtifacts
+      ? Object.keys(config.deliveryArtifacts).sort()
+      : undefined;
+  const deliveryAreaTypeName =
+    delivery === "custom" ? schemaTypeName.replace(/Schema$/, "DeliveryArea") : undefined;
+  const deliveryAreaUnion = deliveryAreaNames
+    ? deliveryAreaNames.map((area) => `'${area}'`).join(" | ")
+    : undefined;
+
   const eagerEntries = hasLazy
     ? entries.filter((entry) => loadOnInitSet.has(entry.namespace))
     : entries;
@@ -103,6 +138,15 @@ function main() {
     localeFallback: localeFallbackForEmit,
     paramsByNamespace,
     requestLocaleUnion,
+    ...(deliveryAreaTypeName && deliveryAreaUnion
+      ? {
+          deliveryAreaTypeName,
+          deliveryAreaUnion,
+          ...(delivery === "custom" && config.deliveryArtifacts
+            ? { deliveryArtifacts: config.deliveryArtifacts }
+            : {}),
+        }
+      : {}),
     hasLazy,
     loadOnInitSet,
     lazyEntries,
@@ -117,14 +161,20 @@ function main() {
     dictionaryOutputPath,
     typesOutputPath,
     schemaTypeName,
+    localeTypeName,
     importExtension,
+    delivery,
+    splitPathsByNamespace,
+    ...(delivery === "split-by-locale" ? { requestLocales: requestLocalesList } : {}),
+    ...(delivery === "custom" && deliveryAreaTypeName && deliveryAreaNames
+      ? { deliveryAreaTypeName, deliveryAreaNames }
+      : {}),
   });
 
   const instanceContent = formatInstanceFile({
     isSingle,
     hasLazy,
     typesOutputPath,
-    dictionaryOutputPath,
     paramsTypeName,
     schemaTypeName,
     localeTypeName,
@@ -134,16 +184,12 @@ function main() {
     hasLocaleType: Boolean(requestLocaleUnion),
     namespaceNames: entries.map((entry) => entry.namespace),
     importExtension,
+    delivery,
   });
 
-  fs.mkdirSync(path.dirname(typesOutputPath), { recursive: true });
-  fs.writeFileSync(typesOutputPath, typesContent);
-
-  fs.mkdirSync(path.dirname(dictionaryOutputPath), { recursive: true });
-  fs.writeFileSync(dictionaryOutputPath, dictionaryContent);
-
-  fs.mkdirSync(path.dirname(instanceOutputPath), { recursive: true });
-  fs.writeFileSync(instanceOutputPath, instanceContent);
+  writeFileIfChanged(typesOutputPath, typesContent);
+  writeFileIfChanged(dictionaryOutputPath, dictionaryContent);
+  writeFileIfChanged(instanceOutputPath, instanceContent);
 
   const generatedFiles = [
     path.relative(projectRoot, typesOutputPath),
@@ -162,8 +208,7 @@ function main() {
       importExtension
     );
 
-    fs.mkdirSync(path.dirname(dictionarySchemaOutputPath), { recursive: true });
-    fs.writeFileSync(dictionarySchemaOutputPath, dictionarySchemaContent);
+    writeFileIfChanged(dictionarySchemaOutputPath, dictionarySchemaContent);
     generatedFiles.push(path.relative(projectRoot, dictionarySchemaOutputPath));
   }
 
@@ -173,24 +218,27 @@ function main() {
       config.namespaceLoadersOutput ??
         path.join(path.dirname(config.instanceOutput), "namespace-loaders.generated.ts")
     );
-    const dictionarySchemaOutputPath = path.resolve(projectRoot, config.dictionarySchemaOutput!);
     const lazyEntriesWithPaths = lazyEntries.map((entry) => ({
       ...entry,
       absolutePath: path.resolve(projectRoot, entry.filePath),
     }));
-    const namespaceLoadersContent = formatNamespaceLoadersFile(
-      namespaceLoadersOutputPath,
-      lazyEntriesWithPaths,
+    const namespaceLoadersContent = formatNamespaceLoadersFile({
+      loadersOutputPath: namespaceLoadersOutputPath,
+      lazyEntries: lazyEntriesWithPaths,
       schemaTypeName,
+      localeTypeName,
       typesModule,
-      toModuleBasename(dictionarySchemaOutputPath),
-      toModuleBasename(instanceOutputPath),
-      factoryName,
-      importExtension
-    );
+      importExtension,
+      projectRoot,
+      delivery,
+      splitPathsByNamespace,
+      ...(delivery === "split-by-locale" ? { requestLocales: requestLocalesList } : {}),
+      ...(delivery === "custom" && deliveryAreaTypeName && deliveryAreaNames
+        ? { deliveryAreaTypeName, deliveryAreaNames }
+        : {}),
+    });
 
-    fs.mkdirSync(path.dirname(namespaceLoadersOutputPath), { recursive: true });
-    fs.writeFileSync(namespaceLoadersOutputPath, namespaceLoadersContent);
+    writeFileIfChanged(namespaceLoadersOutputPath, namespaceLoadersContent);
     generatedFiles.push(path.relative(projectRoot, namespaceLoadersOutputPath));
   }
 
@@ -200,4 +248,9 @@ function main() {
   }
 }
 
-main();
+try {
+  main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/src/codegen/icu-analysis.ts

@@ -6,7 +6,7 @@ import {
   mergeVariableMetaAcrossLocales,
   type VariableSpec,
 } from "../icu/extract-variables.js";
-import type { NamespaceEntry } from "./types.js";
+import type { DictionaryJson, NamespaceEntry } from "./types.js";
 import { readDictionaryFile } from "./read-dictionary.js";
 
 export function paramsTypeForVariables(variables: VariableSpec): string {
@@ -26,8 +26,13 @@ export interface DictionaryAnalysis {
   paramsByNamespace: Record<string, Record<string, string>>;
   argsSpecByNamespace: Record<string, Record<string, VariableSpec>>;
   locales: Set<string>;
+  dictionariesByNamespace: Record<string, DictionaryJson>;
 }
 
+/**
+ * Phase 1 of codegen: read source dictionaries, validate ICU syntax, infer param types.
+ * Output feeds type emission, optional `DICTIONARY_SPEC`, and `prepareDictionaryEntries`.
+ */
 export function analyzeDictionaries(
   projectRoot: string,
   entries: NamespaceEntry[]
@@ -35,6 +40,7 @@ export function analyzeDictionaries(
   const paramsByNamespace: Record<string, Record<string, string>> = {};
   const argsSpecByNamespace: Record<string, Record<string, VariableSpec>> = {};
   const locales = new Set<string>();
+  const dictionariesByNamespace: Record<string, DictionaryJson> = {};
   let hasErrors = false;
 
   for (const entry of entries) {
@@ -49,6 +55,7 @@ export function analyzeDictionaries(
     }
 
     const dictionary = readDictionaryFile(absolutePath);
+    dictionariesByNamespace[entry.namespace] = dictionary;
     paramsByNamespace[entry.namespace] = {};
     argsSpecByNamespace[entry.namespace] = {};
 
@@ -98,6 +105,6 @@ export function analyzeDictionaries(
 
   return {
     ok: true,
-    analysis: { paramsByNamespace, argsSpecByNamespace, locales },
+    analysis: { paramsByNamespace, argsSpecByNamespace, locales, dictionariesByNamespace },
   };
 }

package/src/codegen/locale-fallback.ts

@@ -1,5 +1,9 @@
 import { validateLocaleFallback } from "../resolve-locale.js";
 
+/**
+ * Union of locales found in dictionaries plus every locale referenced by `localeFallback`.
+ * Drives split-by-locale partitioning and the generated locale union type.
+ */
 export function collectRequestLocales(
   dictionaryLocales: Set<string>,
   fallback?: Record<string, string | null>
@@ -19,30 +23,35 @@ export function collectRequestLocales(
   return all;
 }
 
-export function validateCodegenLocaleFallback(
+export type LocaleFallbackIssue = {
+  path: (string | number)[];
+  message: string;
+};
+
+/** Pre-emit validation gate for `localeFallback` config against discovered dictionary locales. */
+export function getCodegenLocaleFallbackIssues(
   fallback: Record<string, string | null>,
   dictionaryLocales: Set<string>
-): boolean {
-  let hasErrors = false;
+): LocaleFallbackIssue[] {
+  const issues: LocaleFallbackIssue[] = [];
 
   try {
     validateLocaleFallback(fallback);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    console.error(`[Codegen Error] ${message}`);
-    hasErrors = true;
+    issues.push({ path: ["localeFallback"], message });
   }
 
   for (const [locale, target] of Object.entries(fallback)) {
     if (target !== null && !(target in fallback) && !dictionaryLocales.has(target)) {
-      console.error(
-        `[Codegen Error] localeFallback: "${locale}" points to "${target}" which is not defined in the fallback map or dictionary locales`
-      );
-      hasErrors = true;
+      issues.push({
+        path: ["localeFallback", locale],
+        message: `localeFallback: "${locale}" points to "${target}" which is not defined in the fallback map or dictionary locales`,
+      });
     }
   }
 
-  return hasErrors;
+  return issues;
 }
 
 export function formatLocaleFallbackBlock(

package/src/codegen/locale-policy.ts

@@ -7,6 +7,10 @@ export function buildRequiredLocales(
   return [...collectRequestLocales(dictionaryLocales, configFallback)].sort();
 }
 
+/**
+ * Completes `localeFallback` with explicit `null` entries for every request locale,
+ * producing a stable map emitted into `i18n-types.generated.ts`.
+ */
 export function enrichLocaleFallback(
   dictionaryLocales: Set<string>,
   configFallback: Record<string, string | null>

package/src/codegen/paths.ts

@@ -6,10 +6,10 @@ import { CodegenConfig } from "./codegen-config-schema.js";
 export const GENERATED_FILE_BANNER = "// Automatically generated code. Do not edit manually.\n";
 export const DEFAULT_IMPORT_EXTENSION: ImportExtension = "none";
 
-export function fail(message: string): never {
-  console.error(message);
-  process.exit(1);
-  throw new Error(message);
+export function reportCodegenIssues(issues: readonly { message: string }[]): void {
+  for (const issue of issues) {
+    console.error(`[Codegen Error] ${issue.message}`);
+  }
 }
 
 export function toImportPath(fromFile: string, toFile: string): string {
@@ -27,7 +27,7 @@ export function resolveImportExtension(
 ): ImportExtension {
   const extension = config.importExtension ?? DEFAULT_IMPORT_EXTENSION;
   if (!SUPPORTED_IMPORT_EXTENSIONS.includes(extension)) {
-    fail(
+    throw new Error(
       `[Codegen Error] importExtension must be "none", ".ts", or ".js", got ${JSON.stringify(extension)}.`
     );
   }
@@ -52,3 +52,7 @@ export function toImportIdentifier(namespace: string): string {
   }
   return `${safe}Ns`;
 }
+
+export function toLocaleObjectKey(locale: string): string {
+  return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(locale) ? locale : JSON.stringify(locale);
+}

package/src/codegen/project-locales-set-namespace.test.ts

@@ -95,7 +95,7 @@ function writeTscProject(tempDir: string) {
   );
 }
 
-describe("codegen projectLocales + setNamespace", () => {
+describe("codegen projectDictionaryLocales + setNamespace", () => {
   describe("generated instance output", () => {
     let tempDir: string;
 
@@ -112,7 +112,7 @@ describe("codegen projectLocales + setNamespace", () => {
       const factory = readFileSync(join(tempDir, "src/i18n/instance.generated.ts"), "utf8");
       expect(factory).toContain('dictionary: AppSchema["billing"]');
       expect(factory).toContain(
-        "projectNamespacesLocalesCore(dictionary, locales, LOCALE_FALLBACK)"
+        "projectDictionaryLocalesCore(dictionary, locales, LOCALE_FALLBACK)"
       );
     });
 
@@ -124,9 +124,10 @@ describe("codegen projectLocales + setNamespace", () => {
         join(tempDir, "src/hydrate-billing.ts"),
         [
           `import { createI18n, projectNamespaceLocales } from "./i18n/instance.generated.js";`,
+          `import { defaultDictionary } from "./i18n/dictionary.generated.js";`,
           `import billingDictionary from "./i18n/translations/billing.json";`,
           ``,
-          `const i18n = createI18n();`,
+          `const i18n = createI18n(defaultDictionary);`,
           `i18n.setNamespace("billing", projectNamespaceLocales(billingDictionary, ["en"]));`,
         ].join("\n")
       );
@@ -137,25 +138,26 @@ describe("codegen projectLocales + setNamespace", () => {
       expect(tsc.status, `${tsc.stdout}\n${tsc.stderr}`).toBe(0);
     });
 
-    it("passes tsc when replacing the full schema with projectLocales before setAll", () => {
+    it("passes tsc when replacing the full schema with projectDictionaryLocales before setAll", () => {
       tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-project-locales-"));
       setupMultiCodegenFixture(tempDir);
 
       writeFileSync(
         join(tempDir, "src/hydrate-all.ts"),
         [
-          `import { createI18n, projectLocales } from "./i18n/instance.generated.js";`,
+          `import { createI18n, projectDictionaryLocales } from "./i18n/instance.generated.js";`,
+          `import { defaultDictionary } from "./i18n/dictionary.generated.js";`,
           `import type { AppSchema } from "./i18n/i18n-types.generated.js";`,
           `import billingDictionary from "./i18n/translations/billing.json";`,
-          `import defaultDictionary from "./i18n/translations/default.json";`,
+          `import defaultNs from "./i18n/translations/default.json";`,
           ``,
           `const fullDictionary = {`,
-          `  default: defaultDictionary,`,
+          `  default: defaultNs,`,
           `  billing: billingDictionary,`,
           `} satisfies AppSchema;`,
           ``,
-          `const i18n = createI18n();`,
-          `i18n.setAll(projectLocales(fullDictionary, ["en"]));`,
+          `const i18n = createI18n(defaultDictionary);`,
+          `i18n.setAll(projectDictionaryLocales(fullDictionary, ["en"]));`,
         ].join("\n")
       );