@xndrjs/i18n 0.3.3 → 0.5.0-alpha.0

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

@@ -0,0 +1,114 @@
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { formatTypesFile } from "./types-file.js";
+
+const projectRoot = "/project";
+const typesOutputPath = path.join(projectRoot, "src/i18n/generated/i18n-types.generated.ts");
+
+describe("formatTypesFile", () => {
+  it("emits explicit Partial schema types for multi-namespace", () => {
+    const output = formatTypesFile({
+      isSingle: false,
+      entries: [
+        { namespace: "default", filePath: "src/i18n/translations/default.json" },
+        { namespace: "billing", filePath: "src/i18n/translations/billing.yaml" },
+      ],
+      projectRoot,
+      typesOutputPath,
+      paramsTypeName: "AppParams",
+      schemaTypeName: "AppSchema",
+      localeTypeName: "AppLocale",
+      localeFallbackConstName: "LOCALE_FALLBACK",
+      localeFallbackTypeName: "AppLocaleFallback",
+      paramsByNamespace: {
+        default: {
+          login_button: "never",
+          welcome: "{ name: string }",
+        },
+        billing: {
+          invoice_summary: "{ count: number }",
+        },
+      },
+      requestLocaleUnion: "'en' | 'it'",
+      hasLazy: true,
+      loadOnInitSet: new Set(["default"]),
+      lazyEntries: [{ namespace: "billing", filePath: "src/i18n/translations/billing.yaml" }],
+    });
+
+    expect(output).toContain("login_button: Partial<Record<AppLocale, string>>;");
+    expect(output).toContain("invoice_summary: Partial<Record<AppLocale, string>>;");
+    expect(output).not.toContain("typeof import");
+  });
+
+  it("emits explicit Partial schema types for single-file mode", () => {
+    const output = formatTypesFile({
+      isSingle: true,
+      entries: [{ namespace: "translations", filePath: "src/i18n/translations/translations.yaml" }],
+      projectRoot,
+      typesOutputPath,
+      paramsTypeName: "AppParams",
+      schemaTypeName: "AppSchema",
+      localeTypeName: "AppLocale",
+      localeFallbackConstName: "LOCALE_FALLBACK",
+      localeFallbackTypeName: "AppLocaleFallback",
+      paramsByNamespace: {
+        translations: {
+          welcome: "{ name: string }",
+        },
+      },
+      requestLocaleUnion: "'en' | 'it'",
+      hasLazy: false,
+      loadOnInitSet: new Set(),
+      lazyEntries: [],
+    });
+
+    expect(output).toContain(
+      "export type AppSchema = {\n  welcome: Partial<Record<AppLocale, string>>;\n};"
+    );
+    expect(output).not.toContain("typeof import");
+  });
+
+  it("emits delivery area type for custom delivery", () => {
+    const output = formatTypesFile({
+      isSingle: false,
+      entries: [
+        { namespace: "default", filePath: "src/i18n/translations/default.json" },
+        { namespace: "billing", filePath: "src/i18n/translations/billing.yaml" },
+      ],
+      projectRoot,
+      typesOutputPath,
+      paramsTypeName: "AppParams",
+      schemaTypeName: "AppSchema",
+      localeTypeName: "AppLocale",
+      localeFallbackConstName: "LOCALE_FALLBACK",
+      localeFallbackTypeName: "AppLocaleFallback",
+      localeFallback: {
+        "en-US": null,
+        it: "en-US",
+        fr: null,
+      },
+      paramsByNamespace: {
+        default: { some_key: "never" },
+        billing: { invoice_summary: "{ count: number }" },
+      },
+      requestLocaleUnion: "'en-US' | 'fr' | 'it'",
+      deliveryAreaTypeName: "AppDeliveryArea",
+      deliveryAreaUnion: "'eu' | 'us'",
+      deliveryArtifacts: {
+        eu: ["it", "fr"],
+        us: ["en-US"],
+      },
+      hasLazy: true,
+      loadOnInitSet: new Set(["default"]),
+      lazyEntries: [{ namespace: "billing", filePath: "src/i18n/translations/billing.yaml" }],
+    });
+
+    expect(output).toContain("export type AppLocale = 'en-US' | 'fr' | 'it';");
+    expect(output).toContain("export type AppDeliveryArea = 'eu' | 'us';");
+    expect(output).toContain("export const LOCALE_DELIVERY_AREA = {");
+    expect(output).toContain('"it": "eu"');
+    expect(output).toContain('"en-US": "us"');
+    expect(output).toContain("} as const satisfies Record<AppLocale, AppDeliveryArea>;");
+    expect(output).toContain("some_key: Partial<Record<AppLocale, string>>;");
+  });
+});

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

@@ -1,8 +1,12 @@
-import path from "node:path";
+import { formatLocaleDeliveryAreaBlock, type DeliveryArtifactsMap } from "../delivery-artifacts.js";
 import { formatLocaleFallbackBlock } from "../locale-fallback.js";
-import { GENERATED_FILE_BANNER, toImportPath } from "../paths.js";
+import { GENERATED_FILE_BANNER } from "../paths.js";
 import type { NamespaceEntry } from "../types.js";
 
+/**
+ * Emits the generated `i18n-types.generated.ts` module: schema, params, locale/area
+ * unions, fallback constants, and lazy-load type aliases.
+ */
 export function formatLazyTypesBlock(
   loadOnInitSet: Set<string>,
   lazyEntries: NamespaceEntry[],
@@ -21,6 +25,13 @@ export function formatLazyTypesBlock(
   );
 }
 
+export function formatLocaleTemplateType(localeTypeName: string, hasLocaleUnion: boolean): string {
+  if (!hasLocaleUnion) {
+    return "Partial<Record<string, string>>";
+  }
+  return `Partial<Record<${localeTypeName}, string>>`;
+}
+
 export interface TypesFileOptions {
   isSingle: boolean;
   entries: NamespaceEntry[];
@@ -34,6 +45,10 @@ export interface TypesFileOptions {
   localeFallback?: Record<string, string | null> | undefined;
   paramsByNamespace: Record<string, Record<string, string>>;
   requestLocaleUnion: string;
+  deliveryAreaTypeName?: string;
+  deliveryAreaUnion?: string;
+  deliveryArtifacts?: DeliveryArtifactsMap;
+  localeDeliveryAreaConstName?: string;
   hasLazy: boolean;
   loadOnInitSet: Set<string>;
   lazyEntries: NamespaceEntry[];
@@ -43,8 +58,6 @@ export function formatTypesFile(options: TypesFileOptions): string {
   const {
     isSingle,
     entries,
-    projectRoot,
-    typesOutputPath,
     paramsTypeName,
     schemaTypeName,
     localeTypeName,
@@ -53,16 +66,36 @@ export function formatTypesFile(options: TypesFileOptions): string {
     localeFallback,
     paramsByNamespace,
     requestLocaleUnion,
+    deliveryAreaTypeName,
+    deliveryAreaUnion,
+    deliveryArtifacts,
+    localeDeliveryAreaConstName = "LOCALE_DELIVERY_AREA",
     hasLazy,
     loadOnInitSet,
     lazyEntries,
   } = options;
 
+  const hasLocaleUnion = Boolean(requestLocaleUnion);
+  const localeTemplateType = formatLocaleTemplateType(localeTypeName, hasLocaleUnion);
+
   const localeBlock = requestLocaleUnion
     ? `${localeFallback ? formatLocaleFallbackBlock(localeFallback, localeFallbackConstName, localeFallbackTypeName) : ""}` +
       `export type ${localeTypeName} = ${requestLocaleUnion};\n\n`
     : "";
 
+  const deliveryAreaBlock =
+    deliveryAreaTypeName && deliveryAreaUnion
+      ? `export type ${deliveryAreaTypeName} = ${deliveryAreaUnion};\n\n` +
+        (deliveryArtifacts
+          ? formatLocaleDeliveryAreaBlock(
+              deliveryArtifacts,
+              localeDeliveryAreaConstName,
+              localeTypeName,
+              deliveryAreaTypeName
+            )
+          : "")
+      : "";
+
   let paramsBlock: string;
   let schemaBlock: string;
 
@@ -75,11 +108,11 @@ export function formatTypesFile(options: TypesFileOptions): string {
 
     paramsBlock = `export type ${paramsTypeName} = {\n${paramsLines}\n};`;
 
-    const importPath = toImportPath(
-      typesOutputPath,
-      path.resolve(projectRoot, entries[0]!.filePath)
-    );
-    schemaBlock = `export type ${schemaTypeName} = typeof import('${importPath}.json');`;
+    const schemaLines = Object.keys(keyTypes)
+      .map((key) => `  ${key}: ${localeTemplateType};`)
+      .join("\n");
+
+    schemaBlock = `export type ${schemaTypeName} = {\n${schemaLines}\n};`;
   } else {
     const namespaceBlocks = entries
       .map((entry) => {
@@ -95,8 +128,11 @@ export function formatTypesFile(options: TypesFileOptions): string {
 
     const schemaLines = entries
       .map((entry) => {
-        const importPath = toImportPath(typesOutputPath, path.resolve(projectRoot, entry.filePath));
-        return `  ${entry.namespace}: typeof import('${importPath}.json');`;
+        const keyTypes = paramsByNamespace[entry.namespace] ?? {};
+        const lines = Object.keys(keyTypes)
+          .map((key) => `    ${key}: ${localeTemplateType};`)
+          .join("\n");
+        return `  ${entry.namespace}: {\n${lines}\n  };`;
       })
       .join("\n");
 
@@ -111,6 +147,7 @@ export function formatTypesFile(options: TypesFileOptions): string {
     `${GENERATED_FILE_BANNER}` +
     `export const I18N_MODE = '${isSingle ? "single" : "multi"}' as const;\n\n` +
     `${localeBlock}` +
+    `${deliveryAreaBlock}` +
     `${paramsBlock}\n\n` +
     `${schemaBlock}\n` +
     `${lazyTypesBlock}`