@xndrjs/i18n 0.4.0 → 0.5.0

package/src/codegen/delivery-artifacts.ts

@@ -0,0 +1,124 @@
+/** Valid TypeScript identifier / filename segment for a delivery area id. */
+export const DELIVERY_AREA_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+
+export type DeliveryArtifactsMap = Record<string, readonly string[]>;
+
+export type DeliveryArtifactsIssue = {
+  path: (string | number)[];
+  message: string;
+};
+
+export function getDeliveryArtifactsStructureIssues(
+  deliveryArtifacts: DeliveryArtifactsMap
+): DeliveryArtifactsIssue[] {
+  const issues: DeliveryArtifactsIssue[] = [];
+
+  for (const [area, locales] of Object.entries(deliveryArtifacts)) {
+    if (!DELIVERY_AREA_NAME_PATTERN.test(area)) {
+      issues.push({
+        path: ["deliveryArtifacts", area],
+        message: `Invalid delivery area name "${area}": must match ${DELIVERY_AREA_NAME_PATTERN.source}`,
+      });
+    }
+
+    if (locales.length === 0) {
+      issues.push({
+        path: ["deliveryArtifacts", area],
+        message: `Delivery area "${area}" must include at least one locale.`,
+      });
+    }
+  }
+
+  const localeToArea = new Map<string, string>();
+  for (const [area, locales] of Object.entries(deliveryArtifacts)) {
+    for (const locale of locales) {
+      const previousArea = localeToArea.get(locale);
+      if (previousArea) {
+        issues.push({
+          path: ["deliveryArtifacts", area],
+          message: `Locale "${locale}" appears in both "${previousArea}" and "${area}".`,
+        });
+      } else {
+        localeToArea.set(locale, area);
+      }
+    }
+  }
+
+  return issues;
+}
+
+export function getDeliveryArtifactsPartitionIssues(
+  deliveryArtifacts: DeliveryArtifactsMap,
+  requestLocales: ReadonlySet<string>
+): DeliveryArtifactsIssue[] {
+  const issues: DeliveryArtifactsIssue[] = [];
+  const artifactLocales = new Set<string>();
+
+  for (const locales of Object.values(deliveryArtifacts)) {
+    for (const locale of locales) {
+      artifactLocales.add(locale);
+    }
+  }
+
+  const missing = [...requestLocales].filter((locale) => !artifactLocales.has(locale)).sort();
+  if (missing.length > 0) {
+    issues.push({
+      path: ["deliveryArtifacts"],
+      message: `deliveryArtifacts is missing locales required by dictionaries and localeFallback: ${missing.join(", ")}`,
+    });
+  }
+
+  const excess = [...artifactLocales].filter((locale) => !requestLocales.has(locale)).sort();
+  if (excess.length > 0) {
+    issues.push({
+      path: ["deliveryArtifacts"],
+      message: `deliveryArtifacts includes locales not required by dictionaries and localeFallback: ${excess.join(", ")}`,
+    });
+  }
+
+  return issues;
+}
+
+/** Pre-emit validation gate for `deliveryArtifacts` in custom delivery mode. */
+export function getDeliveryArtifactsIssues(
+  deliveryArtifacts: DeliveryArtifactsMap,
+  requestLocales: ReadonlySet<string>
+): DeliveryArtifactsIssue[] {
+  return [
+    ...getDeliveryArtifactsStructureIssues(deliveryArtifacts),
+    ...getDeliveryArtifactsPartitionIssues(deliveryArtifacts, requestLocales),
+  ];
+}
+
+export function getDeliveryAreaNames(deliveryArtifacts: DeliveryArtifactsMap): string[] {
+  return Object.keys(deliveryArtifacts).sort();
+}
+
+export function getLocaleDeliveryAreaMap(
+  deliveryArtifacts: DeliveryArtifactsMap
+): Record<string, string> {
+  const localeToArea: Record<string, string> = {};
+
+  for (const [area, locales] of Object.entries(deliveryArtifacts)) {
+    for (const locale of locales) {
+      localeToArea[locale] = area;
+    }
+  }
+
+  return localeToArea;
+}
+
+export function formatLocaleDeliveryAreaBlock(
+  deliveryArtifacts: DeliveryArtifactsMap,
+  constName: string,
+  localeTypeName: string,
+  deliveryAreaTypeName: string
+): string {
+  const localeToArea = getLocaleDeliveryAreaMap(deliveryArtifacts);
+  const lines = Object.keys(localeToArea)
+    .sort()
+    .map((locale) => `  ${JSON.stringify(locale)}: ${JSON.stringify(localeToArea[locale])},`)
+    .join("\n");
+
+  return `export const ${constName} = {\n${lines}\n} as const satisfies Record<${localeTypeName}, ${deliveryAreaTypeName}>;\n\n`;
+}

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

@@ -0,0 +1,190 @@
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { formatDictionaryFile } from "./dictionary-file.js";
+
+const projectRoot = "/project";
+const dictionaryOutputPath = path.join(projectRoot, "src/i18n/dictionary.generated.ts");
+const typesOutputPath = path.join(projectRoot, "src/i18n/i18n-types.generated.ts");
+
+describe("formatDictionaryFile", () => {
+  it("emits defaultDictionary in canonical mode", () => {
+    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: [{ namespace: "default", filePath: "src/i18n/translations/default.json" }],
+      projectRoot,
+      dictionaryOutputPath,
+      typesOutputPath,
+      schemaTypeName: "AppSchema",
+      localeTypeName: "AppLocale",
+      importExtension: "none",
+      delivery: "canonical",
+    });
+
+    expect(output).toContain("export const defaultDictionary: InitialSchema");
+    expect(output).toContain("defaultNs");
+    expect(output).not.toContain("defaultDictionaryFor");
+  });
+
+  it("emits defaultDictionaryFor with per-locale imports 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: [{ namespace: "default", filePath: "src/i18n/translations/default.json" }],
+      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).toContain("import defaultEn from './generated/translations/default.en.json';");
+    expect(output).toContain("import defaultIt from './generated/translations/default.it.json';");
+    expect(output).toContain(
+      "const defaultByLocale = {\n  en: defaultEn,\n  it: defaultIt,\n} as const;"
+    );
+    expect(output).toContain(
+      "export function defaultDictionaryFor(locale: AppLocale): InitialSchema"
+    );
+    expect(output).toContain("return {\n    default: defaultByLocale[locale],\n  };");
+    expect(output).not.toContain("export const defaultDictionary");
+    expect(output).not.toContain("billingEn");
+  });
+
+  it("emits defaultDictionaryFor with per-locale imports in split mode (single)", () => {
+    const output = formatDictionaryFile({
+      isSingle: true,
+      hasLazy: false,
+      entries: [{ namespace: "translations", filePath: "src/i18n/translations/translations.json" }],
+      eagerEntries: [
+        { namespace: "translations", filePath: "src/i18n/translations/translations.json" },
+      ],
+      projectRoot,
+      dictionaryOutputPath,
+      typesOutputPath,
+      schemaTypeName: "AppSchema",
+      localeTypeName: "AppLocale",
+      importExtension: "none",
+      delivery: "split-by-locale",
+      requestLocales: ["en", "it"],
+      splitPathsByNamespace: {
+        translations: {
+          en: "src/i18n/generated/translations/translations.en.json",
+          it: "src/i18n/generated/translations/translations.it.json",
+        },
+      },
+    });
+
+    expect(output).toContain(
+      "import translationsEn from './generated/translations/translations.en.json';"
+    );
+    expect(output).toContain(
+      "import translationsIt from './generated/translations/translations.it.json';"
+    );
+    expect(output).toContain("export function defaultDictionaryFor(locale: AppLocale): AppSchema");
+    expect(output).toContain("return translationsByLocale[locale];");
+    expect(output).not.toContain("export const defaultDictionary");
+  });
+
+  it("emits defaultDictionaryFor with per-area imports in custom 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: [{ namespace: "default", filePath: "src/i18n/translations/default.json" }],
+      projectRoot,
+      dictionaryOutputPath,
+      typesOutputPath,
+      schemaTypeName: "AppSchema",
+      localeTypeName: "AppLocale",
+      importExtension: "none",
+      delivery: "custom",
+      deliveryAreaTypeName: "AppDeliveryArea",
+      deliveryAreaNames: ["eu", "us"],
+      splitPathsByNamespace: {
+        default: {
+          eu: "src/i18n/generated/translations/default.eu.json",
+          us: "src/i18n/generated/translations/default.us.json",
+        },
+        billing: {
+          eu: "src/i18n/generated/translations/billing.eu.json",
+          us: "src/i18n/generated/translations/billing.us.json",
+        },
+      },
+    });
+
+    expect(output).toContain("import defaultEu from './generated/translations/default.eu.json';");
+    expect(output).toContain("import defaultUs from './generated/translations/default.us.json';");
+    expect(output).toContain(
+      "const defaultByArea = {\n  eu: defaultEu,\n  us: defaultUs,\n} as const;"
+    );
+    expect(output).toContain(
+      "export function defaultDictionaryFor(area: AppDeliveryArea): InitialSchema"
+    );
+    expect(output).toContain("return {\n    default: defaultByArea[area],\n  };");
+    expect(output).not.toContain("export const defaultDictionary");
+    expect(output).not.toContain("billingEu");
+  });
+
+  it("emits defaultDictionaryFor with per-area imports in custom mode (single)", () => {
+    const output = formatDictionaryFile({
+      isSingle: true,
+      hasLazy: false,
+      entries: [{ namespace: "translations", filePath: "src/i18n/translations/translations.json" }],
+      eagerEntries: [
+        { namespace: "translations", filePath: "src/i18n/translations/translations.json" },
+      ],
+      projectRoot,
+      dictionaryOutputPath,
+      typesOutputPath,
+      schemaTypeName: "AppSchema",
+      localeTypeName: "AppLocale",
+      importExtension: "none",
+      delivery: "custom",
+      deliveryAreaTypeName: "AppDeliveryArea",
+      deliveryAreaNames: ["eu", "us"],
+      splitPathsByNamespace: {
+        translations: {
+          eu: "src/i18n/generated/translations/translations.eu.json",
+          us: "src/i18n/generated/translations/translations.us.json",
+        },
+      },
+    });
+
+    expect(output).toContain(
+      "import translationsEu from './generated/translations/translations.eu.json';"
+    );
+    expect(output).toContain(
+      "import translationsUs from './generated/translations/translations.us.json';"
+    );
+    expect(output).toContain(
+      "export function defaultDictionaryFor(area: AppDeliveryArea): AppSchema"
+    );
+    expect(output).toContain("return translationsByArea[area];");
+    expect(output).not.toContain("export const defaultDictionary");
+  });
+});

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

@@ -3,11 +3,17 @@ import {
   GENERATED_FILE_BANNER,
   toImportIdentifier,
   toImportPath,
+  toLocaleObjectKey,
   toModuleBasename,
   toRelativeModuleImport,
 } from "../paths.js";
+import type { DeliveryMode } from "../codegen-config-schema.js";
 import type { ImportExtension, NamespaceEntry } from "../types.js";
 
+/**
+ * Emits the generated `dictionary.generated.ts` module: eager translation imports
+ * wired into `defaultDictionary` or `defaultDictionaryFor`, depending on delivery mode.
+ */
 export interface DictionaryFileOptions {
   isSingle: boolean;
   hasLazy: boolean;
@@ -17,10 +23,167 @@ export interface DictionaryFileOptions {
   dictionaryOutputPath: string;
   typesOutputPath: string;
   schemaTypeName: string;
+  localeTypeName: string;
   importExtension: ImportExtension;
+  delivery?: DeliveryMode;
+  splitPathsByNamespace?: Record<string, Record<string, string>>;
+  requestLocales?: readonly string[];
+  deliveryAreaTypeName?: string;
+  deliveryAreaNames?: readonly string[];
 }
 
+function toArtifactIdentifierSuffix(artifactKey: string): string {
+  return artifactKey
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
+}
+
+function toSplitImportIdentifier(namespace: string, artifactKey: string): string {
+  const namespaceId = toImportIdentifier(namespace).replace(/Ns$/, "");
+  return `${namespaceId}${toArtifactIdentifierSuffix(artifactKey)}`;
+}
+
+function toNamespaceBaseIdentifier(namespace: string): string {
+  return toImportIdentifier(namespace).replace(/Ns$/, "");
+}
+
+interface PartitionedDictionaryParams {
+  partitionKeys: readonly string[];
+  paramName: string;
+  paramTypeName: string;
+}
+
+function toPartitionSuffix(paramName: string): string {
+  return `By${paramName.charAt(0).toUpperCase()}${paramName.slice(1)}`;
+}
+
+/**
+ * Emits dictionary source for split-by-locale and custom delivery.
+ * Imports one JSON file per namespace × partition key (locale or area) and
+ * exposes `defaultDictionaryFor(partition)` that selects the matching slice.
+ */
+function formatPartitionedDictionaryFile(
+  options: DictionaryFileOptions,
+  { partitionKeys, paramName, paramTypeName }: PartitionedDictionaryParams
+): string {
+  const {
+    isSingle,
+    hasLazy,
+    eagerEntries,
+    projectRoot,
+    dictionaryOutputPath,
+    typesOutputPath,
+    schemaTypeName,
+    importExtension,
+    splitPathsByNamespace = {},
+  } = options;
+
+  const partitionSuffix = toPartitionSuffix(paramName);
+  const typesModule = toModuleBasename(typesOutputPath);
+  const typesImport = toRelativeModuleImport(typesModule, importExtension);
+  const dictionaryTypeName = hasLazy ? "InitialSchema" : schemaTypeName;
+  const schemaTypeImport = hasLazy ? `, ${schemaTypeName}` : "";
+
+  const imports = eagerEntries
+    .flatMap((entry) =>
+      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(
+          dictionaryOutputPath,
+          path.resolve(projectRoot, splitRelativePath)
+        );
+        const importId = toSplitImportIdentifier(entry.namespace, partitionKey);
+        return `import ${importId} from '${importPath}.json';`;
+      })
+    )
+    .join("\n");
+
+  if (isSingle) {
+    const entry = eagerEntries[0]!;
+    const baseId = toNamespaceBaseIdentifier(entry.namespace);
+    const partitionEntries = partitionKeys
+      .map(
+        (partitionKey) =>
+          `  ${toLocaleObjectKey(partitionKey)}: ${toSplitImportIdentifier(entry.namespace, partitionKey)},`
+      )
+      .join("\n");
+
+    return (
+      `${GENERATED_FILE_BANNER}` +
+      `${imports}\n` +
+      `import type { ${schemaTypeName}, ${paramTypeName} } from '${typesImport}';\n\n` +
+      `const ${baseId}${partitionSuffix} = {\n${partitionEntries}\n} as const;\n\n` +
+      `export function defaultDictionaryFor(${paramName}: ${paramTypeName}): ${schemaTypeName} {\n` +
+      `  return ${baseId}${partitionSuffix}[${paramName}];\n` +
+      `}\n`
+    );
+  }
+
+  const byPartitionBlocks = eagerEntries
+    .map((entry) => {
+      const baseId = toNamespaceBaseIdentifier(entry.namespace);
+      const partitionEntries = partitionKeys
+        .map(
+          (partitionKey) =>
+            `  ${toLocaleObjectKey(partitionKey)}: ${toSplitImportIdentifier(entry.namespace, partitionKey)},`
+        )
+        .join("\n");
+      return `const ${baseId}${partitionSuffix} = {\n${partitionEntries}\n} as const;`;
+    })
+    .join("\n\n");
+
+  const objectEntries = eagerEntries
+    .map((entry) => {
+      const baseId = toNamespaceBaseIdentifier(entry.namespace);
+      return `    ${entry.namespace}: ${baseId}${partitionSuffix}[${paramName}],`;
+    })
+    .join("\n");
+
+  const importsBlock = imports.length > 0 ? `${imports}\n` : "";
+  const byPartitionBlock = byPartitionBlocks.length > 0 ? `${byPartitionBlocks}\n\n` : "";
+
+  return (
+    `${GENERATED_FILE_BANNER}` +
+    `${importsBlock}` +
+    `import type { ${dictionaryTypeName}, ${paramTypeName}${schemaTypeImport} } from '${typesImport}';\n\n` +
+    `${byPartitionBlock}` +
+    `export function defaultDictionaryFor(${paramName}: ${paramTypeName}): ${dictionaryTypeName} {\n` +
+    `  return {\n${objectEntries}\n  };\n` +
+    `}\n`
+  );
+}
+
+/**
+ * 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 {
+  const delivery = options.delivery ?? "canonical";
+  if (delivery === "split-by-locale") {
+    return formatPartitionedDictionaryFile(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 formatPartitionedDictionaryFile(options, {
+      partitionKeys: options.deliveryAreaNames ?? [],
+      paramName: "area",
+      paramTypeName: options.deliveryAreaTypeName,
+    });
+  }
+
   const {
     isSingle,
     hasLazy,

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

@@ -14,6 +14,7 @@ function formatVariableSpecObject(spec: VariableSpec): string {
   return `{\n${lines.join("\n")}\n    }`;
 }
 
+/** Builds the `DICTIONARY_SPEC` constant from ICU analysis output (keys + variable args). */
 export function formatDictionarySpecBlock(
   isSingle: boolean,
   entries: NamespaceEntry[],
@@ -66,6 +67,10 @@ export function formatDictionarySpecBlock(
   );
 }
 
+/**
+ * Emits the optional dictionary-schema module: `DICTIONARY_SPEC` plus thin wrappers
+ * around `@xndrjs/i18n/validation` for external dictionary ingestion.
+ */
 export function formatDictionarySchemaFile(
   schemaTypeName: string,
   typesModule: string,