@xndrjs/i18n 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -7,10 +7,32 @@ type DeliveryArtifactsMap<RequestLocales extends string, DeliveryArea extends st
 /** 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;
 
+/** Serialized builder resource: namespace + partition (locale / delivery area). */
+type BuilderResourceEntry = readonly [namespace: string, partition: string];
+
+/**
+ * Portable i18n instance state after `serialize()`: dictionary strings + which
+ * builder resources are already loaded (namespace × partition).
+ */
+interface I18nSerializedState<Dictionary = Record<string, unknown>> {
+    dictionary: Dictionary;
+    resources: readonly BuilderResourceEntry[];
+}
+/**
+ * Input nested under generated `createI18n({ state? })`. Omitted `state` defaults to an empty
+ * dictionary (lazy cold start). `resources` may be omitted or `[]`.
+ */
+type I18nCreateInput<Dictionary = Record<string, unknown>> = {
+    dictionary: Dictionary;
+    resources?: readonly BuilderResourceEntry[];
+};
+declare function normalizeI18nCreateInput<Dictionary>(value?: I18nCreateInput<Dictionary>): I18nSerializedState<Dictionary>;
+
 type LocaleDictionary = Record<string, string>;
 type KeyDictionary = Record<string, LocaleDictionary>;
 type MultiDictionary = Record<string, KeyDictionary>;
-type LocaleOfSingle<Schema extends KeyDictionary> = {
+/** Locales present on any key of a flat (per-namespace) key dictionary. */
+type LocaleOfKeys<Schema extends KeyDictionary> = {
     [K in keyof Schema]: keyof Schema[K];
 }[keyof Schema] & string;
 type LocaleOfMulti<Schema extends MultiDictionary> = {
@@ -19,7 +41,7 @@ type LocaleOfMulti<Schema extends MultiDictionary> = {
     }[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>> = {
+type PartialKeyDictionary<T extends KeyDictionary, Locales extends string = LocaleOfKeys<T>> = {
     [K in keyof T]?: Partial<Record<Locales, string>>;
 };
 /** Subset of schema namespaces with partial keys/locales — valid input for multi merge operations. */
@@ -56,35 +78,35 @@ type MultiParams<Schema extends MultiDictionary> = {
 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;
-};
 /** Rest args for `t()` — `never` params omit the third argument. */
 type ParamArgs<P> = [P] extends [never] ? [] : [params: P];
+/**
+ * Namespace-bound `t(key, …)` — locale already bound.
+ * Call sites omit the namespace argument.
+ */
+type NamespaceBoundTranslateFn<Schema extends MultiDictionary, Params extends MultiParams<Schema>, NS extends keyof Schema & keyof Params & string> = <const K extends keyof Schema[NS] & keyof Params[NS] & string>(key: K, ...params: ParamArgs<Params[NS][K]>) => string;
 
 /** 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. */
+/** Multi-namespace scope with a bound locale — `t(namespace, key)` without a locale argument. */
 interface I18nScopeMultiForLocale<Schema extends MultiDictionary, Params, RequestLocales extends string, Locale extends RequestLocales> {
     readonly locale: Locale;
     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";
+    /** Loaded namespaces only — cold start is `{}`; never claim full Schema until loaded. */
     private dictionary;
     private compiledCache;
-    private readonly preloadedKeys;
     private readonly builderLoadRegistry;
     private readonly localeFallback?;
     private readonly onMissing;
-    constructor(dictionary: PartialMultiDictionary<Schema, RequestLocales>, options?: IcuTranslationProviderOptions<Fallback>);
+    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;
@@ -93,87 +115,21 @@ declare class IcuTranslationProviderMulti<Schema extends MultiDictionary, Params
     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;
+    /** Live dictionary reference (loaded namespaces only). Do not mutate. */
+    getAll(): PartialMultiDictionary<Schema, RequestLocales>;
+    hasBuilderResourceLoaded(namespace: string, partition: string): boolean;
+    markBuilderResourceLoaded(namespace: string, partition: string): void;
+    seedBuilderResources(resources: readonly BuilderResourceEntry[]): void;
+    serialize(): I18nSerializedState<PartialMultiDictionary<Schema, RequestLocales>>;
     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;
-}
-
-/** 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>> {
-    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 I18nScopeSingleImpl<Schema extends KeyDictionary, Params extends {
-    [K in keyof Schema]: unknown;
-}, 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(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 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>);
-    getWithLocale(key: string, locale: string, params?: Record<string, unknown>): string;
-    toScope(): I18nScopeSingleImpl<Schema, Params, RequestLocales, Fallback>;
-    toScope<Locale extends RequestLocales>(options: {
-        locale: Locale;
-    }): I18nScopeSingleForLocaleImpl<Schema, Params, RequestLocales, Locale, Fallback>;
-    getAll(): Schema;
-    hasBuilderResourceLoaded(partition: string | undefined): boolean;
-    markBuilderResourceLoaded(partition: string | undefined): void;
-    applyLoadMergeSingle(values: PartialKeyDictionary<Schema, RequestLocales>): void;
-    patchKey(key: string, locale: string, template: string): void;
-}
-
-/** 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>;
-}
 /** 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;
+    /** Loaded namespaces only — may be empty at cold start. */
+    getAll(): PartialMultiDictionary<Schema, RequestLocales>;
     toScope<NsList extends readonly (keyof Schema & string)[]>(options: {
         namespaces: NsList;
     }): I18nScopeMulti<SchemaForNamespaces<Schema, NsList>, ParamsForNamespaces<Schema, Params, NsList>, RequestLocales>;
@@ -182,144 +138,59 @@ interface I18nEngineMulti<Schema extends MultiDictionary, Params extends MultiPa
         locale: Locale;
     }): I18nScopeMultiForLocale<SchemaForNamespaces<Schema, NsList>, ParamsForNamespaces<Schema, Params, NsList>, RequestLocales, Locale>;
 }
-/** 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 PartitionedLoader<T> = (partition: string, context: {
+    locale: string;
+}) => Promise<T> | T;
+type NamespaceLoader<T> = PartitionedLoader<T>;
+declare function invokeNamespaceLoader<T>(loader: NamespaceLoader<T>, partition: string, context: {
+    locale: string;
+}): Promise<T>;
 
-type I18nBuilderMultiOptions<Schema extends MultiDictionary, RequestLocales extends string = LocaleOfMulti<Schema>> = {
+/** Engine handle accepted by {@link createI18nHandle} (with or without localeFallback). */
+type HandleEngine<Schema extends MultiDictionary, Params extends MultiParams<Schema>, RequestLocales extends string> = I18nEngineMultiImpl<Schema, Params, RequestLocales, LocaleFallbackMap$1 | undefined>;
+/** Non-empty namespace list — required by {@link I18nHandle.load} / {@link I18nHandle.peek}. */
+type NonEmptyNamespaces<NS extends readonly string[]> = NS extends readonly [] ? never : NS;
+/** Maps a request locale to the delivery partition key (locale itself, or a custom area). */
+type PartitionForLocale<RequestLocales extends string> = (locale: RequestLocales) => string;
+type I18nHandleOptions<Schema extends MultiDictionary, RequestLocales extends string = LocaleOfMulti<Schema>> = {
     namespaceLoaders?: {
         [NS in keyof Schema & string]?: NamespaceLoader<PartialKeyDictionary<Schema[NS], RequestLocales> | Schema[NS]>;
     };
+    /**
+     * Resolves the loader partition for a locale.
+     * Default: identity (`locale → locale`) for split-by-locale.
+     * Custom delivery: codegen injects `locale → LOCALE_DELIVERY_AREA[locale]`.
+     */
+    partitionForLocale?: PartitionForLocale<RequestLocales>;
 };
-/** 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>;
-}
-/** 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;
+type LoadNamespacesInput<Schema extends MultiDictionary, NsList extends readonly (keyof Schema & string)[], Locale extends string> = {
+    namespaces: NonEmptyNamespaces<NsList>;
+    locale: Locale;
 };
-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>>;
+/** Locale-bound scope returned by {@link I18nHandle.load} / {@link I18nHandle.peek}. */
+type ScopeForLocale<Schema extends MultiDictionary, Params extends MultiParams<Schema>, RequestLocales extends string, NsList extends readonly (keyof Schema & string)[], Locale extends RequestLocales> = I18nScopeMultiForLocale<SchemaForNamespaces<Schema, NsList>, ParamsForNamespaces<Schema, Params, NsList>, RequestLocales, Locale>;
+/**
+ * Single runtime handle: pass `namespaces` + `locale`; partition is derived via
+ * {@link I18nHandleOptions.partitionForLocale}.
+ */
+interface I18nHandle<Schema extends MultiDictionary, Params extends MultiParams<Schema>, RequestLocales extends string = LocaleOfMulti<Schema>> {
+    load<const NsList extends readonly (keyof Schema & string)[], Locale extends RequestLocales>(input: LoadNamespacesInput<Schema, NsList, Locale>): Promise<ScopeForLocale<Schema, Params, RequestLocales, NsList, Locale>>;
+    /**
+     * Sync scope when every requested resource is already marked loaded (e.g. hydrate seed).
+     * Returns `null` when a normal async {@link load} is still required.
+     */
+    peek<const NsList extends readonly (keyof Schema & string)[], Locale extends RequestLocales>(input: LoadNamespacesInput<Schema, NsList, Locale>): ScopeForLocale<Schema, Params, RequestLocales, NsList, Locale> | null;
+    /** Dictionary (loaded namespaces) + resources for SSR→CSR hydrate. */
+    serialize(): {
+        dictionary: PartialMultiDictionary<Schema, RequestLocales>;
+        resources: readonly (readonly [string, string])[];
+    };
 }
-
-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>;
+declare function createI18nHandle<Schema extends MultiDictionary, Params extends MultiParams<Schema>, RequestLocales extends string = LocaleOfMulti<Schema>>(engine: HandleEngine<Schema, Params, RequestLocales>, options?: I18nHandleOptions<Schema, RequestLocales>): I18nHandle<Schema, Params, RequestLocales>;
 
 type LocaleFallbackMap = Record<string, string | null>;
 interface ResolvedLocaleTemplate {
@@ -331,36 +202,31 @@ declare function validateLocaleFallback(map: LocaleFallbackMap): void;
 declare function resolveLocaleTemplate(localeByKey: Record<string, string | undefined> | undefined, requestedLocale: string, fallbackMap?: LocaleFallbackMap): ResolvedLocaleTemplate | undefined;
 declare function formatLocaleFallbackChain(requestedLocale: string, fallbackMap?: LocaleFallbackMap): string;
 
-/**
- * Builds a namespace dictionary that contains only the requested locales.
- * For each key and target locale, copies the direct template when present;
- * otherwise resolves through `localeFallback` (same rules as `.get()` at runtime).
- */
-declare function projectNamespaceLocalesCore<T extends KeyDictionary>(dictionary: T, locales: readonly string[], localeFallback?: LocaleFallbackMap$1): T;
-/**
- * Projects a single namespace for a custom delivery area.
- * Full locales resolve through `localeFallback` (e.g. external chains like `it → en-US`);
- * preserve locales copy only their direct canonical entry when present.
- */
-declare function projectNamespaceForDeliveryAreaCore<T extends KeyDictionary>(dictionary: T, areaLocales: readonly string[], localeFallback?: LocaleFallbackMap$1): T;
-/**
- * Projects a multi-namespace dictionary for a custom delivery area.
- * Each namespace uses the same delivery-area rules as `projectNamespaceForDeliveryAreaCore`.
- */
-declare function projectDictionaryForDeliveryAreaCore<T extends MultiDictionary>(dictionary: T, areaLocales: readonly string[], localeFallback?: LocaleFallbackMap$1): T;
-/**
- * Projects every namespace in a multi-namespace dictionary.
- */
-declare function projectDictionaryLocalesCore<T extends MultiDictionary>(dictionary: T, locales: readonly string[], localeFallback?: LocaleFallbackMap$1): T;
 /**
  * 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, Locales extends string = LocaleOfSingle<T>>(existing: T, incoming: PartialKeyDictionary<T, Locales>): T;
+declare function mergeNamespaceLocalesCore<T extends KeyDictionary, Locales extends string = LocaleOfKeys<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, Locales extends string = LocaleOfMulti<T>>(existing: T, incoming: PartialMultiDictionary<T, Locales>): T;
 
-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 };
+/**
+ * Identifies a delivery JSON artifact. Codegen passes this to {@link FetchArtifact};
+ * URL / filesystem mapping is an application concern.
+ */
+type DeliveryResourceId = {
+    locale: string;
+    namespace: string;
+    /** Present for `delivery: "custom"` (partition key is the area). */
+    area?: string;
+};
+/**
+ * Loads a translation JSON artifact by resource id.
+ * Must return the parsed JSON value (not a raw Response).
+ */
+type FetchArtifact = (id: DeliveryResourceId) => Promise<unknown>;
+
+export { type BuilderResourceEntry, type DeliveryArtifactsMap, type DeliveryResourceId, type FetchArtifact, type I18nCreateInput, type I18nEngineMulti, type I18nEngineMultiImpl, type I18nHandle, type I18nHandleOptions, type I18nScopeMulti, type I18nScopeMultiForLocale, type I18nSerializedState, IcuTranslationProviderMulti, type IcuTranslationProviderOptions, type KeyDictionary, type LoadNamespacesInput, type LocaleDictionary, type LocaleFallbackMap$1 as LocaleFallbackMap, type LocaleOfKeys, type LocaleOfMulti, type LocalesForDeliveryArea, type LocalesForDeliveryAreaOrAll, type MissingTranslationContext, type MultiDictionary, type MultiParams, type NamespaceBoundTranslateFn, type NamespaceLoader, type OnMissingTranslation, type ParamsForNamespaces, type PartialKeyDictionary, type PartialMultiDictionary, type PartitionForLocale, type PartitionedLoader, type ResolvedLocaleTemplate, type SchemaForNamespaces, type ScopeForLocale, createI18nHandle, formatLocaleFallbackChain, invokeNamespaceLoader, mergeDictionaryLocalesCore, mergeNamespaceLocalesCore, normalizeI18nCreateInput, resolveLocaleTemplate, validateLocaleFallback };