@xndrjs/i18n 0.5.0 → 0.6.0-alpha.1

package/src/codegen/emit/dictionary-file.test.ts

@@ -30,6 +30,38 @@ describe("formatDictionaryFile", () => {
     expect(output).not.toContain("defaultDictionaryFor");
   });
 
+  it("emits an empty module when all namespaces are lazy in split mode (multi)", () => {
+    const output = formatDictionaryFile({
+      isSingle: false,
+      hasLazy: true,
+      entries: [
+        { namespace: "default", filePath: "src/i18n/translations/default.json" },
+        { namespace: "billing", filePath: "src/i18n/translations/billing.json" },
+      ],
+      eagerEntries: [],
+      projectRoot,
+      dictionaryOutputPath,
+      typesOutputPath,
+      schemaTypeName: "AppSchema",
+      localeTypeName: "AppLocale",
+      importExtension: "none",
+      delivery: "split-by-locale",
+      requestLocales: ["en", "it"],
+      splitPathsByNamespace: {
+        default: {
+          en: "src/i18n/generated/translations/default.en.json",
+          it: "src/i18n/generated/translations/default.it.json",
+        },
+        billing: {
+          en: "src/i18n/generated/translations/billing.en.json",
+          it: "src/i18n/generated/translations/billing.it.json",
+        },
+      },
+    });
+
+    expect(output).toBeNull();
+  });
+
   it("emits defaultDictionaryFor with per-locale imports in split mode (multi)", () => {
     const output = formatDictionaryFile({
       isSingle: false,

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

@@ -67,7 +67,7 @@ function toPartitionSuffix(paramName: string): string {
 function formatPartitionedDictionaryFile(
   options: DictionaryFileOptions,
   { partitionKeys, paramName, paramTypeName }: PartitionedDictionaryParams
-): string {
+): string | null {
   const {
     isSingle,
     hasLazy,
@@ -86,6 +86,10 @@ function formatPartitionedDictionaryFile(
   const dictionaryTypeName = hasLazy ? "InitialSchema" : schemaTypeName;
   const schemaTypeImport = hasLazy ? `, ${schemaTypeName}` : "";
 
+  if (eagerEntries.length === 0) {
+    return null;
+  }
+
   const imports = eagerEntries
     .flatMap((entry) =>
       partitionKeys.map((partitionKey) => {
@@ -164,7 +168,7 @@ function formatPartitionedDictionaryFile(
  * Builds `dictionary.generated.ts` for the configured delivery mode:
  * canonical (single bundled JSON per namespace), split-by-locale, or custom areas.
  */
-export function formatDictionaryFile(options: DictionaryFileOptions): string {
+export function formatDictionaryFile(options: DictionaryFileOptions): string | null {
   const delivery = options.delivery ?? "canonical";
   if (delivery === "split-by-locale") {
     return formatPartitionedDictionaryFile(options, {

package/src/codegen/emit/dictionary-schema-file.ts

@@ -81,14 +81,14 @@ export function formatDictionarySchemaFile(
   const typesImport = toRelativeModuleImport(typesModule, importExtension);
   const namespaceImport = isSingle
     ? ""
-    : `  validateExternalNamespace as validateExternalNamespaceImpl,\n`;
+    : `  validateExternalNamespace as validateExternalNamespaceCore,\n`;
   const namespaceValidator = isSingle
     ? ""
     : `export function validateExternalNamespace<NS extends keyof ${schemaTypeName}>(\n` +
       `  namespace: NS,\n` +
       `  input: unknown,\n` +
       `) {\n` +
-      `  return validateExternalNamespaceImpl<${schemaTypeName}[NS]>(\n` +
+      `  return validateExternalNamespaceCore<${schemaTypeName}[NS]>(\n` +
       `    namespace as string,\n` +
       `    input,\n` +
       `    DICTIONARY_SPEC,\n` +

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

@@ -17,7 +17,10 @@ describe("formatNamespaceLoadersFile", () => {
         },
       ],
       schemaTypeName: "AppSchema",
+      paramsTypeName: "AppParams",
       localeTypeName: "AppLocale",
+      localeFallbackConstName: "LOCALE_FALLBACK",
+      hasLocaleFallback: false,
       typesModule: "i18n-types.generated",
       importExtension: "none",
       projectRoot,
@@ -29,6 +32,7 @@ describe("formatNamespaceLoadersFile", () => {
       "billing: () => import('./translations/billing.json').then((m) => m.default),"
     );
     expect(output).not.toContain("AppLocale");
+    expect(output).not.toContain("ensureNamespacesLoadedForLocale");
   });
 
   it("emits ns(locale) loaders in split mode", () => {
@@ -40,6 +44,11 @@ describe("formatNamespaceLoadersFile", () => {
           filePath: "src/i18n/translations/billing.json",
           absolutePath: path.join(projectRoot, "src/i18n/translations/billing.json"),
         },
+        {
+          namespace: "default",
+          filePath: "src/i18n/translations/default.json",
+          absolutePath: path.join(projectRoot, "src/i18n/translations/default.json"),
+        },
         {
           namespace: "user",
           filePath: "src/i18n/translations/user.json",
@@ -47,10 +56,14 @@ describe("formatNamespaceLoadersFile", () => {
         },
       ],
       schemaTypeName: "AppSchema",
+      paramsTypeName: "AppParams",
       localeTypeName: "AppLocale",
+      localeFallbackConstName: "LOCALE_FALLBACK",
+      hasLocaleFallback: true,
       typesModule: "i18n-types.generated",
       importExtension: "none",
       projectRoot,
+      isSingle: false,
       delivery: "split-by-locale",
       requestLocales: ["en", "it", "de-CH"],
       splitPathsByNamespace: {
@@ -59,6 +72,11 @@ describe("formatNamespaceLoadersFile", () => {
           it: "src/i18n/generated/translations/billing.it.json",
           "de-CH": "src/i18n/generated/translations/billing.de-CH.json",
         },
+        default: {
+          en: "src/i18n/generated/translations/default.en.json",
+          it: "src/i18n/generated/translations/default.it.json",
+          "de-CH": "src/i18n/generated/translations/default.de-CH.json",
+        },
         user: {
           en: "src/i18n/generated/translations/user.en.json",
           it: "src/i18n/generated/translations/user.it.json",
@@ -72,12 +90,21 @@ describe("formatNamespaceLoadersFile", () => {
     expect(output).toContain('case "en":');
     expect(output).toContain('case "it":');
     expect(output).toContain('case "de-CH":');
+    expect(output).toContain(
+      'throw new Error(`[i18n] No translation artifact for namespace "billing" and locale "${String(locale)}".`);'
+    );
     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')");
+    expect(output).toContain("export async function ensureNamespacesLoadedForLocale(");
+    expect(output).toContain("i18n: I18nMultiInstance,");
+    expect(output).toContain(
+      'namespaces: readonly LazyNamespace[] = ["billing", "default", "user"] as const,'
+    );
+    expect(output.match(/from '\.\/i18n-types\.generated'/g)?.length).toBe(1);
   });
 
   it("throws when a split path is missing", () => {
@@ -92,7 +119,10 @@ describe("formatNamespaceLoadersFile", () => {
           },
         ],
         schemaTypeName: "AppSchema",
+        paramsTypeName: "AppParams",
         localeTypeName: "AppLocale",
+        localeFallbackConstName: "LOCALE_FALLBACK",
+        hasLocaleFallback: false,
         typesModule: "i18n-types.generated",
         importExtension: "none",
         projectRoot,
@@ -116,12 +146,21 @@ describe("formatNamespaceLoadersFile", () => {
           filePath: "src/i18n/translations/billing.json",
           absolutePath: path.join(projectRoot, "src/i18n/translations/billing.json"),
         },
+        {
+          namespace: "default",
+          filePath: "src/i18n/translations/default.json",
+          absolutePath: path.join(projectRoot, "src/i18n/translations/default.json"),
+        },
       ],
       schemaTypeName: "AppSchema",
+      paramsTypeName: "AppParams",
       localeTypeName: "AppLocale",
+      localeFallbackConstName: "LOCALE_FALLBACK",
+      hasLocaleFallback: true,
       typesModule: "i18n-types.generated",
       importExtension: "none",
       projectRoot,
+      isSingle: false,
       delivery: "custom",
       deliveryAreaTypeName: "AppDeliveryArea",
       deliveryAreaNames: ["eu", "us"],
@@ -130,6 +169,10 @@ describe("formatNamespaceLoadersFile", () => {
           eu: "src/i18n/generated/translations/billing.eu.json",
           us: "src/i18n/generated/translations/billing.us.json",
         },
+        default: {
+          eu: "src/i18n/generated/translations/default.eu.json",
+          us: "src/i18n/generated/translations/default.us.json",
+        },
       },
     });
 
@@ -139,11 +182,17 @@ describe("formatNamespaceLoadersFile", () => {
     expect(output).toContain("billing: (area) => {");
     expect(output).toContain('case "eu":');
     expect(output).toContain('case "us":');
+    expect(output).toContain(
+      'throw new Error(`[i18n] No translation artifact for namespace "billing" and area "${String(area)}".`);'
+    );
     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')");
+    expect(output).toContain("export async function ensureNamespacesLoadedForArea(");
+    expect(output).toContain(
+      'namespaces: readonly LazyNamespace[] = ["billing", "default"] as const,'
+    );
   });
 
   it("throws when a custom delivery split path is missing", () => {
@@ -158,7 +207,10 @@ describe("formatNamespaceLoadersFile", () => {
           },
         ],
         schemaTypeName: "AppSchema",
+        paramsTypeName: "AppParams",
         localeTypeName: "AppLocale",
+        localeFallbackConstName: "LOCALE_FALLBACK",
+        hasLocaleFallback: false,
         typesModule: "i18n-types.generated",
         importExtension: "none",
         projectRoot,

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

@@ -11,10 +11,14 @@ export interface NamespaceLoadersFileOptions {
   loadersOutputPath: string;
   lazyEntries: (NamespaceEntry & { absolutePath: string })[];
   schemaTypeName: string;
+  paramsTypeName: string;
   localeTypeName: string;
+  localeFallbackConstName: string;
+  hasLocaleFallback: boolean;
   typesModule: string;
   importExtension: ImportExtension;
   projectRoot: string;
+  isSingle?: boolean;
   delivery?: DeliveryMode;
   splitPathsByNamespace?: Record<string, Record<string, string>>;
   requestLocales?: readonly string[];
@@ -26,28 +30,108 @@ interface PartitionedNamespaceLoadersParams {
   partitionKeys: readonly string[];
   paramName: string;
   paramTypeName: string;
+  loadNamespacesFunctionName: string;
+}
+
+function formatI18nMultiInstanceType(options: NamespaceLoadersFileOptions): string {
+  const {
+    schemaTypeName,
+    paramsTypeName,
+    localeTypeName,
+    localeFallbackConstName,
+    hasLocaleFallback,
+  } = options;
+
+  const typeArgs = hasLocaleFallback
+    ? `${schemaTypeName}, ${paramsTypeName}, ${localeTypeName}, typeof ${localeFallbackConstName}`
+    : `${schemaTypeName}, ${paramsTypeName}`;
+
+  return `IcuTranslationProviderMulti<${typeArgs}>`;
+}
+
+function formatDefaultNamespacesLiteral(lazyEntries: NamespaceEntry[]): string {
+  return [...lazyEntries]
+    .map((entry) => entry.namespace)
+    .sort()
+    .map((namespace) => JSON.stringify(namespace))
+    .join(", ");
+}
+
+function formatLoadNamespacesHelper(
+  options: NamespaceLoadersFileOptions,
+  { paramName, paramTypeName, loadNamespacesFunctionName }: PartitionedNamespaceLoadersParams
+): string {
+  const { lazyEntries } = options;
+  const defaultNamespaces = formatDefaultNamespacesLiteral(lazyEntries);
+
+  return (
+    `\ntype I18nMultiInstance = ${formatI18nMultiInstanceType(options)};\n\n` +
+    `export async function ${loadNamespacesFunctionName}(\n` +
+    `  i18n: I18nMultiInstance,\n` +
+    `  ${paramName}: ${paramTypeName},\n` +
+    `  namespaces: readonly LazyNamespace[] = [${defaultNamespaces}] as const,\n` +
+    `): Promise<void> {\n` +
+    `  await Promise.all(\n` +
+    `    namespaces.map(async (namespace) => {\n` +
+    `      i18n.setNamespace(namespace, await namespaceLoaders[namespace](${paramName}));\n` +
+    `    }),\n` +
+    `  );\n` +
+    `}\n`
+  );
+}
+
+function formatPartitionedTypesImport(
+  options: NamespaceLoadersFileOptions,
+  paramTypeName: string
+): string {
+  const {
+    schemaTypeName,
+    paramsTypeName,
+    localeTypeName,
+    localeFallbackConstName,
+    hasLocaleFallback,
+    typesModule,
+    importExtension,
+    isSingle,
+  } = options;
+
+  if (isSingle) {
+    return `import type { ${schemaTypeName}, LazyNamespace, ${paramTypeName} } from '${toRelativeModuleImport(typesModule, importExtension)}';\n\n`;
+  }
+
+  const fallbackImport = hasLocaleFallback ? `${localeFallbackConstName}, ` : "";
+  const paramTypeImport = paramTypeName === localeTypeName ? "" : `, type ${paramTypeName}`;
+  return (
+    `import { IcuTranslationProviderMulti } from '@xndrjs/i18n';\n` +
+    `import { ${fallbackImport}type ${localeTypeName}, type ${paramsTypeName}, type ${schemaTypeName}, type LazyNamespace${paramTypeImport} } from '${toRelativeModuleImport(typesModule, importExtension)}';\n\n`
+  );
+}
+
+function formatSwitchDefaultCase(namespace: string, paramName: string): string {
+  return (
+    `      default:\n` +
+    `        throw new Error(\`[i18n] No translation artifact for namespace ${JSON.stringify(namespace)} and ${paramName} "\${String(${paramName})}".\`);\n`
+  );
 }
 
 /**
- * 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
+  params: PartitionedNamespaceLoadersParams
 ): string {
+  const { partitionKeys, paramName, paramTypeName } = params;
   const {
     loadersOutputPath,
     lazyEntries,
     schemaTypeName,
-    typesModule,
-    importExtension,
     projectRoot,
     splitPathsByNamespace = {},
   } = options;
 
-  const typesImport = toRelativeModuleImport(typesModule, importExtension);
+  const typesImport = formatPartitionedTypesImport(options, paramTypeName);
   const loaderEntries = lazyEntries
     .map((entry) => {
       const switchCases = partitionKeys
@@ -72,6 +156,7 @@ function formatPartitionedNamespaceLoadersFile(
       return (
         `  ${entry.namespace}: (${paramName}) => {\n` +
         `    switch (${paramName}) {\n${switchCases}\n` +
+        `${formatSwitchDefaultCase(entry.namespace, paramName)}` +
         `    }\n` +
         `  },`
       );
@@ -80,10 +165,11 @@ function formatPartitionedNamespaceLoadersFile(
 
   return (
     `${GENERATED_FILE_BANNER}` +
-    `import type { ${schemaTypeName}, LazyNamespace, ${paramTypeName} } from '${typesImport}';\n\n` +
+    typesImport +
     `export const namespaceLoaders: {\n` +
     `  [K in LazyNamespace]: (${paramName}: ${paramTypeName}) => Promise<${schemaTypeName}[K]>;\n` +
-    `} = {\n${loaderEntries}\n};\n`
+    `} = {\n${loaderEntries}\n};\n` +
+    (options.isSingle ? "" : formatLoadNamespacesHelper(options, params))
   );
 }
 
@@ -118,6 +204,7 @@ export function formatNamespaceLoadersFile(options: NamespaceLoadersFileOptions)
       partitionKeys: options.requestLocales ?? [],
       paramName: "locale",
       paramTypeName: options.localeTypeName,
+      loadNamespacesFunctionName: "ensureNamespacesLoadedForLocale",
     });
   }
   if (delivery === "custom") {
@@ -128,6 +215,7 @@ export function formatNamespaceLoadersFile(options: NamespaceLoadersFileOptions)
       partitionKeys: options.deliveryAreaNames ?? [],
       paramName: "area",
       paramTypeName: options.deliveryAreaTypeName,
+      loadNamespacesFunctionName: "ensureNamespacesLoadedForArea",
     });
   }
   return formatCanonicalNamespaceLoadersFile(options);

package/src/codegen/emit/types-file.test.ts

@@ -105,6 +105,11 @@ describe("formatTypesFile", () => {
 
     expect(output).toContain("export type AppLocale = 'en-US' | 'fr' | 'it';");
     expect(output).toContain("export type AppDeliveryArea = 'eu' | 'us';");
+    expect(output).toContain("export const DELIVERY_ARTIFACTS = {");
+    expect(output).toContain('"eu": ["fr", "it"] as const');
+    expect(output).toContain('"us": ["en-US"] as const');
+    expect(output).toContain("} as const satisfies Record<AppDeliveryArea, readonly AppLocale[]>;");
+    expect(output).toContain("export type AppDeliveryArtifacts = typeof DELIVERY_ARTIFACTS;");
     expect(output).toContain("export const LOCALE_DELIVERY_AREA = {");
     expect(output).toContain('"it": "eu"');
     expect(output).toContain('"en-US": "us"');

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

@@ -1,4 +1,8 @@
-import { formatLocaleDeliveryAreaBlock, type DeliveryArtifactsMap } from "../delivery-artifacts.js";
+import {
+  formatDeliveryArtifactsBlock,
+  formatLocaleDeliveryAreaBlock,
+  type DeliveryArtifactsMap,
+} from "../delivery-artifacts.js";
 import { formatLocaleFallbackBlock } from "../locale-fallback.js";
 import { GENERATED_FILE_BANNER } from "../paths.js";
 import type { NamespaceEntry } from "../types.js";
@@ -12,10 +16,13 @@ export function formatLazyTypesBlock(
   lazyEntries: NamespaceEntry[],
   schemaTypeName: string
 ): string {
-  const loadOnInitUnion = [...loadOnInitSet]
-    .sort()
-    .map((namespace) => `'${namespace}'`)
-    .join(" | ");
+  const loadOnInitUnion =
+    loadOnInitSet.size > 0
+      ? [...loadOnInitSet]
+          .sort()
+          .map((namespace) => `'${namespace}'`)
+          .join(" | ")
+      : "never";
   const lazyUnion = lazyEntries.map((entry) => `'${entry.namespace}'`).join(" | ");
 
   return (
@@ -87,7 +94,13 @@ export function formatTypesFile(options: TypesFileOptions): string {
     deliveryAreaTypeName && deliveryAreaUnion
       ? `export type ${deliveryAreaTypeName} = ${deliveryAreaUnion};\n\n` +
         (deliveryArtifacts
-          ? formatLocaleDeliveryAreaBlock(
+          ? formatDeliveryArtifactsBlock(
+              deliveryArtifacts,
+              "DELIVERY_ARTIFACTS",
+              localeTypeName,
+              deliveryAreaTypeName
+            ) +
+            formatLocaleDeliveryAreaBlock(
               deliveryArtifacts,
               localeDeliveryAreaConstName,
               localeTypeName,