@xndrjs/i18n 0.6.1 → 0.7.0

package/src/IcuTranslationProviderSingle.ts

@@ -1,5 +1,12 @@
 import { cloneAndFreeze } from "./deep-freeze.js";
+import { BuilderLoadRegistry, SINGLE_BUILDER_RESOURCE } from "./builder-load-registry.js";
+import type { I18nEngineSingle } from "./engine.js";
 import { resolveAndFormat } from "./format-core.js";
+import {
+  assertPatchKeySingle,
+  recordPreloadedKeysSingle,
+  seedPreloadedKeysSingle,
+} from "./patch-key.js";
 import { mergeNamespaceLocalesCore } from "./project-locales.js";
 import { validateLocaleFallback } from "./resolve-locale.js";
 import type {
@@ -9,77 +16,28 @@ import type {
   LocaleOfSingle,
   OnMissingTranslation,
   SingleCompiledCache,
+  PartialKeyDictionary,
 } from "./types.js";
-
-export interface TranslationProviderSingleForLocale<
-  Schema extends KeyDictionary,
-  Params extends { [K in keyof Schema]: unknown },
-  Locale extends string,
-> {
-  readonly locale: Locale;
-  get<K extends keyof Schema & string>(
-    key: K,
-    ...params: Params[K] extends never ? [] : [params: Params[K]]
-  ): string;
-}
-
-export interface TranslationProviderSingle<
-  Schema extends KeyDictionary,
-  Params extends { [K in keyof Schema]: unknown },
-  RequestLocales extends string = LocaleOfSingle<Schema>,
-> {
-  get<K extends keyof Schema & string>(
-    key: K,
-    locale: RequestLocales,
-    ...params: Params[K] extends never ? [] : [params: Params[K]]
-  ): string;
-  forLocale<Locale extends RequestLocales>(
-    locale: Locale
-  ): TranslationProviderSingleForLocale<Schema, Params, Locale>;
-  getAll(): Schema;
-  setAll(values: Schema): void;
-  mergeAll(values: Partial<Schema>): void;
-}
-
-export class IcuTranslationProviderSingleForLocale<
-  Schema extends KeyDictionary,
-  Params extends { [K in keyof Schema]: unknown },
-  RequestLocales extends string,
-  Locale extends RequestLocales,
-  Fallback extends LocaleFallbackMap | undefined,
-> implements TranslationProviderSingleForLocale<Schema, Params, Locale> {
-  constructor(
-    private readonly provider: IcuTranslationProviderSingle<
-      Schema,
-      Params,
-      RequestLocales,
-      Fallback
-    >,
-    readonly locale: Locale
-  ) {}
-
-  get<K extends keyof Schema & string>(
-    key: K,
-    ...args: Params[K] extends never ? [] : [params: Params[K]]
-  ): string {
-    const params = args[0] as Record<string, unknown> | undefined;
-    return this.provider.getWithLocale(String(key), this.locale, params);
-  }
-}
+import { I18nScopeSingleForLocaleImpl, I18nScopeSingleImpl } from "./scope-single.js";
 
 export class IcuTranslationProviderSingle<
   Schema extends KeyDictionary,
   Params extends { [K in keyof Schema]: unknown },
   RequestLocales extends string = LocaleOfSingle<Schema>,
   Fallback extends LocaleFallbackMap | undefined = undefined,
-> implements TranslationProviderSingle<Schema, Params, RequestLocales> {
+> implements I18nEngineSingle<Schema, Params, RequestLocales> {
+  readonly __i18nEngineMode = "single" as const;
+
   private dictionary: Schema;
   private compiledCache: SingleCompiledCache = {};
+  private readonly preloadedKeys = new Set<string>();
+  private readonly builderLoadRegistry = new BuilderLoadRegistry();
   private readonly localeFallback?: Fallback;
   private readonly onMissing: OnMissingTranslation;
 
   constructor(dictionary: Schema, options?: IcuTranslationProviderOptions<Fallback>) {
     this.dictionary = structuredClone(dictionary);
+    seedPreloadedKeysSingle(this.dictionary, this.preloadedKeys);
     if (options?.localeFallback) {
       validateLocaleFallback(options.localeFallback);
       this.localeFallback = options.localeFallback;
@@ -87,15 +45,6 @@ export class IcuTranslationProviderSingle<
     this.onMissing = options?.onMissing ?? "throw";
   }
 
-  get<K extends keyof Schema & string>(
-    key: K,
-    locale: RequestLocales,
-    ...args: Params[K] extends never ? [] : [params: Params[K]]
-  ): string {
-    const params = args[0] as Record<string, unknown> | undefined;
-    return this.getWithLocale(String(key), locale, params);
-  }
-
   getWithLocale(key: string, locale: string, params?: Record<string, unknown>): string {
     return resolveAndFormat({
       localeByKey: this.dictionary[key],
@@ -116,23 +65,32 @@ export class IcuTranslationProviderSingle<
     });
   }
 
-  forLocale<Locale extends RequestLocales>(
-    locale: Locale
-  ): IcuTranslationProviderSingleForLocale<Schema, Params, RequestLocales, Locale, Fallback> {
-    return new IcuTranslationProviderSingleForLocale(this, locale);
+  toScope(): I18nScopeSingleImpl<Schema, Params, RequestLocales, Fallback>;
+  toScope<Locale extends RequestLocales>(options: {
+    locale: Locale;
+  }): I18nScopeSingleForLocaleImpl<Schema, Params, RequestLocales, Locale, Fallback>;
+  toScope<Locale extends RequestLocales>(options?: { locale?: Locale }) {
+    if (options?.locale !== undefined) {
+      return new I18nScopeSingleForLocaleImpl(this, options.locale);
+    }
+    return new I18nScopeSingleImpl(this);
   }
 
   getAll(): Schema {
     return cloneAndFreeze(this.dictionary);
   }
 
-  setAll(values: Schema): void {
-    this.dictionary = structuredClone(values);
-    this.compiledCache = {};
+  hasBuilderResourceLoaded(partition: string | undefined): boolean {
+    return this.builderLoadRegistry.has(SINGLE_BUILDER_RESOURCE, partition);
+  }
+
+  markBuilderResourceLoaded(partition: string | undefined): void {
+    this.builderLoadRegistry.mark(SINGLE_BUILDER_RESOURCE, partition);
   }
 
-  mergeAll(values: Partial<Schema>): void {
-    this.dictionary = mergeNamespaceLocalesCore(this.dictionary, values as Schema);
+  applyLoadMergeSingle(values: PartialKeyDictionary<Schema, RequestLocales>): void {
+    this.dictionary = mergeNamespaceLocalesCore(this.dictionary, values);
+    recordPreloadedKeysSingle(values, this.preloadedKeys);
 
     for (const [key, incomingLocales] of Object.entries(values)) {
       if (incomingLocales === undefined || typeof incomingLocales !== "object") {
@@ -144,4 +102,13 @@ export class IcuTranslationProviderSingle<
       }
     }
   }
+
+  patchKey(key: string, locale: string, template: string): void {
+    assertPatchKeySingle(key, locale, template, this.preloadedKeys, this.dictionary[key]);
+
+    this.dictionary = mergeNamespaceLocalesCore(this.dictionary, {
+      [key]: { [locale]: template },
+    } as PartialKeyDictionary<Schema, RequestLocales>);
+    delete this.compiledCache[locale]?.[key];
+  }
 }

package/src/builder-load-registry.ts

@@ -0,0 +1,18 @@
+/** Stable key for a lazy-loaded builder resource (namespace + locale or delivery area). */
+export function formatBuilderResourceKey(namespace: string, partition: string | undefined): string {
+  return `${namespace}\0${partition ?? ""}`;
+}
+
+export const SINGLE_BUILDER_RESOURCE = "__dictionary__";
+
+export class BuilderLoadRegistry {
+  private readonly loaded = new Set<string>();
+
+  has(namespace: string, partition: string | undefined): boolean {
+    return this.loaded.has(formatBuilderResourceKey(namespace, partition));
+  }
+
+  mark(namespace: string, partition: string | undefined): void {
+    this.loaded.add(formatBuilderResourceKey(namespace, partition));
+  }
+}

package/src/builder-loaders.ts

@@ -0,0 +1,18 @@
+/** Canonical lazy loader — no locale or delivery-area partition. */
+export type CanonicalLoader<T> = () => Promise<T> | T;
+
+/** Split-by-locale or custom-area loader — partition key is locale or area name. */
+export type PartitionedLoader<T> = (partition: string) => Promise<T> | T;
+
+export type NamespaceLoader<T> = CanonicalLoader<T> | PartitionedLoader<T>;
+
+export async function invokeNamespaceLoader<T>(
+  loader: NamespaceLoader<T>,
+  partition: string | undefined
+): Promise<T> {
+  if (partition === undefined) {
+    return await (loader as CanonicalLoader<T>)();
+  }
+
+  return await (loader as PartitionedLoader<T>)(partition);
+}

package/src/builder-multi.ts

@@ -0,0 +1,481 @@
+import { invokeNamespaceLoader, type NamespaceLoader } from "./builder-loaders.js";
+import type { DeliveryArtifactsMap, LocalesForDeliveryAreaOrAll } from "./builder-types.js";
+import type { I18nEngineMultiImpl } from "./engine.js";
+import type { LocaleOfMulti, MultiDictionary, PartialKeyDictionary } from "./types.js";
+import type { I18nScopeMulti, I18nScopeMultiForLocale } from "./scope-multi.js";
+import type { MultiParams, ParamsForNamespaces, SchemaForNamespaces } from "./scope-types.js";
+
+export type I18nBuilderMultiOptions<
+  Schema extends MultiDictionary,
+  RequestLocales extends string = LocaleOfMulti<Schema>,
+> = {
+  namespaceLoaders?: {
+    [NS in keyof Schema & string]?: NamespaceLoader<
+      PartialKeyDictionary<Schema[NS], RequestLocales> | Schema[NS]
+    >;
+  };
+};
+
+/** Non-empty namespace list — required before partition or load. */
+type NonEmptyNamespaces<NS extends readonly string[]> = NS extends readonly [] ? never : NS;
+
+type MultiBuilderState<
+  Schema extends MultiDictionary,
+  RequestLocales extends string = LocaleOfMulti<Schema>,
+  NsList extends readonly (keyof Schema & string)[] = readonly (keyof Schema & string)[],
+> = {
+  namespaces: NsList;
+  locale?: RequestLocales;
+  deliveryArea?: string;
+};
+
+/** Builder returned by `createI18n({})` — only `withNamespaces` until namespaces are selected. */
+export interface I18nBuilderMultiInitial<
+  Schema extends MultiDictionary,
+  Params extends MultiParams<Schema>,
+  RequestLocales extends string = LocaleOfMulti<Schema>,
+  ActiveLocales extends RequestLocales = RequestLocales,
+  DeliveryArea extends string = never,
+  DeliveryArtifacts extends DeliveryArtifactsMap<RequestLocales, DeliveryArea> =
+    DeliveryArtifactsMap<RequestLocales, DeliveryArea>,
+> {
+  withNamespaces<const NS extends readonly (keyof Schema & string)[]>(
+    namespaces: NonEmptyNamespaces<NS>
+  ): I18nBuilderMultiReady<
+    Schema,
+    Params,
+    RequestLocales,
+    ActiveLocales,
+    NS,
+    DeliveryArea,
+    DeliveryArtifacts
+  >;
+}
+
+/** Builder after `withNamespaces([...])` — partition selection and `load()` are available. */
+export interface I18nBuilderMultiReady<
+  Schema extends MultiDictionary,
+  Params extends MultiParams<Schema>,
+  RequestLocales extends string = LocaleOfMulti<Schema>,
+  ActiveLocales extends RequestLocales = RequestLocales,
+  NsList extends readonly (keyof Schema & string)[] = readonly (keyof Schema & string)[],
+  DeliveryArea extends string = never,
+  DeliveryArtifacts extends DeliveryArtifactsMap<RequestLocales, DeliveryArea> =
+    DeliveryArtifactsMap<RequestLocales, DeliveryArea>,
+> {
+  withNamespaces<const NS extends readonly (keyof Schema & string)[]>(
+    namespaces: NonEmptyNamespaces<NS>
+  ): I18nBuilderMultiReady<
+    Schema,
+    Params,
+    RequestLocales,
+    ActiveLocales,
+    NS,
+    DeliveryArea,
+    DeliveryArtifacts
+  >;
+
+  withLocale<Locale extends ActiveLocales>(
+    locale: Locale
+  ): I18nBuilderMultiForLocale<Schema, Params, RequestLocales, ActiveLocales, NsList, Locale>;
+
+  withDeliveryArea<Area extends DeliveryArea>(
+    area: Area
+  ): I18nBuilderMultiPartitioned<
+    Schema,
+    Params,
+    RequestLocales,
+    LocalesForDeliveryAreaOrAll<RequestLocales, DeliveryArea, DeliveryArtifacts, Area>,
+    NsList,
+    DeliveryArea,
+    DeliveryArtifacts
+  >;
+
+  load(): Promise<
+    I18nScopeMulti<
+      SchemaForNamespaces<Schema, NsList>,
+      ParamsForNamespaces<Schema, Params, NsList>,
+      ActiveLocales
+    >
+  >;
+}
+
+/** @deprecated Alias for {@link I18nBuilderMultiInitial} — the multi builder before `withNamespaces`. */
+export type I18nBuilderMulti<
+  Schema extends MultiDictionary,
+  Params extends MultiParams<Schema>,
+  RequestLocales extends string = LocaleOfMulti<Schema>,
+  ActiveLocales extends RequestLocales = RequestLocales,
+  NsList extends readonly (keyof Schema & string)[] = readonly [],
+  DeliveryArea extends string = never,
+  DeliveryArtifacts extends DeliveryArtifactsMap<RequestLocales, DeliveryArea> =
+    DeliveryArtifactsMap<RequestLocales, DeliveryArea>,
+> = [NsList] extends [readonly []]
+  ? I18nBuilderMultiInitial<
+      Schema,
+      Params,
+      RequestLocales,
+      ActiveLocales,
+      DeliveryArea,
+      DeliveryArtifacts
+    >
+  : I18nBuilderMultiReady<
+      Schema,
+      Params,
+      RequestLocales,
+      ActiveLocales,
+      NsList,
+      DeliveryArea,
+      DeliveryArtifacts
+    >;
+
+/** Builder after `withDeliveryArea` — partition is fixed; bind locale via `scope.forLocale` after `load()`. */
+export interface I18nBuilderMultiPartitioned<
+  Schema extends MultiDictionary,
+  Params extends MultiParams<Schema>,
+  RequestLocales extends string,
+  ActiveLocales extends RequestLocales,
+  NsList extends readonly (keyof Schema & string)[],
+  DeliveryArea extends string = never,
+  DeliveryArtifacts extends DeliveryArtifactsMap<RequestLocales, DeliveryArea> =
+    DeliveryArtifactsMap<RequestLocales, DeliveryArea>,
+> {
+  withNamespaces<const NS extends readonly (keyof Schema & string)[]>(
+    namespaces: NonEmptyNamespaces<NS>
+  ): I18nBuilderMultiPartitioned<
+    Schema,
+    Params,
+    RequestLocales,
+    ActiveLocales,
+    NS,
+    DeliveryArea,
+    DeliveryArtifacts
+  >;
+
+  load(): Promise<
+    I18nScopeMulti<
+      SchemaForNamespaces<Schema, NsList>,
+      ParamsForNamespaces<Schema, Params, NsList>,
+      ActiveLocales
+    >
+  >;
+}
+
+export interface I18nBuilderMultiForLocale<
+  Schema extends MultiDictionary,
+  Params extends MultiParams<Schema>,
+  RequestLocales extends string,
+  ActiveLocales extends RequestLocales,
+  NsList extends readonly (keyof Schema & string)[],
+  Locale extends ActiveLocales,
+> {
+  load(): Promise<
+    I18nScopeMultiForLocale<
+      SchemaForNamespaces<Schema, NsList>,
+      ParamsForNamespaces<Schema, Params, NsList>,
+      Locale,
+      Locale
+    >
+  >;
+}
+
+export class I18nBuilderMultiInitialImpl<
+  Schema extends MultiDictionary,
+  Params extends MultiParams<Schema>,
+  RequestLocales extends string = LocaleOfMulti<Schema>,
+  ActiveLocales extends RequestLocales = RequestLocales,
+  DeliveryArea extends string = never,
+  DeliveryArtifacts extends DeliveryArtifactsMap<RequestLocales, DeliveryArea> =
+    DeliveryArtifactsMap<RequestLocales, DeliveryArea>,
+> implements I18nBuilderMultiInitial<
+  Schema,
+  Params,
+  RequestLocales,
+  ActiveLocales,
+  DeliveryArea,
+  DeliveryArtifacts
+> {
+  constructor(
+    private readonly engine: I18nEngineMultiImpl<Schema, Params, RequestLocales>,
+    private readonly options?: I18nBuilderMultiOptions<Schema, RequestLocales>
+  ) {}
+
+  withNamespaces<const NS extends readonly (keyof Schema & string)[]>(
+    namespaces: NonEmptyNamespaces<NS>
+  ): I18nBuilderMultiReadyImpl<
+    Schema,
+    Params,
+    RequestLocales,
+    ActiveLocales,
+    NS,
+    DeliveryArea,
+    DeliveryArtifacts
+  > {
+    return new I18nBuilderMultiReadyImpl<
+      Schema,
+      Params,
+      RequestLocales,
+      ActiveLocales,
+      NS,
+      DeliveryArea,
+      DeliveryArtifacts
+    >(this.engine, this.options, { namespaces });
+  }
+}
+
+export class I18nBuilderMultiReadyImpl<
+  Schema extends MultiDictionary,
+  Params extends MultiParams<Schema>,
+  RequestLocales extends string = LocaleOfMulti<Schema>,
+  ActiveLocales extends RequestLocales = RequestLocales,
+  NsList extends readonly (keyof Schema & string)[] = readonly (keyof Schema & string)[],
+  DeliveryArea extends string = never,
+  DeliveryArtifacts extends DeliveryArtifactsMap<RequestLocales, DeliveryArea> =
+    DeliveryArtifactsMap<RequestLocales, DeliveryArea>,
+> implements I18nBuilderMultiReady<
+  Schema,
+  Params,
+  RequestLocales,
+  ActiveLocales,
+  NsList,
+  DeliveryArea,
+  DeliveryArtifacts
+> {
+  constructor(
+    private readonly engine: I18nEngineMultiImpl<Schema, Params, RequestLocales>,
+    private readonly options: I18nBuilderMultiOptions<Schema, RequestLocales> | undefined,
+    private readonly state: MultiBuilderState<Schema, RequestLocales, NsList>
+  ) {}
+
+  private clone(): MultiBuilderState<Schema, RequestLocales, NsList> {
+    return {
+      namespaces: this.state.namespaces,
+      ...(this.state.locale !== undefined ? { locale: this.state.locale } : {}),
+      ...(this.state.deliveryArea !== undefined ? { deliveryArea: this.state.deliveryArea } : {}),
+    };
+  }
+
+  withNamespaces<const NS extends readonly (keyof Schema & string)[]>(
+    namespaces: NonEmptyNamespaces<NS>
+  ): I18nBuilderMultiReadyImpl<
+    Schema,
+    Params,
+    RequestLocales,
+    ActiveLocales,
+    NS,
+    DeliveryArea,
+    DeliveryArtifacts
+  > {
+    return new I18nBuilderMultiReadyImpl<
+      Schema,
+      Params,
+      RequestLocales,
+      ActiveLocales,
+      NS,
+      DeliveryArea,
+      DeliveryArtifacts
+    >(this.engine, this.options, {
+      ...this.clone(),
+      namespaces,
+    });
+  }
+
+  withLocale<Locale extends ActiveLocales>(
+    locale: Locale
+  ): I18nBuilderMultiForLocaleImpl<Schema, Params, RequestLocales, ActiveLocales, NsList, Locale> {
+    const { deliveryArea: _deliveryArea, ...rest } = this.clone();
+    return new I18nBuilderMultiForLocaleImpl<
+      Schema,
+      Params,
+      RequestLocales,
+      ActiveLocales,
+      NsList,
+      Locale
+    >(this.engine, this.options, { ...rest, locale });
+  }
+
+  withDeliveryArea<Area extends DeliveryArea>(
+    area: Area
+  ): I18nBuilderMultiPartitionedImpl<
+    Schema,
+    Params,
+    RequestLocales,
+    LocalesForDeliveryAreaOrAll<RequestLocales, DeliveryArea, DeliveryArtifacts, Area>,
+    NsList,
+    DeliveryArea,
+    DeliveryArtifacts
+  > {
+    const { locale: _locale, ...rest } = this.clone();
+    return new I18nBuilderMultiPartitionedImpl<
+      Schema,
+      Params,
+      RequestLocales,
+      LocalesForDeliveryAreaOrAll<RequestLocales, DeliveryArea, DeliveryArtifacts, Area>,
+      NsList,
+      DeliveryArea,
+      DeliveryArtifacts
+    >(this.engine, this.options, { ...rest, deliveryArea: area });
+  }
+
+  async load(): Promise<
+    I18nScopeMulti<
+      SchemaForNamespaces<Schema, NsList>,
+      ParamsForNamespaces<Schema, Params, NsList>,
+      ActiveLocales
+    >
+  > {
+    await applyMultiBuilderLoad(this.engine, this.options, this.state);
+    return this.engine.toScope({ namespaces: this.state.namespaces });
+  }
+}
+
+/** @deprecated Use {@link I18nBuilderMultiInitialImpl} or {@link I18nBuilderMultiReadyImpl}. */
+export class I18nBuilderMultiImpl<
+  Schema extends MultiDictionary,
+  Params extends MultiParams<Schema>,
+  RequestLocales extends string = LocaleOfMulti<Schema>,
+  ActiveLocales extends RequestLocales = RequestLocales,
+  NsList extends readonly (keyof Schema & string)[] = readonly (keyof Schema & string)[],
+  DeliveryArea extends string = never,
+  DeliveryArtifacts extends DeliveryArtifactsMap<RequestLocales, DeliveryArea> =
+    DeliveryArtifactsMap<RequestLocales, DeliveryArea>,
+> extends I18nBuilderMultiReadyImpl<
+  Schema,
+  Params,
+  RequestLocales,
+  ActiveLocales,
+  NsList,
+  DeliveryArea,
+  DeliveryArtifacts
+> {}
+
+export class I18nBuilderMultiPartitionedImpl<
+  Schema extends MultiDictionary,
+  Params extends MultiParams<Schema>,
+  RequestLocales extends string,
+  ActiveLocales extends RequestLocales,
+  NsList extends readonly (keyof Schema & string)[],
+  DeliveryArea extends string = never,
+  DeliveryArtifacts extends DeliveryArtifactsMap<RequestLocales, DeliveryArea> =
+    DeliveryArtifactsMap<RequestLocales, DeliveryArea>,
+> implements I18nBuilderMultiPartitioned<
+  Schema,
+  Params,
+  RequestLocales,
+  ActiveLocales,
+  NsList,
+  DeliveryArea,
+  DeliveryArtifacts
+> {
+  constructor(
+    private readonly engine: I18nEngineMultiImpl<Schema, Params, RequestLocales>,
+    private readonly options: I18nBuilderMultiOptions<Schema, RequestLocales> | undefined,
+    private readonly state: MultiBuilderState<Schema, RequestLocales, NsList> & {
+      deliveryArea: string;
+    }
+  ) {}
+
+  withNamespaces<const NS extends readonly (keyof Schema & string)[]>(
+    namespaces: NonEmptyNamespaces<NS>
+  ): I18nBuilderMultiPartitionedImpl<
+    Schema,
+    Params,
+    RequestLocales,
+    ActiveLocales,
+    NS,
+    DeliveryArea,
+    DeliveryArtifacts
+  > {
+    return new I18nBuilderMultiPartitionedImpl<
+      Schema,
+      Params,
+      RequestLocales,
+      ActiveLocales,
+      NS,
+      DeliveryArea,
+      DeliveryArtifacts
+    >(this.engine, this.options, {
+      ...this.state,
+      namespaces,
+    });
+  }
+
+  async load(): Promise<
+    I18nScopeMulti<
+      SchemaForNamespaces<Schema, NsList>,
+      ParamsForNamespaces<Schema, Params, NsList>,
+      ActiveLocales
+    >
+  > {
+    await applyMultiBuilderLoad(this.engine, this.options, this.state);
+    return this.engine.toScope({ namespaces: this.state.namespaces });
+  }
+}
+
+export class I18nBuilderMultiForLocaleImpl<
+  Schema extends MultiDictionary,
+  Params extends MultiParams<Schema>,
+  RequestLocales extends string,
+  ActiveLocales extends RequestLocales,
+  NsList extends readonly (keyof Schema & string)[],
+  Locale extends ActiveLocales,
+> implements I18nBuilderMultiForLocale<
+  Schema,
+  Params,
+  RequestLocales,
+  ActiveLocales,
+  NsList,
+  Locale
+> {
+  constructor(
+    private readonly engine: I18nEngineMultiImpl<Schema, Params, RequestLocales>,
+    private readonly options: I18nBuilderMultiOptions<Schema, RequestLocales> | undefined,
+    private readonly state: MultiBuilderState<Schema, RequestLocales, NsList> & { locale: Locale }
+  ) {}
+
+  async load(): Promise<
+    I18nScopeMultiForLocale<
+      SchemaForNamespaces<Schema, NsList>,
+      ParamsForNamespaces<Schema, Params, NsList>,
+      Locale,
+      Locale
+    >
+  > {
+    await applyMultiBuilderLoad(this.engine, this.options, this.state);
+    return this.engine.toScope({ namespaces: this.state.namespaces }).forLocale(this.state.locale);
+  }
+}
+
+async function applyMultiBuilderLoad<
+  Schema extends MultiDictionary,
+  Params extends MultiParams<Schema>,
+  RequestLocales extends string,
+  NsList extends readonly (keyof Schema & string)[],
+>(
+  engine: I18nEngineMultiImpl<Schema, Params, RequestLocales>,
+  options: I18nBuilderMultiOptions<Schema, RequestLocales> | undefined,
+  state: MultiBuilderState<Schema, RequestLocales, NsList>
+): Promise<void> {
+  if (state.namespaces.length === 0) {
+    throw new Error("[i18n] withNamespaces(...) is required before load().");
+  }
+
+  const partition = state.locale ?? state.deliveryArea;
+
+  await Promise.all(
+    state.namespaces.map(async (namespace) => {
+      const loader = options?.namespaceLoaders?.[namespace];
+      if (loader === undefined) {
+        return;
+      }
+
+      if (engine.hasBuilderResourceLoaded(namespace, partition)) {
+        return;
+      }
+
+      const data = await invokeNamespaceLoader(loader, partition);
+      engine.applyLoadMergeNamespace(namespace, data);
+      engine.markBuilderResourceLoaded(namespace, partition);
+    })
+  );
+}