@xndrjs/i18n 0.3.3 → 0.5.0-alpha.0

package/src/IcuTranslationProviderSingle.ts

@@ -1,15 +1,12 @@
-import { IntlMessageFormat } from "intl-messageformat";
 import { cloneAndFreeze } from "./deep-freeze.js";
-import {
-  formatLocaleFallbackChain,
-  resolveLocaleTemplate,
-  validateLocaleFallback,
-} from "./resolve-locale.js";
+import { resolveAndFormat } from "./format-core.js";
+import { validateLocaleFallback } from "./resolve-locale.js";
 import type {
   IcuTranslationProviderOptions,
   KeyDictionary,
   LocaleFallbackMap,
   LocaleOfSingle,
+  OnMissingTranslation,
   SingleCompiledCache,
 } from "./types.js";
 
@@ -63,13 +60,8 @@ export class IcuTranslationProviderSingleForLocale<
     key: K,
     ...args: Params[K] extends never ? [] : [params: Params[K]]
   ): string {
-    return (
-      this.provider.get as (
-        key: K,
-        locale: Locale,
-        ...params: Params[K] extends never ? [] : [params: Params[K]]
-      ) => string
-    )(key, this.locale, ...args);
+    const params = args[0] as Record<string, unknown> | undefined;
+    return this.provider.getWithLocale(String(key), this.locale, params);
   }
 }
 
@@ -82,6 +74,7 @@ export class IcuTranslationProviderSingle<
   private dictionary: Schema;
   private compiledCache: SingleCompiledCache = {};
   private readonly localeFallback?: Fallback;
+  private readonly onMissing: OnMissingTranslation;
 
   constructor(dictionary: Schema, options?: IcuTranslationProviderOptions<Fallback>) {
     this.dictionary = structuredClone(dictionary);
@@ -89,6 +82,7 @@ export class IcuTranslationProviderSingle<
       validateLocaleFallback(options.localeFallback);
       this.localeFallback = options.localeFallback;
     }
+    this.onMissing = options?.onMissing ?? "throw";
   }
 
   get<K extends keyof Schema & string>(
@@ -97,45 +91,27 @@ export class IcuTranslationProviderSingle<
     ...args: Params[K] extends never ? [] : [params: Params[K]]
   ): string {
     const params = args[0] as Record<string, unknown> | undefined;
-    const resolved = resolveLocaleTemplate(this.dictionary[key], locale, this.localeFallback);
-
-    if (!resolved) {
-      const chain = formatLocaleFallbackChain(locale, this.localeFallback);
-      throw new Error(
-        `[i18n] Missing key or locale: "${String(key)}" [${locale}] (fallback chain: ${chain})`
-      );
-    }
-
-    const { template, resolvedLocale } = resolved;
-
-    if (!this.compiledCache[resolvedLocale]) {
-      this.compiledCache[resolvedLocale] = {};
-    }
-
-    const cacheKey = String(key);
-
-    if (!this.compiledCache[resolvedLocale][cacheKey]) {
-      try {
-        this.compiledCache[resolvedLocale][cacheKey] = new IntlMessageFormat(
-          template,
-          resolvedLocale
-        );
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        throw new Error(
-          `[i18n ICU Syntax Error] Dictionary error for key "${String(key)}" [${resolvedLocale}]: ${message}`
-        );
-      }
-    }
+    return this.getWithLocale(String(key), locale, params);
+  }
 
-    try {
-      return this.compiledCache[resolvedLocale][cacheKey].format(params) as string;
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      throw new Error(
-        `[i18n Formatting Error] Invalid or missing parameters for key "${String(key)}" [${resolvedLocale}]: ${message}`
-      );
-    }
+  getWithLocale(key: string, locale: string, params?: Record<string, unknown>): string {
+    return resolveAndFormat({
+      localeByKey: this.dictionary[key],
+      locale,
+      params,
+      getCache: (resolvedLocale) => {
+        if (!this.compiledCache[resolvedLocale]) {
+          this.compiledCache[resolvedLocale] = {};
+        }
+        return this.compiledCache[resolvedLocale]!;
+      },
+      context: {
+        key,
+        locale,
+        localeFallback: this.localeFallback,
+        onMissing: this.onMissing,
+      },
+    });
   }
 
   forLocale<Locale extends RequestLocales>(

package/src/audit/audit-dictionaries.ts

@@ -59,6 +59,10 @@ function collectDictionaryLocales(namespaces: Record<string, DictionaryJson>): S
   return locales;
 }
 
+/**
+ * Audit pipeline: reports missing translations per namespace/locale (direct and
+ * effective via fallback), using the same locale policy as codegen.
+ */
 export function auditDictionaries(options: AuditDictionariesOptions): I18nAuditReport {
   const { namespaces, config, treatEmptyAsMissing = true } = options;
   const dictionaryLocales = collectDictionaryLocales(namespaces);
@@ -137,7 +141,6 @@ export function reportHasGaps(report: I18nAuditReport, criterion: FailOnCriterio
 export interface RunAuditOptions {
   projectRoot: string;
   config: CodegenConfig;
-  configPath: string;
   treatEmptyAsMissing?: boolean;
   failOn?: FailOnCriterion;
 }

package/src/audit/run-audit.test.ts

@@ -4,7 +4,7 @@ import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { dirname } from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { parseAuditArgs, runAuditCli } from "./run-audit.js";
 
 const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
@@ -119,6 +119,40 @@ describe("runAuditCli", () => {
     }
   });
 
+  it("exits 2 with an error message when the config is invalid", async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-audit-"));
+    mkdirSync(join(tempDir, "i18n"), { recursive: true });
+    writeFileSync(
+      join(tempDir, "i18n/i18n.codegen.json"),
+      JSON.stringify({ namespaces: { default: "translations/default.json" } })
+    );
+
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => void 0);
+    const previousCwd = process.cwd();
+    process.chdir(tempDir);
+    try {
+      const exitCode = await runAuditCli(["--config", "i18n/i18n.codegen.json"]);
+      expect(exitCode).toBe(2);
+      expect(String(errorSpy.mock.calls[0]?.[0])).toContain("Invalid i18n.codegen.json");
+    } finally {
+      process.chdir(previousCwd);
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("exits 2 with an error message when --fail-on has an invalid value", async () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => void 0);
+    try {
+      const exitCode = await runAuditCli(["--fail-on", "bogus"]);
+      expect(exitCode).toBe(2);
+      expect(String(errorSpy.mock.calls[0]?.[0])).toContain(
+        "[Audit Error] --fail-on must be one of: effective, direct, any"
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
   it("runs through the bin wrapper", () => {
     writeFixture({
       login_button: { en: "Login" },

package/src/audit/run-audit.ts

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
+import type { CodegenConfig } from "../codegen/codegen-config-schema.js";
 import { loadConfig } from "../codegen/config.js";
-import { fail } from "../codegen/paths.js";
 import { type FailOnCriterion, runAuditFromConfig } from "./audit-dictionaries.js";
 
 const FAIL_ON_VALUES = new Set<FailOnCriterion>(["effective", "direct", "any"]);
@@ -30,7 +30,7 @@ export function parseAuditArgs(argv: string[]): AuditCliOptions {
   if (failOnArgIndex >= 0) {
     const value = argv[failOnArgIndex + 1];
     if (!value || !FAIL_ON_VALUES.has(value as FailOnCriterion)) {
-      fail(`[Audit Error] --fail-on must be one of: effective, direct, any`);
+      throw new Error(`[Audit Error] --fail-on must be one of: effective, direct, any`);
     }
     failOn = value as FailOnCriterion;
   }
@@ -46,20 +46,28 @@ export function parseAuditArgs(argv: string[]): AuditCliOptions {
 }
 
 export async function runAuditCli(argv = process.argv.slice(2)): Promise<number> {
-  const options = parseAuditArgs(argv);
+  let options: AuditCliOptions;
+  let config: CodegenConfig;
 
-  if (!fs.existsSync(options.configPath)) {
-    console.error(`[Audit Error] Config file not found: ${options.configPath}`);
+  try {
+    options = parseAuditArgs(argv);
+
+    if (!fs.existsSync(options.configPath)) {
+      console.error(`[Audit Error] Config file not found: ${options.configPath}`);
+      return 2;
+    }
+
+    config = loadConfig(options.configPath);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
     return 2;
   }
 
   const projectRoot = path.dirname(options.configPath);
-  const config = loadConfig(options.configPath);
 
   const { report, exitCode } = await runAuditFromConfig({
     projectRoot,
     config,
-    configPath: options.configPath,
     treatEmptyAsMissing: options.treatEmptyAsMissing,
     ...(options.failOn !== undefined ? { failOn: options.failOn } : {}),
   });

package/src/codegen/codegen-config-schema.ts

@@ -1,7 +1,17 @@
 import { z } from "zod";
-import { SUPPORTED_IMPORT_EXTENSIONS } from "./constants.js";
+import path from "node:path";
+import {
+  IDENTIFIER_NAME_PATTERN,
+  IDENTIFIER_NAME_REQUIREMENT,
+  SUPPORTED_IMPORT_EXTENSIONS,
+} from "./constants.js";
+import { getDeliveryArtifactsStructureIssues } from "./delivery-artifacts.js";
 
 const localeFallbackSchema = z.record(z.string(), z.union([z.string(), z.null()]));
+const deliveryArtifactsSchema = z.record(z.string(), z.array(z.string().min(1)));
+
+export const DELIVERY_MODES = ["canonical", "split-by-locale", "custom"] as const;
+export type DeliveryMode = (typeof DELIVERY_MODES)[number];
 
 const codegenConfigShape = {
   dictionary: z.string().min(1).optional(),
@@ -20,6 +30,9 @@ const codegenConfigShape = {
   localeFallbackConstName: z.string().min(1).optional(),
   localeFallback: localeFallbackSchema.optional(),
   factoryName: z.string().min(1).optional(),
+  delivery: z.enum(DELIVERY_MODES).optional().default("canonical"),
+  deliveryArtifacts: deliveryArtifactsSchema.optional(),
+  deliveryOutput: z.string().min(1).optional(),
 };
 
 export const codegenConfigKeys = Object.keys(
@@ -39,10 +52,64 @@ export const codegenConfigSchema = z
         message: 'Specify exactly one of "dictionary" or "namespaces".',
       });
     }
+
+    if (config.namespaces) {
+      for (const namespace of Object.keys(config.namespaces)) {
+        if (!IDENTIFIER_NAME_PATTERN.test(namespace)) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["namespaces", namespace],
+            message: `Invalid namespace name "${namespace}" (${IDENTIFIER_NAME_REQUIREMENT}).`,
+          });
+        }
+      }
+    }
+
+    if (
+      config.defaultNamespace !== undefined &&
+      !IDENTIFIER_NAME_PATTERN.test(config.defaultNamespace)
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["defaultNamespace"],
+        message: `Invalid namespace name "${config.defaultNamespace}" (${IDENTIFIER_NAME_REQUIREMENT}).`,
+      });
+    }
+
+    if (config.delivery === "custom") {
+      if (!config.deliveryArtifacts) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["deliveryArtifacts"],
+          message: 'deliveryArtifacts is required when delivery is "custom".',
+        });
+      } else {
+        for (const issue of getDeliveryArtifactsStructureIssues(config.deliveryArtifacts)) {
+          ctx.addIssue({
+            code: "custom",
+            path: issue.path,
+            message: issue.message,
+          });
+        }
+      }
+    } else if (config.deliveryArtifacts !== undefined) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["deliveryArtifacts"],
+        message: 'deliveryArtifacts is only allowed when delivery is "custom".',
+      });
+    }
   });
 
+export type CodegenConfigInput = z.input<typeof codegenConfigSchema>;
 export type CodegenConfig = z.infer<typeof codegenConfigSchema>;
 
+export function resolveDeliveryOutputDir(
+  config: Pick<CodegenConfig, "typesOutput" | "deliveryOutput">
+): string {
+  return config.deliveryOutput ?? path.dirname(config.typesOutput);
+}
+
 export function formatCodegenConfigIssues(error: z.ZodError): string {
   const issueLines = error.issues.map((issue) => {
     const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";

package/src/codegen/config.test.ts

@@ -1,9 +1,10 @@
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
 import { codegenConfigKeys } from "./codegen-config-schema.js";
-import { loadConfig } from "./config.js";
+import { loadConfig, resolveDeliveryOutputDir, resolveLoadOnInit } from "./config.js";
+import { resolveImportExtension } from "./paths.js";
 
 function writeConfig(dir: string, config: Record<string, unknown>) {
   const configPath = join(dir, "i18n.codegen.json");
@@ -35,72 +36,206 @@ describe("loadConfig", () => {
     tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
     const configPath = writeConfig(tempDir, validMultiConfig);
 
-    expect(loadConfig(configPath)).toEqual(validMultiConfig);
+    expect(loadConfig(configPath)).toEqual({
+      ...validMultiConfig,
+      delivery: "canonical",
+    });
   });
 
-  it("fails on unknown top-level keys and reports allowed keys", () => {
+  it("throws on invalid config JSON", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
+    const configPath = join(tempDir, "i18n.codegen.json");
+    writeFileSync(configPath, "{ not json");
+
+    expect(() => loadConfig(configPath)).toThrow(
+      `[Codegen Error] Failed to parse config JSON (${configPath})`
+    );
+  });
+
+  it("throws on unknown top-level keys and reports allowed keys", () => {
     tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
     const configPath = writeConfig(tempDir, {
       ...validMultiConfig,
       typoKey: true,
     });
 
-    const exitSpy = vi.spyOn(process, "exit").mockImplementation((() => {
-      throw new Error("process.exit");
-    }) as typeof process.exit);
-    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => void 0);
+    const act = () => loadConfig(configPath);
+    expect(act).toThrow("Invalid i18n.codegen.json");
+    expect(act).toThrow("typoKey");
+    expect(act).toThrow(`Allowed keys: ${codegenConfigKeys.join(", ")}`);
+  });
 
-    expect(() => loadConfig(configPath)).toThrow("process.exit");
-    expect(errorSpy).toHaveBeenCalled();
+  it("throws when both dictionary and namespaces are present", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
+    const configPath = writeConfig(tempDir, {
+      ...validMultiConfig,
+      dictionary: "translations/default.json",
+    });
 
-    const message = String(errorSpy.mock.calls[0]?.[0]);
-    expect(message).toContain("Invalid i18n.codegen.json");
-    expect(message).toContain("typoKey");
-    expect(message).toContain(`Allowed keys: ${codegenConfigKeys.join(", ")}`);
+    expect(() => loadConfig(configPath)).toThrow(
+      'Specify exactly one of "dictionary" or "namespaces".'
+    );
+  });
 
-    exitSpy.mockRestore();
-    errorSpy.mockRestore();
+  it("throws when required fields are missing", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
+    const configPath = writeConfig(tempDir, {
+      namespaces: validMultiConfig.namespaces,
+    });
+
+    const act = () => loadConfig(configPath);
+    expect(act).toThrow("typesOutput");
+    expect(act).toThrow("Allowed keys:");
   });
 
-  it("fails when both dictionary and namespaces are present", () => {
+  it("throws when a namespace name is not a valid identifier", () => {
     tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
     const configPath = writeConfig(tempDir, {
       ...validMultiConfig,
-      dictionary: "translations/default.json",
+      namespaces: {
+        default: "translations/default.json",
+        "user-area": "translations/user-area.json",
+      },
+    });
+
+    expect(() => loadConfig(configPath)).toThrow(
+      'Invalid namespace name "user-area" (allowed: letters, digits, underscore; must not start with a digit).'
+    );
+  });
+
+  it("throws when defaultNamespace is not a valid identifier", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
+    const configPath = writeConfig(tempDir, {
+      ...validMultiConfig,
+      defaultNamespace: "1default",
     });
 
-    const exitSpy = vi.spyOn(process, "exit").mockImplementation((() => {
-      throw new Error("process.exit");
-    }) as typeof process.exit);
-    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => void 0);
+    expect(() => loadConfig(configPath)).toThrow(
+      'defaultNamespace: Invalid namespace name "1default"'
+    );
+  });
 
-    expect(() => loadConfig(configPath)).toThrow("process.exit");
+  it("accepts deliveryOutput for custom json artifact directory", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
+    const configPath = writeConfig(tempDir, {
+      ...validMultiConfig,
+      deliveryOutput: "public/i18n",
+    });
 
-    const message = String(errorSpy.mock.calls[0]?.[0]);
-    expect(message).toContain('Specify exactly one of "dictionary" or "namespaces".');
+    expect(loadConfig(configPath)).toMatchObject({
+      deliveryOutput: "public/i18n",
+      delivery: "canonical",
+    });
+  });
 
-    exitSpy.mockRestore();
-    errorSpy.mockRestore();
+  it("resolveDeliveryOutputDir defaults to dirname(typesOutput)", () => {
+    expect(
+      resolveDeliveryOutputDir({
+        typesOutput: "generated/i18n-types.generated.ts",
+      })
+    ).toBe("generated");
+    expect(
+      resolveDeliveryOutputDir({
+        typesOutput: "generated/i18n-types.generated.ts",
+        deliveryOutput: "public/i18n",
+      })
+    ).toBe("public/i18n");
   });
 
-  it("fails when required fields are missing", () => {
+  it("accepts custom delivery with deliveryArtifacts", () => {
     tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
     const configPath = writeConfig(tempDir, {
-      namespaces: validMultiConfig.namespaces,
+      ...validMultiConfig,
+      delivery: "custom",
+      deliveryArtifacts: {
+        eu: ["it", "fr"],
+        us: ["en-US"],
+      },
+      localeFallback: {
+        "en-US": null,
+        it: "en-US",
+        fr: null,
+      },
+    });
+
+    expect(loadConfig(configPath)).toMatchObject({
+      delivery: "custom",
+      deliveryArtifacts: {
+        eu: ["it", "fr"],
+        us: ["en-US"],
+      },
+    });
+  });
+
+  it("throws when delivery is custom without deliveryArtifacts", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
+    const configPath = writeConfig(tempDir, {
+      ...validMultiConfig,
+      delivery: "custom",
+    });
+
+    expect(() => loadConfig(configPath)).toThrow(
+      'deliveryArtifacts is required when delivery is "custom"'
+    );
+  });
+
+  it("throws when deliveryArtifacts is set for non-custom delivery", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
+    const configPath = writeConfig(tempDir, {
+      ...validMultiConfig,
+      delivery: "split-by-locale",
+      deliveryArtifacts: {
+        eu: ["it"],
+      },
+    });
+
+    expect(() => loadConfig(configPath)).toThrow(
+      'deliveryArtifacts is only allowed when delivery is "custom"'
+    );
+  });
+
+  it("throws when deliveryArtifacts has duplicate locales across areas", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
+    const configPath = writeConfig(tempDir, {
+      ...validMultiConfig,
+      delivery: "custom",
+      deliveryArtifacts: {
+        eu: ["it", "fr"],
+        us: ["fr"],
+      },
     });
 
-    const exitSpy = vi.spyOn(process, "exit").mockImplementation((() => {
-      throw new Error("process.exit");
-    }) as typeof process.exit);
-    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => void 0);
+    expect(() => loadConfig(configPath)).toThrow('Locale "fr" appears in both "eu" and "us"');
+  });
+});
+
+describe("resolveLoadOnInit", () => {
+  const entries = [
+    { namespace: "default", filePath: "translations/default.json" },
+    { namespace: "billing", filePath: "translations/billing.json" },
+  ];
+
+  it("throws when loadOnInit is used in single mode", () => {
+    const config = { ...validMultiConfig, delivery: "canonical" as const, loadOnInit: ["default"] };
 
-    expect(() => loadConfig(configPath)).toThrow("process.exit");
+    expect(() => resolveLoadOnInit(config, entries, true)).toThrow(
+      '[Codegen Error] "loadOnInit" is only supported in multi mode (namespaces config).'
+    );
+  });
+
+  it("throws when loadOnInit references an unknown namespace", () => {
+    const config = { ...validMultiConfig, delivery: "canonical" as const, loadOnInit: ["missing"] };
 
-    const message = String(errorSpy.mock.calls[0]?.[0]);
-    expect(message).toContain("typesOutput");
-    expect(message).toContain("Allowed keys:");
+    expect(() => resolveLoadOnInit(config, entries, false)).toThrow(
+      '[Codegen Error] loadOnInit: namespace "missing" is not defined in namespaces config.'
+    );
+  });
+});
 
-    exitSpy.mockRestore();
-    errorSpy.mockRestore();
+describe("resolveImportExtension", () => {
+  it("throws on unsupported import extensions", () => {
+    expect(() => resolveImportExtension({ importExtension: ".mjs" as never })).toThrow(
+      '[Codegen Error] importExtension must be "none", ".ts", or ".js", got ".mjs".'
+    );
   });
 });

package/src/codegen/config.ts

@@ -5,8 +5,10 @@ import {
   codegenConfigSchema,
   formatCodegenConfigIssues,
 } from "./codegen-config-schema.js";
-import { fail } from "./paths.js";
 
+export { resolveDeliveryOutputDir } from "./codegen-config-schema.js";
+
+/** Parses and validates `i18n.codegen.json`; first step of the codegen pipeline. */
 export function loadConfig(configPath: string): CodegenConfig {
   let raw: unknown;
 
@@ -14,17 +16,18 @@ export function loadConfig(configPath: string): CodegenConfig {
     raw = JSON.parse(fs.readFileSync(configPath, "utf8"));
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    fail(`[Codegen Error] Failed to parse config JSON (${configPath}): ${message}`);
+    throw new Error(`[Codegen Error] Failed to parse config JSON (${configPath}): ${message}`);
   }
 
   const result = codegenConfigSchema.safeParse(raw);
   if (!result.success) {
-    fail(formatCodegenConfigIssues(result.error));
+    throw new Error(formatCodegenConfigIssues(result.error));
   }
 
   return result.data;
 }
 
+/** Maps config to namespace entries (`dictionary` single vs `namespaces` multi). */
 export function resolveNamespaces(config: CodegenConfig): NamespaceEntry[] {
   const hasDictionary = Boolean(config.dictionary);
   const hasNamespaces = Boolean(config.namespaces);
@@ -50,6 +53,10 @@ export function resolveNamespaces(config: CodegenConfig): NamespaceEntry[] {
   }));
 }
 
+/**
+ * Splits namespaces into eager (`loadOnInit`) and lazy sets.
+ * Drives `InitialSchema`, `defaultDictionary`, and `namespace-loaders.generated.ts`.
+ */
 export function resolveLoadOnInit(
   config: CodegenConfig,
   entries: NamespaceEntry[],
@@ -57,7 +64,9 @@ export function resolveLoadOnInit(
 ): LoadOnInitResolution {
   if (isSingle) {
     if (config.loadOnInit) {
-      fail('[Codegen Error] "loadOnInit" is only supported in multi mode (namespaces config).');
+      throw new Error(
+        '[Codegen Error] "loadOnInit" is only supported in multi mode (namespaces config).'
+      );
     }
     const all = new Set(entries.map((entry) => entry.namespace));
     return { loadOnInitSet: all, lazyEntries: [], hasLazy: false };
@@ -70,7 +79,7 @@ export function resolveLoadOnInit(
 
   for (const namespace of loadOnInitSet) {
     if (!allNamespaces.has(namespace)) {
-      fail(
+      throw new Error(
         `[Codegen Error] loadOnInit: namespace "${namespace}" is not defined in namespaces config.`
       );
     }

package/src/codegen/constants.ts

@@ -1 +1,9 @@
 export const SUPPORTED_IMPORT_EXTENSIONS = ["none", ".ts", ".js"] as const;
+export type SupportedImportExtension = (typeof SUPPORTED_IMPORT_EXTENSIONS)[number];
+
+// Translation keys and namespace names become TypeScript identifiers and
+// template-literal type segments in the generated code, so they must be valid
+// identifiers (e.g. "app.title" would emit the broken type `"app.title:..."`).
+export const IDENTIFIER_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export const IDENTIFIER_NAME_REQUIREMENT =
+  "allowed: letters, digits, underscore; must not start with a digit";