@xndrjs/i18n 0.4.0 → 0.5.0-alpha.0

package/src/project-locales.test.ts

@@ -1,7 +1,12 @@
 import { describe, expect, it } from "vitest";
-import { projectLocales, projectNamespacesLocales } from "./project-locales.js";
+import {
+  projectDictionaryForDeliveryAreaCore,
+  projectDictionaryLocalesCore,
+  projectNamespaceForDeliveryAreaCore,
+  projectNamespaceLocalesCore,
+} from "./project-locales.js";
 
-describe("projectLocales", () => {
+describe("projectNamespaceLocalesCore", () => {
   const dictionary = {
     login_button: { en: "Login", it: "Accedi" },
     welcome: { en: "Welcome {name}!", it: "Benvenuto {name}!" },
@@ -16,7 +21,7 @@ describe("projectLocales", () => {
   } as const;
 
   it("keeps only the requested locales with direct templates", () => {
-    expect(projectLocales(dictionary, ["en", "it"])).toEqual({
+    expect(projectNamespaceLocalesCore(dictionary, ["en", "it"])).toEqual({
       login_button: { en: "Login", it: "Accedi" },
       welcome: { en: "Welcome {name}!", it: "Benvenuto {name}!" },
       empty_label: { en: "" },
@@ -24,7 +29,7 @@ describe("projectLocales", () => {
   });
 
   it("drops locales not listed in the projection", () => {
-    expect(projectLocales(dictionary, ["en"])).toEqual({
+    expect(projectNamespaceLocalesCore(dictionary, ["en"])).toEqual({
       login_button: { en: "Login" },
       welcome: { en: "Welcome {name}!" },
       empty_label: { en: "" },
@@ -32,7 +37,7 @@ describe("projectLocales", () => {
   });
 
   it("resolves fallback templates for missing direct locale entries", () => {
-    expect(projectLocales(dictionary, ["de-CH"], fallback)).toEqual({
+    expect(projectNamespaceLocalesCore(dictionary, ["de-CH"], fallback)).toEqual({
       login_button: { "de-CH": "Login" },
       welcome: { "de-CH": "Welcome {name}!" },
       empty_label: { "de-CH": "" },
@@ -40,7 +45,7 @@ describe("projectLocales", () => {
   });
 
   it("projects multiple locales with mixed direct and fallback resolution", () => {
-    expect(projectLocales(dictionary, ["it", "de-CH"], fallback)).toEqual({
+    expect(projectNamespaceLocalesCore(dictionary, ["it", "de-CH"], fallback)).toEqual({
       login_button: { it: "Accedi", "de-CH": "Login" },
       welcome: { it: "Benvenuto {name}!", "de-CH": "Welcome {name}!" },
       empty_label: { it: "", "de-CH": "" },
@@ -52,13 +57,13 @@ describe("projectLocales", () => {
       login_button: { it: "Accedi" },
     };
 
-    expect(projectLocales(partial, ["en", "it"], fallback)).toEqual({
+    expect(projectNamespaceLocalesCore(partial, ["en", "it"], fallback)).toEqual({
       login_button: { it: "Accedi" },
     });
   });
 
   it("deduplicates locales in the projection list", () => {
-    expect(projectLocales(dictionary, ["en", "en"])).toEqual({
+    expect(projectNamespaceLocalesCore(dictionary, ["en", "en"])).toEqual({
       login_button: { en: "Login" },
       welcome: { en: "Welcome {name}!" },
       empty_label: { en: "" },
@@ -66,7 +71,121 @@ describe("projectLocales", () => {
   });
 });
 
-describe("projectNamespacesLocales", () => {
+describe("projectNamespaceForDeliveryAreaCore", () => {
+  const namespace = {
+    some_key: { it: "Ciao", "it-CH": "Ciao CH", fr: "Hallo", "en-US": "Hello" },
+    some_other_key: { "en-US": "Computer", fr: "Ordinateur" },
+  };
+
+  const localeFallback = {
+    "en-US": null,
+    it: "en-US",
+    "it-CH": "it",
+    fr: null,
+  } as const;
+
+  it("projects eu area with fallback resolution for full locales", () => {
+    expect(
+      projectNamespaceForDeliveryAreaCore(namespace, ["it", "fr", "it-CH"], localeFallback)
+    ).toEqual({
+      some_key: { it: "Ciao", fr: "Hallo", "it-CH": "Ciao CH" },
+      // it-CH is preserve (fallback it is in the area): copied only when present in the
+      // canonical dict; "it" is full (fallback en-US is outside the area) and resolves here.
+      some_other_key: { it: "Computer", fr: "Ordinateur" },
+    });
+  });
+
+  it("projects us area with single full locale", () => {
+    expect(projectNamespaceForDeliveryAreaCore(namespace, ["en-US"], localeFallback)).toEqual({
+      some_key: { "en-US": "Hello" },
+      some_other_key: { "en-US": "Computer" },
+    });
+  });
+
+  it("preserves canonical entries for in-area fallback locales without resolving", () => {
+    const withInAreaFallback = {
+      some_key: { it: "Ciao", "it-CH": "Ciao CH", fr: "Hallo", "en-US": "Hello" },
+      some_other_key: {
+        it: "Italiano",
+        "it-CH": "Svizzero",
+        "en-US": "Computer",
+        fr: "Ordinateur",
+      },
+    };
+
+    expect(
+      projectNamespaceForDeliveryAreaCore(
+        withInAreaFallback,
+        ["it", "it-CH", "en-US", "fr"],
+        localeFallback
+      )
+    ).toEqual({
+      some_key: { it: "Ciao", "it-CH": "Ciao CH", "en-US": "Hello", fr: "Hallo" },
+      some_other_key: {
+        it: "Italiano",
+        "it-CH": "Svizzero",
+        "en-US": "Computer",
+        fr: "Ordinateur",
+      },
+    });
+  });
+});
+
+describe("projectDictionaryForDeliveryAreaCore", () => {
+  const localeFallback = {
+    "en-US": null,
+    it: "en-US",
+    "it-CH": "it",
+    fr: null,
+  } as const;
+
+  it("projects each namespace independently for a multi-namespace dictionary", () => {
+    const dictionary = {
+      default: {
+        some_key: { it: "Ciao", "it-CH": "Ciao CH", fr: "Hallo", "en-US": "Hello" },
+        some_other_key: { "en-US": "Computer", fr: "Ordinateur" },
+      },
+      billing: {
+        invoice_summary: {
+          it: "{count} fatture",
+          "en-US": "{count} invoices",
+          fr: "{count} factures",
+        },
+      },
+    };
+
+    expect(
+      projectDictionaryForDeliveryAreaCore(dictionary, ["it", "fr", "it-CH"], localeFallback)
+    ).toEqual({
+      default: {
+        some_key: { it: "Ciao", fr: "Hallo", "it-CH": "Ciao CH" },
+        some_other_key: { it: "Computer", fr: "Ordinateur" },
+      },
+      billing: {
+        invoice_summary: { it: "{count} fatture", fr: "{count} factures" },
+      },
+    });
+  });
+
+  it("matches projectNamespaceForDeliveryAreaCore applied per namespace", () => {
+    const dictionary = {
+      default: {
+        some_key: { it: "Ciao", "en-US": "Hello" },
+      },
+      billing: {
+        invoice_summary: { it: "{count} fatture", "en-US": "{count} invoices" },
+      },
+    };
+    const areaLocales = ["en-US"] as const;
+
+    expect(projectDictionaryForDeliveryAreaCore(dictionary, areaLocales, localeFallback)).toEqual({
+      default: projectNamespaceForDeliveryAreaCore(dictionary.default, areaLocales, localeFallback),
+      billing: projectNamespaceForDeliveryAreaCore(dictionary.billing, areaLocales, localeFallback),
+    });
+  });
+});
+
+describe("projectDictionaryLocalesCore", () => {
   it("projects each namespace independently", () => {
     const dictionary = {
       default: {
@@ -77,7 +196,7 @@ describe("projectNamespacesLocales", () => {
       },
     };
 
-    expect(projectNamespacesLocales(dictionary, ["en"])).toEqual({
+    expect(projectDictionaryLocalesCore(dictionary, ["en"])).toEqual({
       default: { login_button: { en: "Login" } },
       billing: { invoice_summary: { en: "{count} invoices" } },
     });

package/src/project-locales.ts

@@ -1,6 +1,26 @@
 import { resolveLocaleTemplate } from "./resolve-locale.js";
 import type { KeyDictionary, LocaleFallbackMap, MultiDictionary } from "./types.js";
 
+function classifyAreaLocales(
+  areaLocales: readonly string[],
+  localeFallback?: LocaleFallbackMap
+): { full: string[]; preserve: string[] } {
+  const areaSet = new Set(areaLocales);
+  const full: string[] = [];
+  const preserve: string[] = [];
+
+  for (const locale of areaLocales) {
+    const fallback = localeFallback?.[locale];
+    if (fallback !== null && fallback !== undefined && areaSet.has(fallback)) {
+      preserve.push(locale);
+    } else {
+      full.push(locale);
+    }
+  }
+
+  return { full, preserve };
+}
+
 function projectKeyDictionary<T extends KeyDictionary>(
   dictionary: T,
   locales: readonly string[],
@@ -28,11 +48,11 @@ function projectKeyDictionary<T extends KeyDictionary>(
 }
 
 /**
- * Builds a dictionary that contains only the requested locales.
+ * Builds a namespace dictionary that contains only the requested locales.
  * For each key and target locale, copies the direct template when present;
  * otherwise resolves through `localeFallback` (same rules as `.get()` at runtime).
  */
-export function projectLocales<T extends KeyDictionary>(
+export function projectNamespaceLocalesCore<T extends KeyDictionary>(
   dictionary: T,
   locales: readonly string[],
   localeFallback?: LocaleFallbackMap
@@ -40,10 +60,77 @@ export function projectLocales<T extends KeyDictionary>(
   return projectKeyDictionary(dictionary, locales, localeFallback);
 }
 
+/**
+ * Projects a single namespace for a custom delivery area.
+ * Full locales resolve through `localeFallback` (e.g. external chains like `it → en-US`);
+ * preserve locales copy only their direct canonical entry when present.
+ */
+export function projectNamespaceForDeliveryAreaCore<T extends KeyDictionary>(
+  dictionary: T,
+  areaLocales: readonly string[],
+  localeFallback?: LocaleFallbackMap
+): T {
+  const { full, preserve } = classifyAreaLocales(areaLocales, localeFallback);
+  const fullProjection =
+    full.length > 0 ? projectKeyDictionary(dictionary, full, localeFallback) : undefined;
+  const result = {} as T;
+
+  for (const [key, localesByKey] of Object.entries(dictionary)) {
+    const projected: Record<string, string> = {};
+
+    if (fullProjection !== undefined) {
+      const fullEntry = fullProjection[key as keyof T];
+      if (fullEntry !== undefined) {
+        Object.assign(projected, fullEntry);
+      }
+    }
+
+    for (const locale of preserve) {
+      const template = localesByKey[locale];
+      if (template !== undefined) {
+        projected[locale] = template;
+      }
+    }
+
+    if (Object.keys(projected).length > 0) {
+      result[key as keyof T] = projected as T[keyof T];
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Projects a multi-namespace dictionary for a custom delivery area.
+ * Each namespace uses the same delivery-area rules as `projectNamespaceForDeliveryAreaCore`.
+ */
+export function projectDictionaryForDeliveryAreaCore<T extends MultiDictionary>(
+  dictionary: T,
+  areaLocales: readonly string[],
+  localeFallback?: LocaleFallbackMap
+): T {
+  const result = {} as T;
+
+  for (const namespace of Object.keys(dictionary) as (keyof T & string)[]) {
+    const namespaceDictionary = dictionary[namespace];
+    if (namespaceDictionary === undefined) {
+      continue;
+    }
+
+    result[namespace] = projectNamespaceForDeliveryAreaCore(
+      namespaceDictionary,
+      areaLocales,
+      localeFallback
+    ) as T[typeof namespace];
+  }
+
+  return result;
+}
+
 /**
  * Projects every namespace in a multi-namespace dictionary.
  */
-export function projectNamespacesLocales<T extends MultiDictionary>(
+export function projectDictionaryLocalesCore<T extends MultiDictionary>(
   dictionary: T,
   locales: readonly string[],
   localeFallback?: LocaleFallbackMap

package/src/setup/setup-i18n.test.ts

@@ -3,7 +3,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, it, afterEach } from "vitest";
 import { buildCodegenConfig, parseSetupArgs, runSetup } from "./setup-i18n.js";
-import { inferProjectName, typeNamesForProject } from "./type-names.js";
+import { inferProjectName, typeNamesForProject } from "../codegen-config/type-names.js";
 
 describe("type-names", () => {
   it("derives PascalCase project names from directory names", () => {

package/src/setup/setup-i18n.ts

@@ -1,10 +1,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { buildCodegenConfig, type SetupMode } from "../codegen-config/build-config.js";
+import { inferProjectName } from "../codegen-config/type-names.js";
+import { writeCodegenConfig } from "../codegen-config/write-config.js";
 import { DEFAULT_IMPORT_EXTENSION, importExtensionSuffix } from "../codegen/paths.js";
-import { inferProjectName, typeNamesForProject } from "./type-names.js";
 
-export type SetupMode = "single" | "multi";
+export type { SetupMode } from "../codegen-config/build-config.js";
+export { buildCodegenConfig } from "../codegen-config/build-config.js";
 
 export interface SetupOptions {
   mode: SetupMode;
@@ -53,33 +56,6 @@ function relative(fromRoot: string, filePath: string): string {
   return path.relative(fromRoot, filePath).replace(/\\/g, "/");
 }
 
-export function buildCodegenConfig(mode: SetupMode, project: string): Record<string, unknown> {
-  const typeNames = typeNamesForProject(project);
-  const base = {
-    typesOutput: `${GENERATED_DIR}/i18n-types.generated.ts`,
-    dictionaryOutput: `${GENERATED_DIR}/dictionary.generated.ts`,
-    instanceOutput: `${GENERATED_DIR}/instance.generated.ts`,
-    paramsTypeName: typeNames.paramsTypeName,
-    schemaTypeName: typeNames.schemaTypeName,
-    localeTypeName: typeNames.localeTypeName,
-    factoryName: "createI18n",
-  };
-
-  if (mode === "single") {
-    return {
-      dictionary: `${TRANSLATIONS_DIR}/translations.json`,
-      ...base,
-    };
-  }
-
-  return {
-    namespaces: {
-      default: `${TRANSLATIONS_DIR}/default.json`,
-    },
-    ...base,
-  };
-}
-
 export function runSetup(options: SetupOptions): SetupResult {
   const targetDir = path.resolve(options.targetDir);
   const project =
@@ -100,7 +76,7 @@ export function runSetup(options: SetupOptions): SetupResult {
 
   const created: string[] = [];
 
-  writeJson(configPath, buildCodegenConfig(options.mode, project));
+  writeCodegenConfig(configPath, buildCodegenConfig(options.mode, project));
   created.push(relative(targetDir, configPath));
 
   if (options.mode === "single") {

package/src/types.ts

@@ -18,15 +18,30 @@ export type LocaleOfMulti<Schema extends MultiDictionary> = {
 
 export type LocaleFallbackMap = Record<string, string | null>;
 
-export type RequestLocale<
-  DictionaryLocale extends string,
-  Fallback extends LocaleFallbackMap | undefined = undefined,
-> = DictionaryLocale | (Fallback extends LocaleFallbackMap ? keyof Fallback & string : never);
+export type MissingTranslationContext = {
+  /** Only set by the multi-namespace provider. */
+  namespace?: string;
+  key: string;
+  locale: string;
+  fallbackChain: string;
+};
+
+export type OnMissingTranslation =
+  | "throw"
+  | "key"
+  | ((context: MissingTranslationContext) => string);
 
 export type IcuTranslationProviderOptions<
   Fallback extends LocaleFallbackMap | undefined = undefined,
 > = {
   localeFallback?: Fallback;
+  /**
+   * Strategy when no template resolves for a key/locale (after walking the
+   * fallback chain). "throw" (default) raises an error, "key" returns the
+   * translation key itself, a function receives the context and returns the
+   * string to display. ICU syntax and formatting errors always throw.
+   */
+  onMissing?: OnMissingTranslation;
 };
 
 export type LocaleCache = Record<string, IntlMessageFormat>;

package/src/validation/normalize.ts

@@ -107,6 +107,10 @@ function normalizeKeyDictionary(
   return { ok: true, data: keys };
 }
 
+/**
+ * Validation step 1: coerce external input into a normalized dictionary shape
+ * (keys, locales, ICU args) against a `DictionarySpec`.
+ */
 export function normalizeDictionary(
   input: unknown,
   spec: DictionarySpec