@xndrjs/i18n 0.6.0 → 0.7.0-alpha.0

package/src/IcuTranslationProviderMulti.test.ts

@@ -1,6 +1,5 @@
 import { describe, expect, it } from "vitest";
 import { IcuTranslationProviderMulti } from "./IcuTranslationProviderMulti.js";
-import type { LocaleOfMulti } from "./types.js";
 
 type TestSchema = {
   default: {
@@ -69,269 +68,170 @@ const dictionary: TestSchema = {
 };
 
 describe("IcuTranslationProviderMulti", () => {
-  const provider = new IcuTranslationProviderMulti<TestSchema, TestParams>(dictionary);
+  const engine = new IcuTranslationProviderMulti<TestSchema, TestParams>(dictionary);
 
-  it("resolves translations by namespace and key", () => {
-    expect(provider.get("default", "login_button", "it")).toBe("Accedi");
-    expect(provider.get("default", "welcome", "en", { name: "Ada" })).toBe("Welcome Ada!");
-  });
+  it("tracks namespaces via dictionary keys", () => {
+    const partial = new IcuTranslationProviderMulti<TestSchema, TestParams>({
+      default: dictionary.default,
+    });
 
-  it("formats ICU plurals with multiple parameters", () => {
-    expect(provider.get("billing", "invoice_summary", "en", { count: 1, name: "Ada" })).toBe(
-      "You have 1 invoice for Ada"
-    );
-    expect(provider.get("billing", "invoice_summary", "en", { count: 3, name: "Ada" })).toBe(
-      "You have 3 invoices for Ada"
-    );
-    expect(provider.get("billing", "invoice_summary", "it", { count: 1, name: "Ada" })).toBe(
-      "Hai 1 fattura per Ada"
-    );
-    expect(provider.get("billing", "invoice_summary", "it", { count: 3, name: "Ada" })).toBe(
-      "Hai 3 fatture per Ada"
-    );
+    expect("default" in partial.getAll()).toBe(true);
+    expect("billing" in partial.getAll()).toBe(false);
   });
 
-  it("formats nested numeric plurals with double-brace references", () => {
-    expect(provider.get("default", "dashboard_status", "en", { msgCount: 1, chatCount: 1 })).toBe(
-      "You have 1 message in one chat"
-    );
-    expect(provider.get("default", "dashboard_status", "en", { msgCount: 3, chatCount: 2 })).toBe(
-      "You have 3 messages in 2 chats"
-    );
-    expect(provider.get("default", "dashboard_status", "it", { msgCount: 1, chatCount: 1 })).toBe(
-      "Hai 1 messaggio in una chat"
-    );
-    expect(provider.get("default", "dashboard_status", "it", { msgCount: 3, chatCount: 2 })).toBe(
-      "Hai 3 messaggi in 2 chat"
-    );
-  });
+  it("supports partial initialization", () => {
+    const partial = new IcuTranslationProviderMulti<TestSchema, TestParams>({
+      default: dictionary.default,
+    });
 
-  it("formats select and selectordinal ICU variants", () => {
-    expect(provider.get("default", "inbox_owner", "en", { gender: "male", name: "Linus" })).toBe(
-      "Linus owns his inbox"
-    );
-    expect(provider.get("default", "ranking_position", "en", { position: 3 })).toBe(
-      "You finished 3rd"
+    expect(partial.toScope({ namespaces: ["default"] }).t("default", "login_button", "en")).toBe(
+      "Login"
     );
   });
 
-  it("formats number, date, and time ICU variants", () => {
-    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);
+  it("patches a preloaded key and invalidates its cache", () => {
+    const local = new IcuTranslationProviderMulti<TestSchema, TestParams>(dictionary);
+    const view = () => local.toScope({ namespaces: ["default", "billing"] });
 
-    expect(provider.get("billing", "account_balance", "en", { amount })).toBe(
-      `Balance: ${expectedAmount}`
+    expect(view().t("billing", "invoice_summary", "en", { count: 2, name: "Bob" })).toBe(
+      "You have 2 invoices for Bob"
     );
-    expect(
-      provider.get("billing", "appointment_summary", "en", {
-        dueDate: when,
-        startTime: when,
-      })
-    ).toBe(`Due ${expectedDate} at ${expectedTime}`);
-  });
 
-  it("treats an empty string template as valid", () => {
-    expect(provider.get("billing", "empty_label", "en")).toBe("");
+    local.patchKeyMulti(
+      "billing",
+      "invoice_summary",
+      "en",
+      "{count, plural, one {1 bill} other {{count} bills}} for {name}"
+    );
+
+    expect(view().t("billing", "invoice_summary", "en", { count: 2, name: "Bob" })).toBe(
+      "2 bills for Bob"
+    );
+    expect(view().t("default", "login_button", "en")).toBe("Login");
   });
 
-  it("tracks loaded namespaces with hasNamespace", () => {
+  it("adds namespace to dictionary with applyLoadMergeNamespace", () => {
     const partial = new IcuTranslationProviderMulti<TestSchema, TestParams>({
       default: dictionary.default,
     });
+    expect("billing" in partial.getAll()).toBe(false);
 
-    expect(partial.hasNamespace("default")).toBe(true);
-    expect(partial.hasNamespace("billing")).toBe(false);
+    partial.applyLoadMergeNamespace("billing", dictionary.billing);
+    expect("billing" in partial.getAll()).toBe(true);
   });
 
-  it("throws when getting from an unloaded namespace", () => {
-    const partial = new IcuTranslationProviderMulti<TestSchema, TestParams>({
-      default: dictionary.default,
-    });
+  it("adds namespace to dictionary on first applyLoadMergeNamespace", () => {
+    const partial = new IcuTranslationProviderMulti<TestSchema, TestParams>({});
+    expect("billing" in partial.getAll()).toBe(false);
 
-    expect(() =>
-      partial.get("billing", "invoice_summary", "en", { count: 1, name: "Ada" })
-    ).toThrow(
-      '[i18n] Namespace not loaded: "billing". Register it with setNamespace() before calling .get().'
-    );
+    partial.applyLoadMergeNamespace("billing", dictionary.billing);
+    expect("billing" in partial.getAll()).toBe(true);
   });
 
-  it("supports partial initialization", () => {
-    const partial = new IcuTranslationProviderMulti<TestSchema, TestParams>({
-      default: dictionary.default,
+  it("accumulates a locale via applyLoadMergeNamespace when the namespace already exists", () => {
+    const local = new IcuTranslationProviderMulti<TestSchema, TestParams>({
+      billing: {
+        invoice_summary: {
+          en: "You have {count, plural, one {1 invoice} other {{count} invoices}} for {name}",
+        },
+      },
     });
+    const view = () => local.toScope({ namespaces: ["billing"] });
 
-    expect(partial.get("default", "login_button", "en")).toBe("Login");
-  });
-
-  it("throws when namespace, key, or locale is missing", () => {
-    expect(() =>
-      provider.get("default", "login_button", "fr" as unknown as LocaleOfMulti<TestSchema>)
-    ).toThrow(
-      '[i18n] Missing key or locale: namespace "default", key "login_button" [fr] (fallback chain: fr)'
-    );
-    expect(() => provider.get("billing", "login_button" as "empty_label", "en")).toThrow(
-      '[i18n] Missing key or locale: namespace "billing", key "login_button" [en] (fallback chain: en)'
+    expect("billing" in local.getAll()).toBe(true);
+    expect(view().t("billing", "invoice_summary", "en", { count: 1, name: "Ada" })).toBe(
+      "You have 1 invoice for Ada"
     );
-  });
 
-  it("throws when required parameters are missing", () => {
-    expect(() => provider.get("billing", "invoice_summary", "en", { count: 1 } as never)).toThrow(
-      "[i18n Formatting Error]"
-    );
-  });
+    local.applyLoadMergeNamespace("billing", {
+      invoice_summary: {
+        it: "Hai {count, plural, one {1 fattura} other {{count} fatture}} per {name}",
+      },
+    });
 
-  it("patches a single namespace with setNamespace and invalidates its cache", () => {
-    const local = new IcuTranslationProviderMulti<TestSchema, TestParams>(dictionary);
-    expect(local.get("billing", "invoice_summary", "en", { count: 2, name: "Bob" })).toBe(
+    expect(view().t("billing", "invoice_summary", "en", { count: 2, name: "Bob" })).toBe(
       "You have 2 invoices for Bob"
     );
+    expect(view().t("billing", "invoice_summary", "it", { count: 2, name: "Bob" })).toBe(
+      "Hai 2 fatture per Bob"
+    );
+  });
+
+  it("merges locales per key with applyLoadMergeNamespace without dropping existing locales", () => {
+    const local = new IcuTranslationProviderMulti<TestSchema, TestParams>({
+      billing: {
+        invoice_summary: {
+          en: "You have {count, plural, one {1 invoice} other {{count} invoices}} for {name}",
+        },
+      },
+    });
+    const view = () => local.toScope({ namespaces: ["billing"] });
 
-    local.setNamespace("billing", {
-      ...dictionary.billing,
+    local.applyLoadMergeNamespace("billing", {
       invoice_summary: {
-        en: "{count, plural, one {1 bill} other {{count} bills}}",
-        it: dictionary.billing.invoice_summary.it,
+        it: "Hai {count, plural, one {1 fattura} other {{count} fatture}} per {name}",
       },
     });
 
-    expect(local.get("billing", "invoice_summary", "en", { count: 2, name: "Bob" })).toBe(
-      "2 bills"
+    expect(view().t("billing", "invoice_summary", "en", { count: 2, name: "Bob" })).toBe(
+      "You have 2 invoices for Bob"
+    );
+    expect(view().t("billing", "invoice_summary", "it", { count: 2, name: "Bob" })).toBe(
+      "Hai 2 fatture per Bob"
     );
-    expect(local.get("default", "login_button", "en")).toBe("Login");
   });
 
-  it("replaces the full dictionary on setAll", () => {
+  it("patches a preloaded default namespace key", () => {
     const local = new IcuTranslationProviderMulti<TestSchema, TestParams>(dictionary);
 
-    local.setAll({
-      ...dictionary,
-      default: {
-        ...dictionary.default,
-        login_button: { en: "Sign in", it: "Entra" },
+    local.patchKeyMulti("default", "login_button", "en", "Sign in");
+
+    expect(local.toScope({ namespaces: ["default"] }).t("default", "login_button", "en")).toBe(
+      "Sign in"
+    );
+  });
+
+  it("merges namespaces with applyLoadMergeAll without dropping existing locales", () => {
+    const local = new IcuTranslationProviderMulti<TestSchema, TestParams>({
+      billing: {
+        invoice_summary: {
+          en: "You have {count, plural, one {1 invoice} other {{count} invoices}} for {name}",
+        },
+      },
+    });
+    const view = () => local.toScope({ namespaces: ["default", "billing"] });
+
+    local.applyLoadMergeAll({
+      billing: {
+        invoice_summary: {
+          it: "Hai {count, plural, one {1 fattura} other {{count} fatture}} per {name}",
+        },
       },
+      default: dictionary.default,
     });
 
-    expect(local.get("default", "login_button", "en")).toBe("Sign in");
+    expect(view().t("billing", "invoice_summary", "en", { count: 2, name: "Bob" })).toBe(
+      "You have 2 invoices for Bob"
+    );
+    expect(view().t("billing", "invoice_summary", "it", { count: 2, name: "Bob" })).toBe(
+      "Hai 2 fatture per Bob"
+    );
+    expect(view().t("default", "login_button", "en")).toBe("Login");
   });
 
   it("returns a deep-frozen snapshot from getAll", () => {
-    expect(provider.getAll()).toEqual(dictionary);
-    expect(provider.getAll()).not.toBe(dictionary);
-    expect(Object.isFrozen(provider.getAll().default)).toBe(true);
+    expect(engine.getAll()).toEqual(dictionary);
+    expect(engine.getAll()).not.toBe(dictionary);
+    expect(Object.isFrozen(engine.getAll().default)).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.default.login_button.en = "Hacked";
     }).toThrow(TypeError);
-    expect(provider.get("default", "login_button", "en")).toBe("Login");
-  });
-
-  describe("forLocale", () => {
-    it("binds a locale so get() no longer requires it", () => {
-      const it = provider.forLocale("it");
-
-      expect(it.locale).toBe("it");
-      expect(it.get("default", "login_button")).toBe("Accedi");
-      expect(it.get("billing", "invoice_summary", { count: 2, name: "Ada" })).toBe(
-        "Hai 2 fatture per Ada"
-      );
-    });
-  });
-
-  describe("locale fallback", () => {
-    const fallbackMap = {
-      en: null,
-      "de-DE": "en",
-      "de-CH": "de-DE",
-      it: "en",
-    } as const;
-
-    const fallbackProvider = new IcuTranslationProviderMulti<
-      TestSchema,
-      TestParams,
-      keyof typeof fallbackMap | LocaleOfMulti<TestSchema>,
-      typeof fallbackMap
-    >(dictionary, { localeFallback: fallbackMap });
-
-    it("resolves a locale through the fallback chain", () => {
-      expect(fallbackProvider.get("default", "login_button", "de-CH")).toBe("Login");
-    });
-
-    it("throws when the fallback chain cannot resolve a template", () => {
-      const unresolvedFallback = {
-        en: null,
-        "de-CH": "fr",
-        fr: null,
-      } as const;
-      const unresolvedProvider = new IcuTranslationProviderMulti<
-        TestSchema,
-        TestParams,
-        keyof typeof unresolvedFallback | LocaleOfMulti<TestSchema>,
-        typeof unresolvedFallback
-      >(dictionary, { localeFallback: unresolvedFallback });
-
-      expect(() => unresolvedProvider.get("default", "login_button", "de-CH")).toThrow(
-        '[i18n] Missing key or locale: namespace "default", key "login_button" [de-CH] (fallback chain: de-CH → fr)'
-      );
-    });
-  });
-
-  describe("onMissing", () => {
-    it('returns "namespace.key" with onMissing: "key"', () => {
-      const local = new IcuTranslationProviderMulti<TestSchema, TestParams>(dictionary, {
-        onMissing: "key",
-      });
-      expect(local.get("default", "missing_key" as "login_button", "en")).toBe(
-        "default.missing_key"
-      );
-    });
-
-    it("calls a custom handler with namespace, key, locale, and fallback chain", () => {
-      const contexts: unknown[] = [];
-      const local = new IcuTranslationProviderMulti<TestSchema, TestParams>(dictionary, {
-        onMissing: (context) => {
-          contexts.push(context);
-          return `<missing:${context.namespace}/${context.key}>`;
-        },
-      });
-
-      expect(local.get("default", "missing_key" as "login_button", "en")).toBe(
-        "<missing:default/missing_key>"
-      );
-      expect(contexts).toEqual([
-        { namespace: "default", key: "missing_key", locale: "en", fallbackChain: "en" },
-      ]);
-    });
-
-    it("still throws for unloaded namespaces with a lenient onMissing", () => {
-      const local = new IcuTranslationProviderMulti<TestSchema, TestParams>(
-        { default: dictionary.default },
-        { onMissing: "key" }
-      );
-      expect(() => local.get("billing", "account_balance", "en", { amount: 1 })).toThrow(
-        '[i18n] Namespace not loaded: "billing"'
-      );
-    });
-
-    it("applies onMissing through forLocale wrappers", () => {
-      const local = new IcuTranslationProviderMulti<TestSchema, TestParams>(dictionary, {
-        onMissing: "key",
-      });
-      expect(local.forLocale("en").get("default", "missing_key" as "login_button")).toBe(
-        "default.missing_key"
-      );
-    });
+    expect(engine.toScope({ namespaces: ["default"] }).t("default", "login_button", "en")).toBe(
+      "Login"
+    );
   });
 });

package/src/IcuTranslationProviderMulti.ts

@@ -1,5 +1,13 @@
 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 {
   IcuTranslationProviderOptions,
@@ -8,83 +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;
-  setNamespace<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;
@@ -92,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];
@@ -141,35 +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);
   }
 
-  setNamespace<NS extends keyof Schema>(namespace: NS, values: Schema[NS]): void {
+  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);
+
     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(incomingLocales)) {
+        delete this.compiledCache[locale]?.[namespace as string]?.[key];
+      }
+    }
+  }
 
-    for (const locale of Object.keys(this.compiledCache)) {
-      delete this.compiledCache[locale]?.[namespace as string];
+  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);
+      }
     }
   }
+
+  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
+      >
+    );
+  }
 }