@xndrjs/i18n 0.6.1 → 0.7.0

package/src/IcuTranslationProviderMulti.ts

@@ -1,5 +1,12 @@
 import { cloneAndFreeze } from "./deep-freeze.js";
+import { BuilderLoadRegistry } from "./builder-load-registry.js";
+import type { I18nEngineMulti } from "./engine.js";
 import { resolveAndFormat } from "./format-core.js";
+import {
+  assertPatchKeyMulti,
+  recordPreloadedKeysMulti,
+  seedPreloadedKeysMulti,
+} from "./patch-key.js";
 import { mergeNamespaceLocalesCore } from "./project-locales.js";
 import { validateLocaleFallback } from "./resolve-locale.js";
 import type {
@@ -9,85 +16,34 @@ import type {
   MultiCompiledCache,
   MultiDictionary,
   OnMissingTranslation,
+  PartialKeyDictionary,
+  PartialMultiDictionary,
 } from "./types.js";
-
-export interface TranslationProviderMultiForLocale<
-  Schema extends MultiDictionary,
-  Params extends { [NS in keyof Schema]: { [K in keyof Schema[NS]]: unknown } },
-  Locale extends string,
-> {
-  readonly locale: Locale;
-  get<NS extends keyof Schema, K extends keyof Schema[NS] & keyof Params[NS] & string>(
-    namespace: NS,
-    key: K,
-    ...params: Params[NS][K] extends never ? [] : [params: Params[NS][K]]
-  ): string;
-}
-
-export interface TranslationProviderMulti<
-  Schema extends MultiDictionary,
-  Params extends { [NS in keyof Schema]: { [K in keyof Schema[NS]]: unknown } },
-  RequestLocales extends string = LocaleOfMulti<Schema>,
-> {
-  get<NS extends keyof Schema, K extends keyof Schema[NS] & keyof Params[NS] & string>(
-    namespace: NS,
-    key: K,
-    locale: RequestLocales,
-    ...params: Params[NS][K] extends never ? [] : [params: Params[NS][K]]
-  ): string;
-  forLocale<Locale extends RequestLocales>(
-    locale: Locale
-  ): TranslationProviderMultiForLocale<Schema, Params, Locale>;
-  getAll(): Schema;
-  hasNamespace<NS extends keyof Schema & string>(namespace: NS): boolean;
-  setAll(values: Schema): void;
-  mergeAll(values: Partial<Schema>): void;
-  setNamespace<NS extends keyof Schema>(namespace: NS, values: Schema[NS]): void;
-  mergeNamespace<NS extends keyof Schema>(namespace: NS, values: Schema[NS]): void;
-}
-
-export class IcuTranslationProviderMultiForLocale<
-  Schema extends MultiDictionary,
-  Params extends { [NS in keyof Schema]: { [K in keyof Schema[NS]]: unknown } },
-  RequestLocales extends string,
-  Locale extends RequestLocales,
-  Fallback extends LocaleFallbackMap | undefined,
-> implements TranslationProviderMultiForLocale<Schema, Params, Locale> {
-  constructor(
-    private readonly provider: IcuTranslationProviderMulti<
-      Schema,
-      Params,
-      RequestLocales,
-      Fallback
-    >,
-    readonly locale: Locale
-  ) {}
-
-  get<NS extends keyof Schema, K extends keyof Schema[NS] & keyof Params[NS] & string>(
-    namespace: NS,
-    key: K,
-    ...args: Params[NS][K] extends never ? [] : [params: Params[NS][K]]
-  ): string {
-    const params = args[0] as Record<string, unknown> | undefined;
-    return this.provider.getWithLocale(String(namespace), String(key), this.locale, params);
-  }
-}
+import { I18nScopeMultiForLocaleImpl, I18nScopeMultiImpl } from "./scope-multi.js";
+import type { I18nScopeMulti, I18nScopeMultiForLocale } from "./scope-multi.js";
+import type { MultiParams, ParamsForNamespaces, SchemaForNamespaces } from "./scope-types.js";
 
 export class IcuTranslationProviderMulti<
   Schema extends MultiDictionary,
-  Params extends { [NS in keyof Schema]: { [K in keyof Schema[NS]]: unknown } },
+  Params extends MultiParams<Schema>,
   RequestLocales extends string = LocaleOfMulti<Schema>,
   Fallback extends LocaleFallbackMap | undefined = undefined,
-> implements TranslationProviderMulti<Schema, Params, RequestLocales> {
+> implements I18nEngineMulti<Schema, Params, RequestLocales> {
+  readonly __i18nEngineMode = "multi" as const;
+
   private dictionary: Schema;
   private compiledCache: MultiCompiledCache = {};
+  private readonly preloadedKeys = new Set<string>();
+  private readonly builderLoadRegistry = new BuilderLoadRegistry();
   private readonly localeFallback?: Fallback;
   private readonly onMissing: OnMissingTranslation;
-  private loadedNamespaces: Set<string>;
 
-  constructor(dictionary: Partial<Schema>, options?: IcuTranslationProviderOptions<Fallback>) {
+  constructor(
+    dictionary: PartialMultiDictionary<Schema, RequestLocales>,
+    options?: IcuTranslationProviderOptions<Fallback>
+  ) {
     this.dictionary = structuredClone(dictionary) as Schema;
-    this.loadedNamespaces = new Set(Object.keys(dictionary));
+    seedPreloadedKeysMulti(this.dictionary, this.preloadedKeys);
     if (options?.localeFallback) {
       validateLocaleFallback(options.localeFallback);
       this.localeFallback = options.localeFallback;
@@ -95,28 +51,12 @@ export class IcuTranslationProviderMulti<
     this.onMissing = options?.onMissing ?? "throw";
   }
 
-  get<NS extends keyof Schema, K extends keyof Schema[NS] & keyof Params[NS] & string>(
-    namespace: NS,
-    key: K,
-    locale: RequestLocales,
-    ...args: Params[NS][K] extends never ? [] : [params: Params[NS][K]]
-  ): string {
-    const params = args[0] as Record<string, unknown> | undefined;
-    return this.getWithLocale(String(namespace), String(key), locale, params);
-  }
-
   getWithLocale(
     namespace: string,
     key: string,
     locale: string,
     params?: Record<string, unknown>
   ): string {
-    if (!this.loadedNamespaces.has(namespace)) {
-      throw new Error(
-        `[i18n] Namespace not loaded: "${namespace}". Register it with setNamespace() before calling .get().`
-      );
-    }
-
     const localeByKey = (
       this.dictionary[namespace] as Record<string, Record<string, string>> | undefined
     )?.[key];
@@ -144,54 +84,103 @@ export class IcuTranslationProviderMulti<
     });
   }
 
-  forLocale<Locale extends RequestLocales>(
-    locale: Locale
-  ): IcuTranslationProviderMultiForLocale<Schema, Params, RequestLocales, Locale, Fallback> {
-    return new IcuTranslationProviderMultiForLocale(this, locale);
+  toScope<
+    NsList extends readonly (keyof Schema & string)[],
+    Locale extends RequestLocales,
+  >(options: {
+    namespaces: NsList;
+    locale: Locale;
+  }): I18nScopeMultiForLocale<
+    SchemaForNamespaces<Schema, NsList>,
+    ParamsForNamespaces<Schema, Params, NsList>,
+    RequestLocales,
+    Locale
+  >;
+  toScope<NsList extends readonly (keyof Schema & string)[]>(options: {
+    namespaces: NsList;
+  }): I18nScopeMulti<
+    SchemaForNamespaces<Schema, NsList>,
+    ParamsForNamespaces<Schema, Params, NsList>,
+    RequestLocales
+  >;
+  toScope<
+    NsList extends readonly (keyof Schema & string)[],
+    Locale extends RequestLocales,
+  >(options: { namespaces: NsList; locale?: Locale }) {
+    if (options.locale !== undefined) {
+      return new I18nScopeMultiForLocaleImpl(this, options.locale) as I18nScopeMultiForLocale<
+        SchemaForNamespaces<Schema, NsList>,
+        ParamsForNamespaces<Schema, Params, NsList>,
+        RequestLocales,
+        Locale
+      >;
+    }
+    return new I18nScopeMultiImpl(this) as I18nScopeMulti<
+      SchemaForNamespaces<Schema, NsList>,
+      ParamsForNamespaces<Schema, Params, NsList>,
+      RequestLocales
+    >;
   }
 
   getAll(): Schema {
     return cloneAndFreeze(this.dictionary);
   }
 
-  hasNamespace<NS extends keyof Schema & string>(namespace: NS): boolean {
-    return this.loadedNamespaces.has(namespace);
+  hasBuilderResourceLoaded(namespace: string, partition: string | undefined): boolean {
+    return this.builderLoadRegistry.has(namespace, partition);
   }
 
-  setAll(values: Schema): void {
-    this.dictionary = structuredClone(values);
-    this.compiledCache = {};
-    this.loadedNamespaces = new Set(Object.keys(values));
+  markBuilderResourceLoaded(namespace: string, partition: string | undefined): void {
+    this.builderLoadRegistry.mark(namespace, partition);
   }
 
-  mergeAll(values: Partial<Schema>): void {
-    for (const namespace of Object.keys(values) as (keyof Schema & string)[]) {
-      const incoming = values[namespace];
-      if (incoming !== undefined) {
-        this.mergeNamespace(namespace, incoming as Schema[typeof namespace]);
-      }
-    }
-  }
+  applyLoadMergeNamespace<NS extends keyof Schema>(
+    namespace: NS,
+    values: PartialKeyDictionary<Schema[NS], RequestLocales>
+  ): void {
+    const existing = this.dictionary[namespace];
+    const merged = mergeNamespaceLocalesCore((existing ?? {}) as Schema[NS], values);
 
-  setNamespace<NS extends keyof Schema>(namespace: NS, values: Schema[NS]): void {
     this.dictionary = {
       ...this.dictionary,
-      [namespace]: structuredClone(values),
+      [namespace]: merged,
     };
-    this.loadedNamespaces.add(namespace as string);
+    recordPreloadedKeysMulti(namespace as string, values, this.preloadedKeys);
+
+    for (const [key, incomingLocales] of Object.entries(values)) {
+      if (incomingLocales === undefined || typeof incomingLocales !== "object") {
+        continue;
+      }
 
-    for (const locale of Object.keys(this.compiledCache)) {
-      delete this.compiledCache[locale]?.[namespace as string];
+      for (const locale of Object.keys(incomingLocales)) {
+        delete this.compiledCache[locale]?.[namespace as string]?.[key];
+      }
     }
   }
 
-  mergeNamespace<NS extends keyof Schema>(namespace: NS, values: Schema[NS]): void {
-    if (!this.loadedNamespaces.has(namespace as string)) {
-      this.setNamespace(namespace, values);
-      return;
+  applyLoadMergeAll(values: PartialMultiDictionary<Schema, RequestLocales>): void {
+    for (const namespace of Object.keys(values) as (keyof Schema & string)[]) {
+      const incoming = values[namespace];
+      if (incoming !== undefined) {
+        this.applyLoadMergeNamespace(namespace, incoming);
+      }
     }
+  }
 
-    const existing = this.dictionary[namespace];
-    this.setNamespace(namespace, mergeNamespaceLocalesCore(existing as Schema[NS], values));
+  patchKeyMulti(namespace: string, key: string, locale: string, template: string): void {
+    const namespaceDictionary = this.dictionary[namespace] as
+      | Record<string, Record<string, string>>
+      | undefined;
+    const localeByKey = namespaceDictionary?.[key];
+
+    assertPatchKeyMulti(namespace, key, locale, template, this.preloadedKeys, localeByKey);
+
+    this.applyLoadMergeNamespace(
+      namespace as keyof Schema,
+      { [key]: { [locale]: template } } as PartialKeyDictionary<
+        Schema[keyof Schema],
+        RequestLocales
+      >
+    );
   }
 }

package/src/IcuTranslationProviderSingle.test.ts

@@ -1,6 +1,5 @@
 import { describe, expect, it } from "vitest";
 import { IcuTranslationProviderSingle } from "./IcuTranslationProviderSingle.js";
-import type { LocaleOfSingle } from "./types.js";
 
 type TestSchema = {
   login_button: { en: string; it: string };
@@ -82,160 +81,19 @@ const dictionary: TestSchema = {
 };
 
 describe("IcuTranslationProviderSingle", () => {
-  const provider = new IcuTranslationProviderSingle<TestSchema, TestParams>(dictionary);
+  const engine = new IcuTranslationProviderSingle<TestSchema, TestParams>(dictionary);
 
-  it("returns a static translation without params", () => {
-    expect(provider.get("login_button", "it")).toBe("Accedi");
-  });
-
-  it("interpolates ICU arguments", () => {
-    expect(provider.get("welcome", "en", { name: "Ada" })).toBe("Welcome Ada!");
-  });
-
-  describe("ICU plural interpolation", () => {
-    it("formats a single numeric plural in English and Italian", () => {
-      expect(provider.get("invoice_count", "en", { count: 1 })).toBe("You have 1 invoice");
-      expect(provider.get("invoice_count", "en", { count: 5 })).toBe("You have 5 invoices");
-      expect(provider.get("invoice_count", "it", { count: 1 })).toBe("Hai 1 fattura");
-      expect(provider.get("invoice_count", "it", { count: 5 })).toBe("Hai 5 fatture");
-    });
-
-    it("uses =5 for an exact match; zero is a locale plural category, not exact match in English", () => {
-      // ICU "zero" is a plural rule category (e.g. Arabic); in English, 0 maps to "other".
-      expect(provider.get("item_count_zero", "en", { count: 0 })).toBe("0 items");
-      // "=5" is an exact-value selector and matches count === 5 in any locale.
-      expect(provider.get("item_count_exact", "en", { count: 0 })).toBe("0 items");
-      expect(provider.get("item_count_exact", "en", { count: 1 })).toBe("1 item");
-      expect(provider.get("item_count_exact", "en", { count: 5 })).toBe("five items");
-    });
-
-    it("formats nested numeric plurals with double-brace references", () => {
-      expect(provider.get("dashboard_status", "en", { msgCount: 1, chatCount: 1 })).toBe(
-        "You have 1 message in one chat"
-      );
-      expect(provider.get("dashboard_status", "en", { msgCount: 3, chatCount: 2 })).toBe(
-        "You have 3 messages in 2 chats"
-      );
-      expect(provider.get("dashboard_status", "it", { msgCount: 1, chatCount: 1 })).toBe(
-        "Hai 1 messaggio in una chat"
-      );
-      expect(provider.get("dashboard_status", "it", { msgCount: 3, chatCount: 2 })).toBe(
-        "Hai 3 messaggi in 2 chat"
-      );
-    });
-
-    it("throws when a required numeric plural parameter is missing", () => {
-      expect(() => provider.get("dashboard_status", "en", { msgCount: 1 } as never)).toThrow(
-        "[i18n Formatting Error]"
-      );
-    });
-  });
-
-  describe("additional ICU variants", () => {
-    it("formats select arguments as strings", () => {
-      expect(provider.get("inbox_owner", "en", { gender: "female", name: "Ada" })).toBe(
-        "Ada owns her inbox"
-      );
-      expect(provider.get("inbox_owner", "en", { gender: "unknown", name: "Sam" })).toBe(
-        "Sam owns their inbox"
-      );
-    });
-
-    it("formats Italian select with a single other branch and the same params", () => {
-      expect(provider.get("inbox_owner", "it", { gender: "female", name: "Ada" })).toBe(
-        "Ada gestisce la propria casella"
-      );
-      expect(provider.get("inbox_owner", "it", { gender: "male", name: "Luca" })).toBe(
-        "Luca gestisce la propria casella"
-      );
-    });
-
-    it("formats selectordinal arguments as numbers", () => {
-      expect(provider.get("ranking_position", "en", { position: 1 })).toBe("You finished 1st");
-      expect(provider.get("ranking_position", "en", { position: 2 })).toBe("You finished 2nd");
-      expect(provider.get("ranking_position", "en", { position: 3 })).toBe("You finished 3rd");
-      expect(provider.get("ranking_position", "en", { position: 4 })).toBe("You finished 4th");
-    });
-
-    it("formats number, date, and time arguments", () => {
-      const amount = 1234.5;
-      const when = new Date("2026-07-01T13:30:00Z");
-
-      const expectedAmount = new Intl.NumberFormat("en", {
-        style: "currency",
-        currency: "EUR",
-      }).format(amount);
-      const expectedDate = new Intl.DateTimeFormat("en", {
-        dateStyle: "short",
-      }).format(when);
-      const expectedTime = new Intl.DateTimeFormat("en", {
-        timeStyle: "short",
-      }).format(when);
-
-      expect(provider.get("account_balance", "en", { amount })).toBe(`Balance: ${expectedAmount}`);
-      expect(
-        provider.get("appointment_summary", "en", {
-          dueDate: when,
-          startTime: when,
-        })
-      ).toBe(`Due ${expectedDate} at ${expectedTime}`);
-    });
-
-    it("formats ICU date and number skeletons (::yMMMMd, ::percent)", () => {
-      const when = new Date("2026-07-01T13:30:00Z");
-      const expectedLongDate = new Intl.DateTimeFormat("en", {
-        year: "numeric",
-        month: "long",
-        day: "numeric",
-      }).format(when);
-      const expectedPercent = new Intl.NumberFormat("en", {
-        style: "percent",
-      }).format(0.25);
-
-      expect(provider.get("invoice_due_long", "en", { dueDate: when })).toBe(
-        `Payment due on ${expectedLongDate}`
-      );
-      expect(provider.get("discount_rate", "en", { rate: 0.25 })).toBe(
-        `Save ${expectedPercent} today`
-      );
-    });
-  });
-
-  it("treats an empty string template as valid", () => {
-    expect(provider.get("empty_label", "en")).toBe("");
-  });
-
-  it("throws when the key or locale is missing", () => {
-    expect(() =>
-      provider.get("login_button", "fr" as unknown as LocaleOfSingle<TestSchema>)
-    ).toThrow('[i18n] Missing key or locale: "login_button" [fr] (fallback chain: fr)');
-    expect(() => provider.get("missing_key" as "login_button", "en")).toThrow(
-      '[i18n] Missing key or locale: "missing_key" [en] (fallback chain: en)'
-    );
-  });
-
-  it("throws on malformed ICU syntax", () => {
-    expect(() => provider.get("broken", "en", { name: "Ada" })).toThrow("[i18n ICU Syntax Error]");
-  });
-
-  it("throws when required parameters are missing", () => {
-    // @ts-expect-error
-    expect(() => provider.get("welcome", "en")).toThrow("[i18n Formatting Error]");
-  });
-
-  it("replaces the dictionary and invalidates cache on setAll", () => {
+  it("patches a preloaded key and invalidates cache", () => {
     const local = new IcuTranslationProviderSingle<TestSchema, TestParams>(dictionary);
-    expect(local.get("login_button", "en")).toBe("Login");
+    expect(local.toScope().t("login_button", "en")).toBe("Login");
 
-    local.setAll({
-      ...dictionary,
-      login_button: { en: "Sign in", it: "Entra" },
-    });
+    local.patchKey("login_button", "en", "Sign in");
 
-    expect(local.get("login_button", "en")).toBe("Sign in");
+    expect(local.toScope().t("login_button", "en")).toBe("Sign in");
+    expect(local.toScope().t("login_button", "it")).toBe("Accedi");
   });
 
-  it("merges locales per key with mergeAll without dropping existing locales", () => {
+  it("merges locales per key with applyLoadMergeSingle without dropping existing locales", () => {
     const local = new IcuTranslationProviderSingle<TestSchema, TestParams>({
       ...dictionary,
       // @ts-expect-error missing locale
@@ -244,30 +102,41 @@ describe("IcuTranslationProviderSingle", () => {
       },
     });
 
-    local.mergeAll({
-      // @ts-expect-error missing locale
+    local.applyLoadMergeSingle({
       welcome: {
+        // @ts-expect-error adding locale via merge
         it: "Benvenuto {name}!",
       },
     });
 
-    expect(local.get("welcome", "en", { name: "Ada" })).toBe("Welcome Ada!");
-    expect(local.get("welcome", "it", { name: "Ada" })).toBe("Benvenuto Ada!");
-    expect(local.get("login_button", "en")).toBe("Login");
+    const view = local.toScope();
+    expect(view.t("welcome", "en", { name: "Ada" })).toBe("Welcome Ada!");
+    expect(view.t("welcome", "it", { name: "Ada" })).toBe("Benvenuto Ada!");
+    expect(view.t("login_button", "en")).toBe("Login");
+  });
+
+  it("throws when patching a key that was not preloaded", () => {
+    const local = new IcuTranslationProviderSingle<TestSchema, TestParams>({
+      login_button: { en: "Login" },
+    } as TestSchema);
+
+    expect(() => local.patchKey("login_button", "it", "Accedi")).toThrow(
+      "[i18n] Key not preloaded: login_button (it)"
+    );
   });
 
   it("returns a deep-frozen snapshot from getAll", () => {
-    expect(provider.getAll()).toEqual(dictionary);
-    expect(provider.getAll()).not.toBe(dictionary);
-    expect(Object.isFrozen(provider.getAll())).toBe(true);
+    expect(engine.getAll()).toEqual(dictionary);
+    expect(engine.getAll()).not.toBe(dictionary);
+    expect(Object.isFrozen(engine.getAll())).toBe(true);
   });
 
-  it("does not mutate the provider when getAll snapshot is modified", () => {
-    const snapshot = provider.getAll();
+  it("does not mutate the engine when getAll snapshot is modified", () => {
+    const snapshot = engine.getAll();
     expect(() => {
       snapshot.welcome.en = "Hacked";
     }).toThrow(TypeError);
-    expect(provider.get("welcome", "en", { name: "Ada" })).toBe("Welcome Ada!");
+    expect(engine.toScope().t("welcome", "en", { name: "Ada" })).toBe("Welcome Ada!");
   });
 
   it("does not reflect external dictionary mutations after construction", () => {
@@ -292,91 +161,10 @@ describe("IcuTranslationProviderSingle", () => {
     };
     const local = new IcuTranslationProviderSingle<TestSchema, TestParams>(external);
     external.login_button.en = "Sign in";
-    expect(local.get("login_button", "en")).toBe("Login");
-  });
-
-  describe("forLocale", () => {
-    it("binds a locale so get() no longer requires it", () => {
-      const en = provider.forLocale("en");
-
-      expect(en.locale).toBe("en");
-      expect(en.get("login_button")).toBe("Login");
-      expect(en.get("welcome", { name: "Ada" })).toBe("Welcome Ada!");
-    });
-
-    it("uses the parent provider cache and fallback rules", () => {
-      const fallbackMap = {
-        en: null,
-        "de-CH": "en",
-      } as const;
-      const fallbackProvider = new IcuTranslationProviderSingle<
-        TestSchema,
-        TestParams,
-        keyof typeof fallbackMap | LocaleOfSingle<TestSchema>,
-        typeof fallbackMap
-      >(dictionary, { localeFallback: fallbackMap });
-      const deCh = fallbackProvider.forLocale("de-CH");
-
-      expect(deCh.get("login_button")).toBe("Login");
-    });
+    expect(local.toScope().t("login_button", "en")).toBe("Login");
   });
 
   describe("locale fallback", () => {
-    const fallbackMap = {
-      en: null,
-      "de-DE": "en",
-      "de-CH": "de-DE",
-      it: "en",
-    } as const;
-
-    const fallbackProvider = new IcuTranslationProviderSingle<
-      TestSchema,
-      TestParams,
-      keyof typeof fallbackMap | LocaleOfSingle<TestSchema>,
-      typeof fallbackMap
-    >(dictionary, { localeFallback: fallbackMap });
-
-    it("resolves a locale through the fallback chain", () => {
-      expect(fallbackProvider.get("login_button", "de-CH")).toBe("Login");
-    });
-
-    it("uses an intermediate locale template when available", () => {
-      const withGerman = new IcuTranslationProviderSingle<
-        TestSchema & {
-          login_button: { en: string; it: string; "de-DE": string };
-        },
-        TestParams,
-        keyof typeof fallbackMap | LocaleOfSingle<TestSchema>,
-        typeof fallbackMap
-      >(
-        {
-          ...dictionary,
-          login_button: { en: "Login", it: "Accedi", "de-DE": "Anmelden" },
-        },
-        { localeFallback: fallbackMap }
-      );
-
-      expect(withGerman.get("login_button", "de-CH")).toBe("Anmelden");
-    });
-
-    it("throws when the fallback chain cannot resolve a template", () => {
-      const unresolvedFallback = {
-        en: null,
-        "de-CH": "fr",
-        fr: null,
-      } as const;
-      const unresolvedProvider = new IcuTranslationProviderSingle<
-        TestSchema,
-        TestParams,
-        keyof typeof unresolvedFallback | LocaleOfSingle<TestSchema>,
-        typeof unresolvedFallback
-      >(dictionary, { localeFallback: unresolvedFallback });
-
-      expect(() => unresolvedProvider.get("login_button", "de-CH")).toThrow(
-        '[i18n] Missing key or locale: "login_button" [de-CH] (fallback chain: de-CH → fr)'
-      );
-    });
-
     it("rejects circular fallback maps at construction", () => {
       expect(
         () =>
@@ -386,71 +174,4 @@ describe("IcuTranslationProviderSingle", () => {
       ).toThrow("[i18n] Circular locale fallback detected");
     });
   });
-
-  describe("onMissing", () => {
-    it('throws on missing translations with onMissing: "throw" (explicit default)', () => {
-      const local = new IcuTranslationProviderSingle<TestSchema, TestParams>(dictionary, {
-        onMissing: "throw",
-      });
-      expect(() => local.get("missing_key" as "login_button", "en")).toThrow(
-        '[i18n] Missing key or locale: "missing_key" [en] (fallback chain: en)'
-      );
-    });
-
-    it('returns the key itself with onMissing: "key"', () => {
-      const local = new IcuTranslationProviderSingle<TestSchema, TestParams>(dictionary, {
-        onMissing: "key",
-      });
-      expect(local.get("missing_key" as "login_button", "en")).toBe("missing_key");
-    });
-
-    it("calls a custom handler with the missing-translation context", () => {
-      const contexts: unknown[] = [];
-      const local = new IcuTranslationProviderSingle<TestSchema, TestParams>(dictionary, {
-        onMissing: (context) => {
-          contexts.push(context);
-          return `<missing:${context.key}>`;
-        },
-      });
-
-      expect(local.get("missing_key" as "login_button", "en")).toBe("<missing:missing_key>");
-      expect(contexts).toEqual([{ key: "missing_key", locale: "en", fallbackChain: "en" }]);
-    });
-
-    it("includes the walked fallback chain in the handler context", () => {
-      const fallbackMap = { en: null, "de-CH": "fr", fr: null } as const;
-      const contexts: { fallbackChain: string }[] = [];
-      const local = new IcuTranslationProviderSingle<
-        TestSchema,
-        TestParams,
-        keyof typeof fallbackMap | LocaleOfSingle<TestSchema>,
-        typeof fallbackMap
-      >(dictionary, {
-        localeFallback: fallbackMap,
-        onMissing: (context) => {
-          contexts.push(context);
-          return context.key;
-        },
-      });
-
-      expect(local.get("login_button", "de-CH")).toBe("login_button");
-      expect(contexts[0]?.fallbackChain).toBe("de-CH → fr");
-    });
-
-    it("still throws ICU syntax and formatting errors with a lenient onMissing", () => {
-      const local = new IcuTranslationProviderSingle<TestSchema, TestParams>(dictionary, {
-        onMissing: "key",
-      });
-      expect(() => local.get("broken", "en", { name: "Ada" })).toThrow("[i18n ICU Syntax Error]");
-      // @ts-expect-error
-      expect(() => local.get("welcome", "en")).toThrow("[i18n Formatting Error]");
-    });
-
-    it("applies onMissing through forLocale wrappers", () => {
-      const local = new IcuTranslationProviderSingle<TestSchema, TestParams>(dictionary, {
-        onMissing: "key",
-      });
-      expect(local.forLocale("en").get("missing_key" as "login_button")).toBe("missing_key");
-    });
-  });
 });