@xndrjs/i18n 0.3.3 → 0.5.0-alpha.0

package/src/codegen/emit/instance-file.ts

@@ -1,11 +1,15 @@
 import { GENERATED_FILE_BANNER, toModuleBasename, toRelativeModuleImport } from "../paths.js";
+import type { DeliveryMode } from "../codegen-config-schema.js";
 import type { ImportExtension } from "../types.js";
 
+/**
+ * Emits the generated instance module: `createI18n` factory wrapping the ICU provider
+ * plus runtime projection helpers (`projectDictionaryLocales`, etc.).
+ */
 export interface InstanceFileOptions {
   isSingle: boolean;
   hasLazy: boolean;
   typesOutputPath: string;
-  dictionaryOutputPath: string;
   paramsTypeName: string;
   schemaTypeName: string;
   localeTypeName: string;
@@ -15,6 +19,7 @@ export interface InstanceFileOptions {
   hasLocaleType: boolean;
   namespaceNames: string[];
   importExtension: ImportExtension;
+  delivery: DeliveryMode;
 }
 
 export function formatInstanceFile(options: InstanceFileOptions): string {
@@ -22,7 +27,6 @@ export function formatInstanceFile(options: InstanceFileOptions): string {
     isSingle,
     hasLazy,
     typesOutputPath,
-    dictionaryOutputPath,
     paramsTypeName,
     schemaTypeName,
     localeTypeName,
@@ -32,71 +36,115 @@ export function formatInstanceFile(options: InstanceFileOptions): string {
     hasLocaleType,
     namespaceNames,
     importExtension,
+    delivery,
   } = options;
 
+  const emitDeliveryAreaHelpers = delivery === "custom";
   const providerClass = isSingle ? "IcuTranslationProviderSingle" : "IcuTranslationProviderMulti";
   const typesModule = toModuleBasename(typesOutputPath);
-  const dictionaryModule = toModuleBasename(dictionaryOutputPath);
   const typesImport = toRelativeModuleImport(typesModule, importExtension);
-  const dictionaryImport = toRelativeModuleImport(dictionaryModule, importExtension);
-  const initialDictionaryType = hasLazy ? "InitialSchema" : schemaTypeName;
-  const initialDictionaryImport = hasLazy
+  const dictionaryParamType = hasLazy ? "InitialSchema" : schemaTypeName;
+  const schemaTypesImport = hasLazy
     ? `import type { ${paramsTypeName}, ${schemaTypeName}, InitialSchema } from '${typesImport}';\n`
     : `import type { ${paramsTypeName}, ${schemaTypeName} } from '${typesImport}';\n`;
   const providerTypeArgs = hasLocaleFallback
     ? `${schemaTypeName}, ${paramsTypeName}, ${localeTypeName}, typeof ${localeFallbackConstName}`
     : `${schemaTypeName}, ${paramsTypeName}`;
   const providerOptions = hasLocaleFallback
-    ? `, {\n    localeFallback: ${localeFallbackConstName},\n  }`
-    : "";
+    ? `, {\n    localeFallback: ${localeFallbackConstName},\n    ...options,\n  }`
+    : `, options`;
   const typesImportLine = hasLocaleType
     ? hasLocaleFallback
       ? `import { ${localeFallbackConstName}, type ${localeTypeName} } from '${typesImport}';\n`
       : `import type { ${localeTypeName} } from '${typesImport}';\n`
     : "";
   const localesParamType = hasLocaleType ? `readonly ${localeTypeName}[]` : "readonly string[]";
-  const projectLocalesFallbackArg = hasLocaleFallback ? `, ${localeFallbackConstName}` : "";
-  const coreImports = isSingle
-    ? "projectLocales as projectLocalesCore"
-    : "projectLocales as projectLocalesCore, projectNamespacesLocales as projectNamespacesLocalesCore";
-  const projectLocalesBlock = isSingle
-    ? `\n` +
-      `export function projectLocales(\n` +
-      `  dictionary: ${schemaTypeName},\n` +
-      `  locales: ${localesParamType},\n` +
-      `): ${schemaTypeName} {\n` +
-      `  return projectLocalesCore(dictionary, locales${projectLocalesFallbackArg});\n` +
-      `}\n`
-    : formatMultiProjectLocalesBlock(
+  const fallbackArg = hasLocaleFallback ? `, ${localeFallbackConstName}` : "";
+  const coreImports = formatCoreImports(isSingle, emitDeliveryAreaHelpers);
+  const projectionBlock = isSingle
+    ? formatSingleProjectionBlock(
+        schemaTypeName,
+        localesParamType,
+        fallbackArg,
+        emitDeliveryAreaHelpers
+      )
+    : formatMultiProjectionBlock(
         schemaTypeName,
         namespaceNames,
         localesParamType,
-        projectLocalesFallbackArg
+        fallbackArg,
+        emitDeliveryAreaHelpers
       );
 
   return (
     `${GENERATED_FILE_BANNER}` +
-    `import { ${providerClass}, ${coreImports} } from '@xndrjs/i18n';\n` +
-    `import { dictionary } from '${dictionaryImport}';\n` +
-    initialDictionaryImport +
+    `import { ${providerClass}, ${coreImports}, type OnMissingTranslation } from '@xndrjs/i18n';\n` +
+    schemaTypesImport +
     typesImportLine +
     `\n` +
     `export function ${factoryName}(\n` +
-    `  initialDictionary: ${initialDictionaryType} = dictionary,\n` +
+    `  dictionary: ${dictionaryParamType},\n` +
+    `  options?: { onMissing?: OnMissingTranslation },\n` +
     `) {\n` +
-    `  return new ${providerClass}<${providerTypeArgs}>(initialDictionary${providerOptions});\n` +
+    `  return new ${providerClass}<${providerTypeArgs}>(dictionary${providerOptions});\n` +
     `}\n` +
-    projectLocalesBlock
+    projectionBlock
   );
 }
 
-function formatMultiProjectLocalesBlock(
+function formatCoreImports(isSingle: boolean, emitDeliveryAreaHelpers: boolean): string {
+  if (isSingle) {
+    const imports = ["projectNamespaceLocalesCore"];
+    if (emitDeliveryAreaHelpers) {
+      imports.push("projectNamespaceForDeliveryAreaCore");
+    }
+    return imports.join(", ");
+  }
+
+  const imports = ["projectNamespaceLocalesCore", "projectDictionaryLocalesCore"];
+  if (emitDeliveryAreaHelpers) {
+    imports.push("projectNamespaceForDeliveryAreaCore", "projectDictionaryForDeliveryAreaCore");
+  }
+  return imports.join(", ");
+}
+
+function formatSingleProjectionBlock(
+  schemaTypeName: string,
+  localesParamType: string,
+  fallbackArg: string,
+  emitDeliveryAreaHelpers: boolean
+): string {
+  let block =
+    `\n` +
+    `export function projectDictionaryLocales(\n` +
+    `  dictionary: ${schemaTypeName},\n` +
+    `  locales: ${localesParamType},\n` +
+    `): ${schemaTypeName} {\n` +
+    `  return projectNamespaceLocalesCore(dictionary, locales${fallbackArg});\n` +
+    `}\n`;
+
+  if (emitDeliveryAreaHelpers) {
+    block +=
+      `\n` +
+      `export function projectDictionaryForDeliveryArea(\n` +
+      `  dictionary: ${schemaTypeName},\n` +
+      `  areaLocales: ${localesParamType},\n` +
+      `): ${schemaTypeName} {\n` +
+      `  return projectNamespaceForDeliveryAreaCore(dictionary, areaLocales${fallbackArg});\n` +
+      `}\n`;
+  }
+
+  return block;
+}
+
+function formatMultiProjectionBlock(
   schemaTypeName: string,
   namespaceNames: string[],
   localesParamType: string,
-  projectLocalesFallbackArg: string
+  fallbackArg: string,
+  emitDeliveryAreaHelpers: boolean
 ): string {
-  const overloads = namespaceNames
+  const namespaceLocaleOverloads = namespaceNames
     .map(
       (namespace) =>
         `export function projectNamespaceLocales(\n` +
@@ -106,22 +154,55 @@ function formatMultiProjectLocalesBlock(
     )
     .join("\n");
 
-  return (
+  const namespaceDeliveryOverloads = emitDeliveryAreaHelpers
+    ? namespaceNames
+        .map(
+          (namespace) =>
+            `export function projectNamespaceForDeliveryArea(\n` +
+            `  dictionary: ${schemaTypeName}["${namespace}"],\n` +
+            `  areaLocales: ${localesParamType},\n` +
+            `): ${schemaTypeName}["${namespace}"];`
+        )
+        .join("\n")
+    : "";
+
+  let block =
     `\n` +
-    `export function projectLocales(\n` +
+    `export function projectDictionaryLocales(\n` +
     `  dictionary: ${schemaTypeName},\n` +
     `  locales: ${localesParamType},\n` +
     `): ${schemaTypeName} {\n` +
-    `  return projectNamespacesLocalesCore(dictionary, locales${projectLocalesFallbackArg});\n` +
+    `  return projectDictionaryLocalesCore(dictionary, locales${fallbackArg});\n` +
     `}\n` +
     `\n` +
-    overloads +
+    namespaceLocaleOverloads +
     `\n` +
     `export function projectNamespaceLocales(\n` +
     `  dictionary: ${schemaTypeName}[keyof ${schemaTypeName}],\n` +
     `  locales: ${localesParamType},\n` +
     `): ${schemaTypeName}[keyof ${schemaTypeName}] {\n` +
-    `  return projectLocalesCore(dictionary, locales${projectLocalesFallbackArg});\n` +
-    `}\n`
-  );
+    `  return projectNamespaceLocalesCore(dictionary, locales${fallbackArg});\n` +
+    `}\n`;
+
+  if (emitDeliveryAreaHelpers) {
+    block +=
+      `\n` +
+      `export function projectDictionaryForDeliveryArea(\n` +
+      `  dictionary: ${schemaTypeName},\n` +
+      `  areaLocales: ${localesParamType},\n` +
+      `): ${schemaTypeName} {\n` +
+      `  return projectDictionaryForDeliveryAreaCore(dictionary, areaLocales${fallbackArg});\n` +
+      `}\n` +
+      `\n` +
+      namespaceDeliveryOverloads +
+      `\n` +
+      `export function projectNamespaceForDeliveryArea(\n` +
+      `  dictionary: ${schemaTypeName}[keyof ${schemaTypeName}],\n` +
+      `  areaLocales: ${localesParamType},\n` +
+      `): ${schemaTypeName}[keyof ${schemaTypeName}] {\n` +
+      `  return projectNamespaceForDeliveryAreaCore(dictionary, areaLocales${fallbackArg});\n` +
+      `}\n`;
+  }
+
+  return block;
 }

package/src/codegen/emit/namespace-loaders-file.test.ts

@@ -0,0 +1,176 @@
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { formatNamespaceLoadersFile } from "./namespace-loaders-file.js";
+
+const projectRoot = "/project";
+const loadersOutputPath = path.join(projectRoot, "src/i18n/namespace-loaders.generated.ts");
+
+describe("formatNamespaceLoadersFile", () => {
+  it("emits flat loaders in canonical mode", () => {
+    const output = formatNamespaceLoadersFile({
+      loadersOutputPath,
+      lazyEntries: [
+        {
+          namespace: "billing",
+          filePath: "src/i18n/translations/billing.json",
+          absolutePath: path.join(projectRoot, "src/i18n/translations/billing.json"),
+        },
+      ],
+      schemaTypeName: "AppSchema",
+      localeTypeName: "AppLocale",
+      typesModule: "i18n-types.generated",
+      importExtension: "none",
+      projectRoot,
+      delivery: "canonical",
+    });
+
+    expect(output).toContain("[K in LazyNamespace]: () => Promise<AppSchema[K]>");
+    expect(output).toContain(
+      "billing: () => import('./translations/billing.json').then((m) => m.default),"
+    );
+    expect(output).not.toContain("AppLocale");
+  });
+
+  it("emits ns(locale) loaders in split mode", () => {
+    const output = formatNamespaceLoadersFile({
+      loadersOutputPath,
+      lazyEntries: [
+        {
+          namespace: "billing",
+          filePath: "src/i18n/translations/billing.json",
+          absolutePath: path.join(projectRoot, "src/i18n/translations/billing.json"),
+        },
+        {
+          namespace: "user",
+          filePath: "src/i18n/translations/user.json",
+          absolutePath: path.join(projectRoot, "src/i18n/translations/user.json"),
+        },
+      ],
+      schemaTypeName: "AppSchema",
+      localeTypeName: "AppLocale",
+      typesModule: "i18n-types.generated",
+      importExtension: "none",
+      projectRoot,
+      delivery: "split-by-locale",
+      requestLocales: ["en", "it", "de-CH"],
+      splitPathsByNamespace: {
+        billing: {
+          en: "src/i18n/generated/translations/billing.en.json",
+          it: "src/i18n/generated/translations/billing.it.json",
+          "de-CH": "src/i18n/generated/translations/billing.de-CH.json",
+        },
+        user: {
+          en: "src/i18n/generated/translations/user.en.json",
+          it: "src/i18n/generated/translations/user.it.json",
+          "de-CH": "src/i18n/generated/translations/user.de-CH.json",
+        },
+      },
+    });
+
+    expect(output).toContain("[K in LazyNamespace]: (locale: AppLocale) => Promise<AppSchema[K]>;");
+    expect(output).toContain("billing: (locale) => {");
+    expect(output).toContain('case "en":');
+    expect(output).toContain('case "it":');
+    expect(output).toContain('case "de-CH":');
+    expect(output).toContain(
+      "return import('./generated/translations/billing.en.json').then((m) => m.default);"
+    );
+    expect(output).toContain("user: (locale) => {");
+    expect(output).not.toContain("billing: {");
+    expect(output).not.toContain("import('./translations/billing.json')");
+  });
+
+  it("throws when a split path is missing", () => {
+    expect(() =>
+      formatNamespaceLoadersFile({
+        loadersOutputPath,
+        lazyEntries: [
+          {
+            namespace: "billing",
+            filePath: "src/i18n/translations/billing.json",
+            absolutePath: path.join(projectRoot, "src/i18n/translations/billing.json"),
+          },
+        ],
+        schemaTypeName: "AppSchema",
+        localeTypeName: "AppLocale",
+        typesModule: "i18n-types.generated",
+        importExtension: "none",
+        projectRoot,
+        delivery: "split-by-locale",
+        requestLocales: ["en", "it"],
+        splitPathsByNamespace: {
+          billing: {
+            en: "src/i18n/generated/translations/billing.en.json",
+          },
+        },
+      })
+    ).toThrow('[Codegen Error] Missing split path for namespace "billing", locale "it".');
+  });
+
+  it("emits ns(area) loaders in custom mode", () => {
+    const output = formatNamespaceLoadersFile({
+      loadersOutputPath,
+      lazyEntries: [
+        {
+          namespace: "billing",
+          filePath: "src/i18n/translations/billing.json",
+          absolutePath: path.join(projectRoot, "src/i18n/translations/billing.json"),
+        },
+      ],
+      schemaTypeName: "AppSchema",
+      localeTypeName: "AppLocale",
+      typesModule: "i18n-types.generated",
+      importExtension: "none",
+      projectRoot,
+      delivery: "custom",
+      deliveryAreaTypeName: "AppDeliveryArea",
+      deliveryAreaNames: ["eu", "us"],
+      splitPathsByNamespace: {
+        billing: {
+          eu: "src/i18n/generated/translations/billing.eu.json",
+          us: "src/i18n/generated/translations/billing.us.json",
+        },
+      },
+    });
+
+    expect(output).toContain(
+      "[K in LazyNamespace]: (area: AppDeliveryArea) => Promise<AppSchema[K]>;"
+    );
+    expect(output).toContain("billing: (area) => {");
+    expect(output).toContain('case "eu":');
+    expect(output).toContain('case "us":');
+    expect(output).toContain(
+      "return import('./generated/translations/billing.eu.json').then((m) => m.default);"
+    );
+    expect(output).not.toContain("AppLocale");
+    expect(output).not.toContain("import('./translations/billing.json')");
+  });
+
+  it("throws when a custom delivery split path is missing", () => {
+    expect(() =>
+      formatNamespaceLoadersFile({
+        loadersOutputPath,
+        lazyEntries: [
+          {
+            namespace: "billing",
+            filePath: "src/i18n/translations/billing.json",
+            absolutePath: path.join(projectRoot, "src/i18n/translations/billing.json"),
+          },
+        ],
+        schemaTypeName: "AppSchema",
+        localeTypeName: "AppLocale",
+        typesModule: "i18n-types.generated",
+        importExtension: "none",
+        projectRoot,
+        delivery: "custom",
+        deliveryAreaTypeName: "AppDeliveryArea",
+        deliveryAreaNames: ["eu", "us"],
+        splitPathsByNamespace: {
+          billing: {
+            eu: "src/i18n/generated/translations/billing.eu.json",
+          },
+        },
+      })
+    ).toThrow('[Codegen Error] Missing split path for namespace "billing", area "us".');
+  });
+});

package/src/codegen/emit/namespace-loaders-file.ts

@@ -1,19 +1,96 @@
+import path from "node:path";
+import type { DeliveryMode } from "../codegen-config-schema.js";
 import { GENERATED_FILE_BANNER, toImportPath, toRelativeModuleImport } from "../paths.js";
 import type { ImportExtension, NamespaceEntry } from "../types.js";
 
-export function formatNamespaceLoadersFile(
-  loadersOutputPath: string,
-  lazyEntries: (NamespaceEntry & { absolutePath: string })[],
-  schemaTypeName: string,
-  typesModule: string,
-  dictionarySchemaModule: string,
-  instanceModule: string,
-  factoryName: string,
-  importExtension: ImportExtension
+/**
+ * Emits the generated `namespace-loaders.generated.ts` module: dynamic `import()`
+ * functions for lazy-loaded namespaces, shaped by delivery mode.
+ */
+export interface NamespaceLoadersFileOptions {
+  loadersOutputPath: string;
+  lazyEntries: (NamespaceEntry & { absolutePath: string })[];
+  schemaTypeName: string;
+  localeTypeName: string;
+  typesModule: string;
+  importExtension: ImportExtension;
+  projectRoot: string;
+  delivery?: DeliveryMode;
+  splitPathsByNamespace?: Record<string, Record<string, string>>;
+  requestLocales?: readonly string[];
+  deliveryAreaTypeName?: string;
+  deliveryAreaNames?: readonly string[];
+}
+
+interface PartitionedNamespaceLoadersParams {
+  partitionKeys: readonly string[];
+  paramName: string;
+  paramTypeName: string;
+}
+
+/**
+ * Emits lazy loaders for split-by-locale and custom delivery.
+ * Each namespace gets a function that dynamic-imports the JSON for the given
+ * partition key (locale or area) via a switch.
+ */
+function formatPartitionedNamespaceLoadersFile(
+  options: NamespaceLoadersFileOptions,
+  { partitionKeys, paramName, paramTypeName }: PartitionedNamespaceLoadersParams
 ): string {
-  const dictionarySchemaImport = toRelativeModuleImport(dictionarySchemaModule, importExtension);
+  const {
+    loadersOutputPath,
+    lazyEntries,
+    schemaTypeName,
+    typesModule,
+    importExtension,
+    projectRoot,
+    splitPathsByNamespace = {},
+  } = options;
+
+  const typesImport = toRelativeModuleImport(typesModule, importExtension);
+  const loaderEntries = lazyEntries
+    .map((entry) => {
+      const switchCases = partitionKeys
+        .map((partitionKey) => {
+          const splitRelativePath = splitPathsByNamespace[entry.namespace]?.[partitionKey];
+          if (!splitRelativePath) {
+            throw new Error(
+              `[Codegen Error] Missing split path for namespace "${entry.namespace}", ${paramName} "${partitionKey}".`
+            );
+          }
+          const importPath = toImportPath(
+            loadersOutputPath,
+            path.resolve(projectRoot, splitRelativePath)
+          );
+          return (
+            `      case ${JSON.stringify(partitionKey)}:\n` +
+            `        return import('${importPath}.json').then((m) => m.default);`
+          );
+        })
+        .join("\n");
+
+      return (
+        `  ${entry.namespace}: (${paramName}) => {\n` +
+        `    switch (${paramName}) {\n${switchCases}\n` +
+        `    }\n` +
+        `  },`
+      );
+    })
+    .join("\n");
+
+  return (
+    `${GENERATED_FILE_BANNER}` +
+    `import type { ${schemaTypeName}, LazyNamespace, ${paramTypeName} } from '${typesImport}';\n\n` +
+    `export const namespaceLoaders: {\n` +
+    `  [K in LazyNamespace]: (${paramName}: ${paramTypeName}) => Promise<${schemaTypeName}[K]>;\n` +
+    `} = {\n${loaderEntries}\n};\n`
+  );
+}
+
+/** Emits lazy loaders for canonical delivery: one dynamic import per namespace. */
+function formatCanonicalNamespaceLoadersFile(options: NamespaceLoadersFileOptions): string {
+  const { loadersOutputPath, lazyEntries, schemaTypeName, typesModule, importExtension } = options;
   const typesImport = toRelativeModuleImport(typesModule, importExtension);
-  const instanceImport = toRelativeModuleImport(instanceModule, importExtension);
   const loaderEntries = lazyEntries
     .map((entry) => {
       const importPath = toImportPath(loadersOutputPath, entry.absolutePath);
@@ -23,26 +100,35 @@ export function formatNamespaceLoadersFile(
 
   return (
     `${GENERATED_FILE_BANNER}` +
-    `import { ensureNamespacesLoadedImpl } from '@xndrjs/i18n';\n` +
-    `import { validateExternalNamespace } from '${dictionarySchemaImport}';\n` +
-    `import type { ${schemaTypeName}, LazyNamespace } from '${typesImport}';\n` +
-    `import type { ${factoryName} } from '${instanceImport}';\n\n` +
-    `export const namespaceLoaders: Record<\n` +
-    `  LazyNamespace,\n` +
-    `  () => Promise<${schemaTypeName}[LazyNamespace]>\n` +
-    `> = {\n${loaderEntries}\n};\n\n` +
-    `export async function ensureNamespacesLoaded(\n` +
-    `  i18n: ReturnType<typeof ${factoryName}>,\n` +
-    `  namespaces: LazyNamespace[],\n` +
-    `): Promise<void> {\n` +
-    `  return ensureNamespacesLoadedImpl<${schemaTypeName}, LazyNamespace>(\n` +
-    `    {\n` +
-    `      provider: i18n,\n` +
-    `      resolveLoader: (namespace) => namespaceLoaders[namespace],\n` +
-    `      validate: (namespace, raw) => validateExternalNamespace(namespace, raw),\n` +
-    `    },\n` +
-    `    namespaces,\n` +
-    `  );\n` +
-    `}\n`
+    `import type { ${schemaTypeName}, LazyNamespace } from '${typesImport}';\n\n` +
+    `export const namespaceLoaders: {\n` +
+    `  [K in LazyNamespace]: () => Promise<${schemaTypeName}[K]>;\n` +
+    `} = {\n${loaderEntries}\n};\n`
   );
 }
+
+/**
+ * Builds `namespace-loaders.generated.ts` for the configured delivery mode:
+ * canonical, split-by-locale, or custom areas.
+ */
+export function formatNamespaceLoadersFile(options: NamespaceLoadersFileOptions): string {
+  const delivery = options.delivery ?? "canonical";
+  if (delivery === "split-by-locale") {
+    return formatPartitionedNamespaceLoadersFile(options, {
+      partitionKeys: options.requestLocales ?? [],
+      paramName: "locale",
+      paramTypeName: options.localeTypeName,
+    });
+  }
+  if (delivery === "custom") {
+    if (!options.deliveryAreaTypeName) {
+      throw new Error("[Codegen Error] deliveryAreaTypeName is required for custom delivery.");
+    }
+    return formatPartitionedNamespaceLoadersFile(options, {
+      partitionKeys: options.deliveryAreaNames ?? [],
+      paramName: "area",
+      paramTypeName: options.deliveryAreaTypeName,
+    });
+  }
+  return formatCanonicalNamespaceLoadersFile(options);
+}