@xndrjs/i18n 0.6.1 → 0.7.0

package/dist/index.d.ts

@@ -1,3 +1,12 @@
+/** Locales served by a delivery area, from a codegen `DELIVERY_ARTIFACTS`-shaped map. */
+type LocalesForDeliveryArea<Artifacts extends Record<string, readonly string[]>, Area extends keyof Artifacts & string> = Artifacts[Area][number];
+/** Map from delivery area to locale lists; empty when custom delivery is not configured. */
+type DeliveryArtifactsMap<RequestLocales extends string, DeliveryArea extends string> = [
+    DeliveryArea
+] extends [never] ? Record<string, never> : Record<DeliveryArea, readonly RequestLocales[]>;
+/** When a delivery-area map is configured, resolve partition locales; otherwise keep the full pool. */
+type LocalesForDeliveryAreaOrAll<RequestLocales extends string, DeliveryArea extends string, DeliveryArtifacts extends DeliveryArtifactsMap<RequestLocales, DeliveryArea>, Area extends string> = [DeliveryArea] extends [never] ? RequestLocales : Area extends DeliveryArea ? DeliveryArtifacts[Area][number] : never;
+
 type LocaleDictionary = Record<string, string>;
 type KeyDictionary = Record<string, LocaleDictionary>;
 type MultiDictionary = Record<string, KeyDictionary>;
@@ -9,6 +18,14 @@ type LocaleOfMulti<Schema extends MultiDictionary> = {
         [K in keyof Schema[NS]]: keyof Schema[NS][K];
     }[keyof Schema[NS]];
 }[keyof Schema] & string;
+/** Subset of schema keys with any subset of project locales per key — valid input for merge operations. */
+type PartialKeyDictionary<T extends KeyDictionary, Locales extends string = LocaleOfSingle<T>> = {
+    [K in keyof T]?: Partial<Record<Locales, string>>;
+};
+/** Subset of schema namespaces with partial keys/locales — valid input for multi merge operations. */
+type PartialMultiDictionary<T extends MultiDictionary, Locales extends string = LocaleOfMulti<T>> = {
+    [NS in keyof T]?: PartialKeyDictionary<T[NS], Locales>;
+};
 type LocaleFallbackMap$1 = Record<string, string | null>;
 type MissingTranslationContext = {
     /** Only set by the multi-namespace provider. */
@@ -29,98 +46,280 @@ type IcuTranslationProviderOptions<Fallback extends LocaleFallbackMap$1 | undefi
     onMissing?: OnMissingTranslation;
 };
 
-interface TranslationProviderSingleForLocale<Schema extends KeyDictionary, Params extends {
+/** ICU argument map for a multi-namespace schema. */
+type MultiParams<Schema extends MultiDictionary> = {
+    [NS in keyof Schema]: {
+        [K in keyof Schema[NS]]: unknown;
+    };
+};
+/** Restrict a multi schema to a subset of namespaces. */
+type SchemaForNamespaces<Schema extends MultiDictionary, NsList extends readonly (keyof Schema & string)[]> = Pick<Schema, NsList[number]>;
+/** Restrict multi ICU params to a subset of namespaces. */
+type ParamsForNamespaces<Schema extends MultiDictionary, Params extends MultiParams<Schema>, NsList extends readonly (keyof Schema & string)[]> = Pick<Params, NsList[number]>;
+/** ICU argument map for a single-namespace schema. */
+type SingleParams<Schema extends KeyDictionary> = {
     [K in keyof Schema]: unknown;
-}, Locale extends string> {
+};
+/** Rest args for `t()` — `never` params omit the third argument. */
+type ParamArgs<P> = [P] extends [never] ? [] : [params: P];
+
+/** Type-safe translation scope for a multi-namespace schema subset. */
+interface I18nScopeMulti<Schema extends MultiDictionary, Params, RequestLocales extends string = LocaleOfMulti<Schema>> {
+    t<const NS extends keyof Schema & keyof Params & string, const K extends keyof Schema[NS] & keyof Params[NS] & string>(namespace: NS, key: K, locale: RequestLocales, ...params: ParamArgs<Params[NS][K]>): string;
+    forLocale<Locale extends RequestLocales>(locale: Locale): I18nScopeMultiForLocale<Schema, Params, RequestLocales, Locale>;
+}
+/** Multi-namespace scope with a bound locale — `t(namespace, key)` and `set(...)` without a locale argument. */
+interface I18nScopeMultiForLocale<Schema extends MultiDictionary, Params, RequestLocales extends string, Locale extends RequestLocales> {
     readonly locale: Locale;
-    get<K extends keyof Schema & string>(key: K, ...params: Params[K] extends never ? [] : [params: Params[K]]): string;
+    t<const NS extends keyof Schema & keyof Params & string, const K extends keyof Schema[NS] & keyof Params[NS] & string>(namespace: NS, key: K, ...params: ParamArgs<Params[NS][K]>): string;
+    set<const NS extends keyof Schema & keyof Params & string, const K extends keyof Schema[NS] & keyof Params[NS] & string>(namespace: NS, key: K, template: string): void;
+    forLocale<Next extends RequestLocales>(locale: Next): I18nScopeMultiForLocale<Schema, Params, RequestLocales, Next>;
+}
+
+declare class IcuTranslationProviderMulti<Schema extends MultiDictionary, Params extends MultiParams<Schema>, RequestLocales extends string = LocaleOfMulti<Schema>, Fallback extends LocaleFallbackMap$1 | undefined = undefined> implements I18nEngineMulti<Schema, Params, RequestLocales> {
+    readonly __i18nEngineMode: "multi";
+    private dictionary;
+    private compiledCache;
+    private readonly preloadedKeys;
+    private readonly builderLoadRegistry;
+    private readonly localeFallback?;
+    private readonly onMissing;
+    constructor(dictionary: PartialMultiDictionary<Schema, RequestLocales>, options?: IcuTranslationProviderOptions<Fallback>);
+    getWithLocale(namespace: string, key: string, locale: string, params?: Record<string, unknown>): string;
+    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>;
+    getAll(): Schema;
+    hasBuilderResourceLoaded(namespace: string, partition: string | undefined): boolean;
+    markBuilderResourceLoaded(namespace: string, partition: string | undefined): void;
+    applyLoadMergeNamespace<NS extends keyof Schema>(namespace: NS, values: PartialKeyDictionary<Schema[NS], RequestLocales>): void;
+    applyLoadMergeAll(values: PartialMultiDictionary<Schema, RequestLocales>): void;
+    patchKeyMulti(namespace: string, key: string, locale: string, template: string): void;
 }
-interface TranslationProviderSingle<Schema extends KeyDictionary, Params extends {
+
+/** Type-safe translation scope for a single-namespace schema. */
+interface I18nScopeSingle<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;
+    t<const K extends keyof Schema & string>(key: K, locale: RequestLocales, ...params: ParamArgs<Params[K]>): string;
+    forLocale<Locale extends RequestLocales>(locale: Locale): I18nScopeSingleForLocale<Schema, Params, Locale>;
+}
+/** Single-namespace scope with a bound locale — `t(key)` and `set(key)` without a locale argument. */
+interface I18nScopeSingleForLocale<Schema extends KeyDictionary, Params extends {
+    [K in keyof Schema]: unknown;
+}, Locale extends string> {
+    readonly locale: Locale;
+    t<const K extends keyof Schema & string>(key: K, ...params: ParamArgs<Params[K]>): string;
+    set<const K extends keyof Schema & string>(key: K, template: string): void;
+    forLocale<Next extends Locale>(locale: Next): I18nScopeSingleForLocale<Schema, Params, Next>;
 }
-declare class IcuTranslationProviderSingleForLocale<Schema extends KeyDictionary, Params extends {
+declare class I18nScopeSingleImpl<Schema extends KeyDictionary, Params extends {
     [K in keyof Schema]: unknown;
-}, RequestLocales extends string, Locale extends RequestLocales, Fallback extends LocaleFallbackMap$1 | undefined> implements TranslationProviderSingleForLocale<Schema, Params, Locale> {
-    private readonly provider;
+}, RequestLocales extends string, Fallback extends LocaleFallbackMap$1 | undefined> implements I18nScopeSingle<Schema, Params, RequestLocales> {
+    private readonly engine;
+    constructor(engine: IcuTranslationProviderSingle<Schema, Params, RequestLocales, Fallback>);
+    t: <const K extends keyof Schema & string>(key: K, locale: RequestLocales, ...args: ParamArgs<Params[K]>) => string;
+    forLocale: <Locale extends RequestLocales>(locale: Locale) => I18nScopeSingleForLocaleImpl<Schema, Params, RequestLocales, Locale, Fallback>;
+}
+declare class I18nScopeSingleForLocaleImpl<Schema extends KeyDictionary, Params extends {
+    [K in keyof Schema]: unknown;
+}, RequestLocales extends string, Locale extends RequestLocales, Fallback extends LocaleFallbackMap$1 | undefined> implements I18nScopeSingleForLocale<Schema, Params, Locale> {
+    private readonly engine;
     readonly locale: Locale;
-    constructor(provider: IcuTranslationProviderSingle<Schema, Params, RequestLocales, Fallback>, locale: Locale);
-    get<K extends keyof Schema & string>(key: K, ...args: Params[K] extends never ? [] : [params: Params[K]]): string;
+    constructor(engine: IcuTranslationProviderSingle<Schema, Params, RequestLocales, Fallback>, locale: Locale);
+    t: <const K extends keyof Schema & string>(key: K, ...args: ParamArgs<Params[K]>) => string;
+    set: <const K extends keyof Schema & string>(key: K, template: string) => void;
+    forLocale: <Next extends Locale>(locale: Next) => I18nScopeSingleForLocaleImpl<Schema, Params, RequestLocales, Next, Fallback>;
 }
+
 declare class IcuTranslationProviderSingle<Schema extends KeyDictionary, Params extends {
     [K in keyof Schema]: unknown;
-}, RequestLocales extends string = LocaleOfSingle<Schema>, Fallback extends LocaleFallbackMap$1 | undefined = undefined> implements TranslationProviderSingle<Schema, Params, RequestLocales> {
+}, RequestLocales extends string = LocaleOfSingle<Schema>, Fallback extends LocaleFallbackMap$1 | undefined = undefined> implements I18nEngineSingle<Schema, Params, RequestLocales> {
+    readonly __i18nEngineMode: "single";
     private dictionary;
     private compiledCache;
+    private readonly preloadedKeys;
+    private readonly builderLoadRegistry;
     private readonly localeFallback?;
     private readonly onMissing;
     constructor(dictionary: Schema, options?: IcuTranslationProviderOptions<Fallback>);
-    get<K extends keyof Schema & string>(key: K, locale: RequestLocales, ...args: Params[K] extends never ? [] : [params: Params[K]]): string;
     getWithLocale(key: string, locale: string, params?: Record<string, unknown>): string;
-    forLocale<Locale extends RequestLocales>(locale: Locale): IcuTranslationProviderSingleForLocale<Schema, Params, RequestLocales, Locale, Fallback>;
+    toScope(): I18nScopeSingleImpl<Schema, Params, RequestLocales, Fallback>;
+    toScope<Locale extends RequestLocales>(options: {
+        locale: Locale;
+    }): I18nScopeSingleForLocaleImpl<Schema, Params, RequestLocales, Locale, Fallback>;
     getAll(): Schema;
-    setAll(values: Schema): void;
-    mergeAll(values: Partial<Schema>): void;
+    hasBuilderResourceLoaded(partition: string | undefined): boolean;
+    markBuilderResourceLoaded(partition: string | undefined): void;
+    applyLoadMergeSingle(values: PartialKeyDictionary<Schema, RequestLocales>): void;
+    patchKey(key: string, locale: string, template: string): void;
 }
 
-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;
+/** Mutable translation engine for a single-namespace dictionary. */
+interface I18nEngineSingle<Schema extends KeyDictionary, Params extends {
+    [K in keyof Schema]: unknown;
+}, RequestLocales extends string = LocaleOfSingle<Schema>> {
+    readonly __i18nEngineMode: "single";
+    getAll(): Schema;
+    toScope(): I18nScopeSingle<Schema, Params, RequestLocales>;
+    toScope<Locale extends RequestLocales>(options: {
+        locale: Locale;
+    }): I18nScopeSingleForLocale<Schema, Params, Locale>;
 }
-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>;
+/** Mutable translation engine for a multi-namespace dictionary. */
+interface I18nEngineMulti<Schema extends MultiDictionary, Params extends MultiParams<Schema>, RequestLocales extends string = LocaleOfMulti<Schema>> {
+    readonly __i18nEngineMode: "multi";
     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;
+    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;
+    }): I18nScopeMultiForLocale<SchemaForNamespaces<Schema, NsList>, ParamsForNamespaces<Schema, Params, NsList>, RequestLocales, Locale>;
 }
-declare class IcuTranslationProviderMultiForLocale<Schema extends MultiDictionary, Params extends {
-    [NS in keyof Schema]: {
-        [K in keyof Schema[NS]]: unknown;
+/** Alias for the default single-namespace engine implementation. */
+type I18nEngineSingleImpl<Schema extends KeyDictionary, Params extends {
+    [K in keyof Schema]: unknown;
+}, RequestLocales extends string = LocaleOfSingle<Schema>, Fallback extends LocaleFallbackMap$1 | undefined = undefined> = IcuTranslationProviderSingle<Schema, Params, RequestLocales, Fallback>;
+/** Alias for the default multi-namespace engine implementation. */
+type I18nEngineMultiImpl<Schema extends MultiDictionary, Params extends MultiParams<Schema>, RequestLocales extends string = LocaleOfMulti<Schema>, Fallback extends LocaleFallbackMap$1 | undefined = undefined> = IcuTranslationProviderMulti<Schema, Params, RequestLocales, Fallback>;
+
+/** Canonical lazy loader — no locale or delivery-area partition. */
+type CanonicalLoader<T> = () => Promise<T> | T;
+/** Split-by-locale or custom-area loader — partition key is locale or area name. */
+type PartitionedLoader<T> = (partition: string) => Promise<T> | T;
+type NamespaceLoader<T> = CanonicalLoader<T> | PartitionedLoader<T>;
+declare function invokeNamespaceLoader<T>(loader: NamespaceLoader<T>, partition: string | undefined): Promise<T>;
+
+type I18nBuilderMultiOptions<Schema extends MultiDictionary, RequestLocales extends string = LocaleOfMulti<Schema>> = {
+    namespaceLoaders?: {
+        [NS in keyof Schema & string]?: NamespaceLoader<PartialKeyDictionary<Schema[NS], RequestLocales> | Schema[NS]>;
     };
-}, RequestLocales extends string, Locale extends RequestLocales, Fallback extends LocaleFallbackMap$1 | undefined> implements TranslationProviderMultiForLocale<Schema, Params, Locale> {
-    private readonly provider;
-    readonly locale: Locale;
-    constructor(provider: IcuTranslationProviderMulti<Schema, Params, RequestLocales, Fallback>, 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;
+};
+/** 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. */
+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>;
 }
-declare class IcuTranslationProviderMulti<Schema extends MultiDictionary, Params extends {
-    [NS in keyof Schema]: {
-        [K in keyof Schema[NS]]: unknown;
-    };
-}, RequestLocales extends string = LocaleOfMulti<Schema>, Fallback extends LocaleFallbackMap$1 | undefined = undefined> implements TranslationProviderMulti<Schema, Params, RequestLocales> {
-    private dictionary;
-    private compiledCache;
-    private readonly localeFallback?;
-    private readonly onMissing;
-    private loadedNamespaces;
-    constructor(dictionary: Partial<Schema>, options?: IcuTranslationProviderOptions<Fallback>);
-    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;
-    getWithLocale(namespace: string, key: string, locale: string, params?: Record<string, unknown>): string;
-    forLocale<Locale extends RequestLocales>(locale: Locale): IcuTranslationProviderMultiForLocale<Schema, Params, RequestLocales, Locale, Fallback>;
-    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;
+/** Builder after `withNamespaces([...])` — partition selection and `load()` are available. */
+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`. */
+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()`. */
+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>>;
+}
+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>>;
+}
+declare 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> {
+    private readonly engine;
+    private readonly options?;
+    constructor(engine: I18nEngineMultiImpl<Schema, Params, RequestLocales>, options?: I18nBuilderMultiOptions<Schema, RequestLocales> | undefined);
+    withNamespaces<const NS extends readonly (keyof Schema & string)[]>(namespaces: NonEmptyNamespaces<NS>): I18nBuilderMultiReadyImpl<Schema, Params, RequestLocales, ActiveLocales, NS, DeliveryArea, DeliveryArtifacts>;
+}
+declare 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> {
+    private readonly engine;
+    private readonly options;
+    private readonly state;
+    constructor(engine: I18nEngineMultiImpl<Schema, Params, RequestLocales>, options: I18nBuilderMultiOptions<Schema, RequestLocales> | undefined, state: MultiBuilderState<Schema, RequestLocales, NsList>);
+    private clone;
+    withNamespaces<const NS extends readonly (keyof Schema & string)[]>(namespaces: NonEmptyNamespaces<NS>): I18nBuilderMultiReadyImpl<Schema, Params, RequestLocales, ActiveLocales, NS, DeliveryArea, DeliveryArtifacts>;
+    withLocale<Locale extends ActiveLocales>(locale: Locale): I18nBuilderMultiForLocaleImpl<Schema, Params, RequestLocales, ActiveLocales, NsList, Locale>;
+    withDeliveryArea<Area extends DeliveryArea>(area: Area): I18nBuilderMultiPartitionedImpl<Schema, Params, RequestLocales, LocalesForDeliveryAreaOrAll<RequestLocales, DeliveryArea, DeliveryArtifacts, Area>, NsList, DeliveryArea, DeliveryArtifacts>;
+    load(): Promise<I18nScopeMulti<SchemaForNamespaces<Schema, NsList>, ParamsForNamespaces<Schema, Params, NsList>, ActiveLocales>>;
 }
+declare 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> {
+    private readonly engine;
+    private readonly options;
+    private readonly state;
+    constructor(engine: I18nEngineMultiImpl<Schema, Params, RequestLocales>, options: I18nBuilderMultiOptions<Schema, RequestLocales> | undefined, 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>;
+    load(): Promise<I18nScopeMulti<SchemaForNamespaces<Schema, NsList>, ParamsForNamespaces<Schema, Params, NsList>, ActiveLocales>>;
+}
+declare 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> {
+    private readonly engine;
+    private readonly options;
+    private readonly state;
+    constructor(engine: I18nEngineMultiImpl<Schema, Params, RequestLocales>, options: I18nBuilderMultiOptions<Schema, RequestLocales> | undefined, state: MultiBuilderState<Schema, RequestLocales, NsList> & {
+        locale: Locale;
+    });
+    load(): Promise<I18nScopeMultiForLocale<SchemaForNamespaces<Schema, NsList>, ParamsForNamespaces<Schema, Params, NsList>, Locale, Locale>>;
+}
+
+type SingleScopeBound<Schema extends KeyDictionary, Params, Locale extends string> = I18nScopeSingleForLocale<Schema, Params & {
+    [K in keyof Schema]: unknown;
+}, Locale>;
+type I18nBuilderSingleOptions<Schema extends KeyDictionary, RequestLocales extends string = LocaleOfSingle<Schema>> = {
+    dictionaryLoader?: NamespaceLoader<PartialKeyDictionary<Schema, RequestLocales> | Schema>;
+};
+interface I18nBuilderSingle<Schema extends KeyDictionary, Params extends {
+    [K in keyof Schema]: unknown;
+}, RequestLocales extends string = LocaleOfSingle<Schema>> {
+    withLocale<Locale extends RequestLocales>(locale: Locale): I18nBuilderSingleForLocaleImpl<Schema, Params, RequestLocales, Locale>;
+    withDeliveryArea<Area extends string>(area: Area): I18nBuilderSingle<Schema, Params, RequestLocales>;
+    load(): Promise<I18nScopeSingleImpl<Schema, Params, RequestLocales, LocaleFallbackMap$1 | undefined>>;
+}
+interface I18nBuilderSingleForLocale<Schema extends KeyDictionary, Params extends {
+    [K in keyof Schema]: unknown;
+}, Locale extends string> {
+    load(): Promise<SingleScopeBound<Schema, Params, Locale>>;
+}
+type SingleBuilderState<Schema extends KeyDictionary, RequestLocales extends string = LocaleOfSingle<Schema>> = {
+    locale?: RequestLocales;
+    deliveryArea?: string;
+};
+declare class I18nBuilderSingleImpl<Schema extends KeyDictionary, Params extends {
+    [K in keyof Schema]: unknown;
+}, RequestLocales extends string = LocaleOfSingle<Schema>> implements I18nBuilderSingle<Schema, Params, RequestLocales> {
+    private readonly engine;
+    private readonly options?;
+    private state;
+    constructor(engine: I18nEngineSingleImpl<Schema, Params, RequestLocales>, options?: I18nBuilderSingleOptions<Schema, RequestLocales> | undefined, state?: SingleBuilderState<Schema, RequestLocales>);
+    private clone;
+    withLocale<Locale extends RequestLocales>(locale: Locale): I18nBuilderSingleForLocaleImpl<Schema, Params, RequestLocales, Locale>;
+    withDeliveryArea<Area extends string>(_area: Area): I18nBuilderSingle<Schema, Params, RequestLocales>;
+    load(): Promise<I18nScopeSingleImpl<Schema, Params, RequestLocales, LocaleFallbackMap$1 | undefined>>;
+}
+declare class I18nBuilderSingleForLocaleImpl<Schema extends KeyDictionary, Params extends {
+    [K in keyof Schema]: unknown;
+}, RequestLocales extends string = LocaleOfSingle<Schema>, Locale extends RequestLocales = RequestLocales> implements I18nBuilderSingleForLocale<Schema, Params, Locale> {
+    private readonly engine;
+    private readonly options;
+    private readonly state;
+    constructor(engine: I18nEngineSingleImpl<Schema, Params, RequestLocales>, options: I18nBuilderSingleOptions<Schema, RequestLocales> | undefined, state: SingleBuilderState<Schema, RequestLocales> & {
+        locale: Locale;
+    });
+    load(): Promise<SingleScopeBound<Schema, Params, Locale>>;
+}
+
+declare function createI18nSingleBuilder<Schema extends KeyDictionary, Params extends {
+    [K in keyof Schema]: unknown;
+}, RequestLocales extends string = LocaleOfSingle<Schema>>(engine: I18nEngineSingleImpl<Schema, Params, RequestLocales>, options?: I18nBuilderSingleOptions<Schema, RequestLocales>): I18nBuilderSingleImpl<Schema, Params, RequestLocales>;
+declare function createI18nMultiBuilder<Schema extends MultiDictionary, Params extends MultiParams<Schema>, RequestLocales extends string = LocaleOfMulti<Schema>, DeliveryArea extends string = never, DeliveryArtifacts extends DeliveryArtifactsMap<RequestLocales, DeliveryArea> = DeliveryArtifactsMap<RequestLocales, DeliveryArea>>(engine: I18nEngineMultiImpl<Schema, Params, RequestLocales>, options?: I18nBuilderMultiOptions<Schema, RequestLocales>): I18nBuilderMultiInitialImpl<Schema, Params, RequestLocales, RequestLocales, DeliveryArea, DeliveryArtifacts>;
+declare function createI18nBuilder<Schema extends MultiDictionary, Params extends MultiParams<Schema>, RequestLocales extends string = LocaleOfMulti<Schema>>(engine: I18nEngineMultiImpl<Schema, Params, RequestLocales>, options?: I18nBuilderMultiOptions<Schema, RequestLocales>): I18nBuilderMultiInitialImpl<Schema, Params, RequestLocales, RequestLocales, never, DeliveryArtifactsMap<RequestLocales, never>>;
+declare function createI18nBuilder<Schema extends KeyDictionary, Params extends {
+    [K in keyof Schema]: unknown;
+}, RequestLocales extends string = LocaleOfSingle<Schema>>(engine: I18nEngineSingleImpl<Schema, Params, RequestLocales>, options?: I18nBuilderSingleOptions<Schema, RequestLocales>): I18nBuilderSingleImpl<Schema, Params, RequestLocales>;
 
 type LocaleFallbackMap = Record<string, string | null>;
 interface ResolvedLocaleTemplate {
@@ -157,11 +356,11 @@ declare function projectDictionaryLocalesCore<T extends MultiDictionary>(diction
  * Merges locale entries per translation key without dropping keys or locales
  * already present in `existing`. Incoming locales overwrite the same locale on conflict.
  */
-declare function mergeNamespaceLocalesCore<T extends KeyDictionary>(existing: T, incoming: T): T;
+declare function mergeNamespaceLocalesCore<T extends KeyDictionary, Locales extends string = LocaleOfSingle<T>>(existing: T, incoming: PartialKeyDictionary<T, Locales>): T;
 /**
  * Merges locale entries per key in every namespace present in `incoming`.
  * Namespaces and keys not in `incoming` are preserved from `existing`.
  */
-declare function mergeDictionaryLocalesCore<T extends MultiDictionary>(existing: T, incoming: Partial<T>): T;
+declare function mergeDictionaryLocalesCore<T extends MultiDictionary, Locales extends string = LocaleOfMulti<T>>(existing: T, incoming: PartialMultiDictionary<T, Locales>): T;
 
-export { IcuTranslationProviderMulti, type IcuTranslationProviderOptions, IcuTranslationProviderSingle, type KeyDictionary, type LocaleDictionary, type LocaleFallbackMap$1 as LocaleFallbackMap, type LocaleOfMulti, type LocaleOfSingle, type MissingTranslationContext, type MultiDictionary, type OnMissingTranslation, type ResolvedLocaleTemplate, type TranslationProviderMulti, type TranslationProviderMultiForLocale, type TranslationProviderSingle, type TranslationProviderSingleForLocale, formatLocaleFallbackChain, mergeDictionaryLocalesCore, mergeNamespaceLocalesCore, projectDictionaryForDeliveryAreaCore, projectDictionaryLocalesCore, projectNamespaceForDeliveryAreaCore, projectNamespaceLocalesCore, resolveLocaleTemplate, validateLocaleFallback };
+export { type CanonicalLoader, type DeliveryArtifactsMap, type I18nBuilderMulti, type I18nBuilderMultiForLocale, type I18nBuilderMultiInitial, type I18nBuilderMultiOptions, type I18nBuilderMultiPartitioned, type I18nBuilderMultiReady, type I18nBuilderSingle, type I18nBuilderSingleForLocale, type I18nBuilderSingleOptions, type I18nEngineMulti, type I18nEngineMultiImpl, type I18nEngineSingle, type I18nEngineSingleImpl, type I18nScopeMulti, type I18nScopeMultiForLocale, type I18nScopeSingle, type I18nScopeSingleForLocale, IcuTranslationProviderMulti, type IcuTranslationProviderOptions, IcuTranslationProviderSingle, type KeyDictionary, type LocaleDictionary, type LocaleFallbackMap$1 as LocaleFallbackMap, type LocaleOfMulti, type LocaleOfSingle, type LocalesForDeliveryArea, type LocalesForDeliveryAreaOrAll, type MissingTranslationContext, type MultiDictionary, type MultiParams, type NamespaceLoader, type OnMissingTranslation, type ParamsForNamespaces, type PartialKeyDictionary, type PartialMultiDictionary, type PartitionedLoader, type ResolvedLocaleTemplate, type SchemaForNamespaces, type SingleParams, createI18nBuilder, createI18nMultiBuilder, createI18nSingleBuilder, formatLocaleFallbackChain, invokeNamespaceLoader, mergeDictionaryLocalesCore, mergeNamespaceLocalesCore, projectDictionaryForDeliveryAreaCore, projectDictionaryLocalesCore, projectNamespaceForDeliveryAreaCore, projectNamespaceLocalesCore, resolveLocaleTemplate, validateLocaleFallback };