@xndrjs/i18n 0.3.3 → 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;
@@ -32,11 +35,12 @@ const DEFAULT_STARTER = {
 const DEFAULT_IMPORT_SUFFIX = importExtensionSuffix(DEFAULT_IMPORT_EXTENSION);
 
 const INDEX_TS =
-  `import { createI18n } from "./generated/instance.generated${DEFAULT_IMPORT_SUFFIX}";\n\n` +
+  `import { createI18n } from "./generated/instance.generated${DEFAULT_IMPORT_SUFFIX}";\n` +
+  `import { defaultDictionary } from "./generated/dictionary.generated${DEFAULT_IMPORT_SUFFIX}";\n\n` +
   `export * from "./generated/instance.generated${DEFAULT_IMPORT_SUFFIX}";\n` +
   `export * from "./generated/dictionary.generated${DEFAULT_IMPORT_SUFFIX}";\n` +
   `export * from "./generated/i18n-types.generated${DEFAULT_IMPORT_SUFFIX}";\n\n` +
-  `export const i18n = createI18n();\n`;
+  `export const i18n = createI18n(defaultDictionary);\n`;
 
 function writeJson(filePath: string, value: unknown): void {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
@@ -52,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 =
@@ -99,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

package/dist/types-C1CpXVOJ.d.ts

@@ -1,83 +0,0 @@
-import { parse } from '@formatjs/icu-messageformat-parser';
-
-type VariableType = "string" | "number" | "date";
-type VariableSpec = Record<string, VariableType>;
-type VariableRole = "simple" | "plural" | "selectordinal" | "select" | "number" | "date" | "time";
-type VariableMeta = {
-    type: VariableType;
-    roles: Set<VariableRole>;
-};
-type VariableMetaSpec = Record<string, VariableMeta>;
-type IcuAst = ReturnType<typeof parse>;
-declare function extractVariables(nodes: IcuAst): VariableSpec;
-declare function mergeVariableSpecs(target: VariableSpec, source: VariableSpec): VariableSpec;
-declare function variableSpecsEqual(a: VariableSpec, b: VariableSpec): boolean;
-
-type ParsedLocaleEntry = {
-    readonly template: string;
-    readonly args: VariableSpec;
-};
-type ParsedKeyEntry = {
-    readonly locales: Readonly<Record<string, ParsedLocaleEntry>>;
-    readonly mergedArgs: VariableSpec;
-};
-type NormalizedKeyDictionary = Readonly<Record<string, ParsedKeyEntry>>;
-type NormalizedMultiDictionary = Readonly<Record<string, NormalizedKeyDictionary>>;
-type NormalizedDictionary = {
-    readonly mode: "single";
-    readonly keys: NormalizedKeyDictionary;
-} | {
-    readonly mode: "multi";
-    readonly namespaces: NormalizedMultiDictionary;
-};
-type DictionarySpec = {
-    readonly mode: "single";
-    readonly requiredKeys: readonly string[];
-    readonly argsByKey: Readonly<Record<string, VariableSpec>>;
-} | {
-    readonly mode: "multi";
-    readonly requiredKeys: Readonly<Record<string, readonly string[]>>;
-    readonly argsByKey: Readonly<Record<string, Readonly<Record<string, VariableSpec>>>>;
-};
-type ValidationIssue = {
-    readonly kind: "invalid_input";
-    readonly message: string;
-} | {
-    readonly kind: "missing_key";
-    readonly path: readonly string[];
-} | {
-    readonly kind: "invalid_locale_value";
-    readonly path: readonly string[];
-    readonly message: string;
-} | {
-    readonly kind: "icu_syntax_error";
-    readonly path: readonly string[];
-    readonly message: string;
-} | {
-    readonly kind: "locale_args_mismatch";
-    readonly path: readonly string[];
-    readonly locales: Readonly<Record<string, VariableSpec>>;
-    readonly message: string;
-} | {
-    readonly kind: "variable_mismatch";
-    readonly path: readonly string[];
-    readonly expected: VariableSpec;
-    readonly found: VariableSpec;
-    readonly message: string;
-} | {
-    readonly kind: "variable_type_mismatch";
-    readonly path: readonly string[];
-    readonly variable: string;
-    readonly expected: VariableType;
-    readonly found: VariableType;
-    readonly message: string;
-};
-type ValidationResult<T> = {
-    readonly ok: true;
-    readonly data: T;
-} | {
-    readonly ok: false;
-    readonly issues: readonly ValidationIssue[];
-};
-
-export { type DictionarySpec as D, type NormalizedDictionary as N, type ParsedKeyEntry as P, type ValidationResult as V, type VariableSpec as a, type ValidationIssue as b, type VariableMetaSpec as c, type NormalizedKeyDictionary as d, type NormalizedMultiDictionary as e, type ParsedLocaleEntry as f, type VariableType as g, extractVariables as h, mergeVariableSpecs as m, variableSpecsEqual as v };

package/src/ensure-namespace.integration.test.ts

@@ -1,66 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { ensureNamespacesLoadedImpl } from "./ensure-namespace.js";
-import { IcuTranslationProviderMulti } from "./IcuTranslationProviderMulti.js";
-
-type TestSchema = {
-  default: {
-    login_button: { en: string };
-  };
-  user: {
-    greeting: { en: string };
-  };
-  billing: {
-    invoice_summary: { en: string };
-  };
-};
-
-type TestParams = {
-  default: { login_button: never };
-  user: { greeting: { name: string } };
-  billing: { invoice_summary: { count: number } };
-};
-
-const namespaces: TestSchema = {
-  default: { login_button: { en: "Login" } },
-  user: { greeting: { en: "Hello {name}!" } },
-  billing: {
-    invoice_summary: {
-      en: "You have {count, plural, one {1 invoice} other {{count} invoices}}",
-    },
-  },
-};
-
-describe("ensureNamespacesLoadedImpl integration", () => {
-  it("mirrors the lazy codegen flow: partial init, preload batch, sync get", async () => {
-    const i18n = new IcuTranslationProviderMulti<TestSchema, TestParams>({
-      default: namespaces.default,
-    });
-
-    expect(i18n.hasNamespace("default")).toBe(true);
-    expect(i18n.hasNamespace("user")).toBe(false);
-    expect(i18n.hasNamespace("billing")).toBe(false);
-
-    expect(i18n.get("default", "login_button", "en")).toBe("Login");
-
-    expect(() => i18n.get("billing", "invoice_summary", "en", { count: 1 })).toThrow(
-      'Namespace not loaded: "billing"'
-    );
-
-    await ensureNamespacesLoadedImpl(
-      {
-        provider: i18n,
-        resolveLoader: (namespace) => async () => namespaces[namespace],
-        validate: (_namespace, raw) => ({ ok: true, data: raw as TestSchema["billing"] }),
-      },
-      ["user", "billing"]
-    );
-
-    expect(i18n.get("user", "greeting", "en", { name: "Ada" })).toBe("Hello Ada!");
-    expect(i18n.get("billing", "invoice_summary", "en", { count: 2 })).toBe("You have 2 invoices");
-
-    i18n.setNamespace("billing", {
-      invoice_summary: { en: "{count, plural, one {1 bill} other {{count} bills}}" },
-    });
-    expect(i18n.get("billing", "invoice_summary", "en", { count: 3 })).toBe("3 bills");
-  });
-});