@sveltekit-i18n/base 3.1.2 → 3.3.0

package/dist/I18n.svelte.js

@@ -1,13 +1,17 @@
 import { untrack } from 'svelte';
-import { capturesParams, fetchTranslation, hasOwn, loaderName, maskOutputKeys, maskTranslations, mergeFetched, mergeTranslations, omitProtoKeys, paramsSignature, read, resolveLoaders, routeParams, sanitizerFactory, sanitizeTranslationLocales, serialize, servedLocales, toDotNotation, translate, unique, withoutBasePath } from './utils.js';
+import { capturesParams, dotNotates, fetchTranslation, hasOwn, loaderName, maskOutputKeys, maskTranslations, mergeFetched, mergeTranslations, omitProtoKeys, paramsSignature, read, resolveLoaders, routeParams, sanitizerFactory, sanitizeTranslationLocales, serialize, servedLocales, toDotNotation, translate, unique, withoutBasePath } from './utils.js';
 import { logError, logger, loggerFactory, setLogger } from './logger.js';
 const defaultCache = Number.POSITIVE_INFINITY;
+const unasked = { config: undefined, signatures: new Map() };
+const noLoaders = [];
 /**
  * A top-level key holding part of `namespace` — the namespace itself or a key
  * flattened out of it. Keys are strings, so an off-contract namespace that is
  * not one holds none of them.
  */
 const isNamespaceKey = (key, namespace) => typeof namespace === 'string' && (key === namespace || key.startsWith(`${namespace}.`));
+/** What the log says of a load of `locale` on `route` whose data could not be applied. */
+const loadFailure = (locale, route) => `Failed to load translations for '${locale}' locale${route ? ` and '${route}' route` : ''}.`;
 class I18nCore {
     // -- reactive state ---------------------------------------------------------
     /**
@@ -47,13 +51,20 @@ class I18nCore {
     // apart from the records: invalidation drops those, not what is displayed,
     // and a reconfiguration hands them on to the same loaders of the new config.
     #deliveries = new Map();
+    // The delivery each seed's masked copy in `#deliveries` stands for: a seed is
+    // no replacement, so what counts on a delivery counts on its copy.
+    #maskedFrom = new WeakMap();
     #externalTranslations = {};
     // The params signature the next trigger asks each loader for:
     // the one the most recent call asked for, unless a failed call put an
     // earlier one's back, and `null` for a loader its route does not select.
     // Loads settle out of order, and a delivery for params the route no longer
     // asks for must not replace what it displays; a warm load asks for nothing.
-    #wanted = new Map();
+    // Replaced whole, never changed in place, so a call keeps what it replaced
+    // by reference.
+    #wanted = unasked;
+    // What `#localeLoaders` found for each locale, under the config it read.
+    #byLocale = { config: undefined, loaders: new Map() };
     // The latest delivery of each loader for params nothing wanted yet — a warm
     // load of another route's params, typically a preload — so the trigger that
     // wants them applies it instead of fetching again. One per loader, as a
@@ -64,7 +75,8 @@ class I18nCore {
     // records keep no trigger that selects them from running them. It serves the
     // pass it arrived with: until an activating trigger asks for another locale
     // or route than the hand-off named, or than the first activating trigger
-    // after it where the hand-off named none.
+    // after it where the hand-off named none, or until a preload, the request
+    // of a navigation.
     #handedOff = new Map();
     #handOffPass = {};
     /** When each locale first received data — drives the `cache` expiry. */
@@ -91,6 +103,12 @@ class I18nCore {
      * call that came later and has not failed keeps what it asked for.
      */
     #calls = [];
+    // Moved by `invalidate()` and by a reconfiguration: a preload's answers
+    // predate one that moved it. Expiry leaves it: a preload judged the window
+    // at its own request, and a later request's judgement is no newer for it.
+    #epoch = 0;
+    // What each token of `preload()` stands for, until a call reads it.
+    #preloads = new WeakMap();
     #destroyed = false;
     constructor(config) {
         if (config)
@@ -129,8 +147,26 @@ class I18nCore {
         // Loader locales are sanitized once, when the config resolves them, and
         // table locales once, when their data arrives; a custom `sanitizeLocales`
         // need not be idempotent.
-        return servedLocales(this.#config.loaders ?? [], this.#translations);
+        return this.#served();
     });
+    // Svelte memoizes a server `$derived` only when it is created during a
+    // render, which an instance is not, so `locales` is not memoized there.
+    #loaderLocales = { loaders: noLoaders, locales: [] };
+    /**
+     * The locales the config and the tables serve, as a fresh array. The
+     * loaders' are read once per loader list, the tables' on every call: a
+     * navigation to new params replaces the tables, so a memo keyed by them
+     * would miss on each one, adding a lookup and an entry per navigation,
+     * held until a later collection.
+     */
+    #served() {
+        if (!this.#config)
+            return [];
+        const { loaders = noLoaders } = this.#config;
+        if (this.#loaderLocales.loaders !== loaders)
+            this.#loaderLocales = { loaders, locales: servedLocales(loaders, {}) };
+        return unique([...this.#loaderLocales.locales, ...Object.keys(this.#translations)]);
+    }
     initialized = $derived(this.#locale !== undefined && this.#route !== undefined && Object.keys(this.#translations).length > 0);
     /**
      * Translates `key` for the active locale. Reactive on two levels: the
@@ -191,7 +227,6 @@ class I18nCore {
         // A reconfiguration can swap loaders or cache policy — bookkeeping from
         // the previous config must not suppress the new loaders.
         this.invalidate();
-        this.#wanted.clear();
         this.#handOnDeliveries(loaders);
         if (translations)
             this.addTranslations(translations);
@@ -228,7 +263,7 @@ class I18nCore {
     setLocale = (locale) => untrack(() => {
         if (!locale || this.#inert('setLocale') || this.#unserved(locale))
             return Promise.resolve();
-        const call = this.#ask();
+        const call = this.#ask({ locale, route: this.#route });
         if (locale !== this.#requestedLocale) {
             logger.debug(`Setting '${locale}' locale.`);
             this.#requestedLocale = locale;
@@ -237,16 +272,21 @@ class I18nCore {
         // loaded", which may mean joining a load already in flight.
         return this.#stand(call, this.#route !== undefined ? this.#load(locale, this.#route, call) : Promise.resolve());
     });
-    setRoute = (input) => untrack(() => {
+    /**
+     * With `{ preloaded }`, the token of a `preload()` for the requested locale
+     * and this route, it shows what that preload fetched — see
+     * `loadTranslations()`.
+     */
+    setRoute = (input, options) => untrack(() => {
         if (this.#inert('setRoute'))
             return Promise.resolve();
         const route = withoutBasePath(input, this.#config?.basePath);
-        const call = this.#ask();
+        const call = this.#ask({ locale: this.#requestedLocale, route });
         if (route !== this.#route) {
             logger.debug(`Setting '${route}' route.`);
             this.#route = route;
         }
-        return this.#stand(call, this.#requestedLocale !== undefined ? this.#load(this.#requestedLocale, route, call) : Promise.resolve());
+        return this.#stand(call, this.#requestedLocale !== undefined ? this.#load(this.#requestedLocale, route, call, undefined, options?.preloaded) : Promise.resolve());
     });
     /**
      * `{ activate: false }` only fills the tables: it leaves the requested
@@ -257,17 +297,89 @@ class I18nCore {
      * it. It
      * leaves `cache` expiry to the next activating trigger. A loader's
      * `redirect()` or `error()` below 500 rejects it all the same.
+     *
+     * `{ preloaded }` hands an activating call the token of a `preload()` for
+     * the same locale and route. The call then evaluates no `cache` window — the
+     * preload did — and shows what the preload fetched instead of fetching it
+     * again, at once when nothing else is left to fetch, and otherwise with the
+     * rest, in one go. It fetches what the preload did not deliver, and what it
+     * delivered to a loader that shows something else since — a seed or
+     * another delivery replaced what it showed — wherever the call has that
+     * loader to load anyway (one with `cache: false`, or one whose record an
+     * expiry dropped, say). A token serves one call: the first activating call
+     * that reads it spends it, whether or not it serves that call, even with
+     * nothing left to fetch; a call left without a locale to show — handed an
+     * empty one or one nothing serves, say — reads none. Another instance's,
+     * one of another locale or route, one spent already and one older than a
+     * `loadConfig()` or an `invalidate()` are ignored, as is any with
+     * `{ activate: false }`, which leaves it unspent. A window a later request
+     * found elapsed does not void it: the preload judged the window at its own
+     * request.
      */
-    loadTranslations = (locale, route, { activate = true } = {}) => untrack(() => {
+    loadTranslations = (locale, route, { activate = true, preloaded } = {}) => untrack(() => {
         if (!locale || this.#inert('loadTranslations') || this.#unserved(locale))
             return Promise.resolve();
         const target = route === undefined ? this.#route ?? '' : withoutBasePath(route, this.#config?.basePath);
         if (!activate)
             return this.#load(locale, target);
-        const call = this.#ask();
+        const call = this.#ask({ locale, route: target });
         this.#requestedLocale = locale;
         this.#route = target;
-        return this.#stand(call, this.#load(locale, target, call));
+        return this.#stand(call, this.#load(locale, target, call, undefined, preloaded));
+    });
+    /**
+     * A request for `locale` on `route` (the current route by default) that
+     * shows nothing new by itself: what a router's `load` runs ahead of a
+     * navigation, a hover's included. Like an activating call it evaluates the
+     * `cache` window, ends the pass a hand-off serves, and runs a loader with
+     * `cache: false` — sharing a fetch of it for the same params and route
+     * already in flight. Like `{ activate: false }` it writes neither the locale
+     * nor the route, does not count towards `loading`, and lands what it fetched
+     * as a warm load does. It resolves to a token for the next activating call of
+     * that locale and route, which shows what it fetched (see
+     * `loadTranslations()`), and to `undefined` once the instance was destroyed
+     * or when nothing serves the locale. A loader's `redirect()` or `error()`
+     * below 500 rejects it, unless it shares its load with an activating call,
+     * whose outcome it then gets; one nobody awaits never becomes an unhandled
+     * rejection.
+     */
+    preload = (locale, route) => untrack(() => {
+        const resolved = !locale || this.#inert('preload') || this.#unserved(locale) ? undefined : this.#resolveLocale(locale);
+        if (!resolved)
+            return Promise.resolve(undefined);
+        const target = route === undefined ? this.#route ?? '' : withoutBasePath(route, this.#config?.basePath);
+        this.#invalidateExpired(resolved, this.#config?.fallbackLocale);
+        this.#handedOff.clear();
+        const config = this.#config;
+        const epoch = this.#epoch;
+        const matching = this.#matchLoaders(resolved, target);
+        const key = this.#inflightKey(resolved, target, matching);
+        const requests = this.#unloaded(matching);
+        const fresh = requests.filter(({ loader }) => loader.cache === false);
+        const fetching = new Set(this.#fetches);
+        const isFresh = ({ request }) => fresh.some(({ loader, signature }) => request.loader === loader && request.signature === signature);
+        const earlier = Array.from(this.#inflight).filter(({ fetches }) => fetches.some((fetch) => fetch.route !== target && isFresh(fetch)));
+        // A fetch of a loader with `cache: false` that delivered before the request
+        // is no answer to it, so a load that holds one is not joined.
+        const joinable = requests.length ? this.#joinable(key, requests) : undefined;
+        const joined = joinable?.fetches.filter(isFresh).every((fetch) => this.#fetches.has(fetch)) ? joinable : undefined;
+        const entry = joined ?? (requests.length ? this.#start(resolved, target, key, requests, [], []) : undefined);
+        const fetches = entry?.fetches ?? [];
+        const preloaded = (entry?.promise ?? Promise.resolve()).then(() => Promise.all(fetches.map(({ outcome }) => outcome))).then((fetched) => {
+            if (this.#destroyed)
+                return undefined;
+            const answers = requests.flatMap(({ loader, signature }) => {
+                const index = fetches.findIndex(({ request }) => request.loader === loader && request.signature === signature);
+                const [delivery] = fetched[index]?.deliveries ?? [];
+                const shared = loader.cache === false && (joined !== undefined || fetching.has(fetches[index]));
+                return delivery ? [{ delivery, shown: this.#deliveries.get(loader), shared }] : [];
+            });
+            const token = Object.freeze(Object.create(null));
+            this.#preloads.set(token, { config, epoch, locale: resolved, route: target, answers, earlier: earlier.filter((load) => this.#inflight.has(load)) });
+            return token;
+        });
+        preloaded.catch(() => undefined);
+        return preloaded;
     });
     /**
      * Loads one namespace for the active locale (or `locale`), whatever the
@@ -318,6 +430,8 @@ class I18nCore {
      * expiry leaves it alone.
      */
     #invalidate(sanitized, namespace, { expiry = false } = {}) {
+        if (!expiry)
+            this.#epoch += 1;
         const locales = sanitized === undefined ? Object.keys(this.#namespaceRecords) : [sanitized];
         locales.forEach((recorded) => {
             if (namespace === undefined)
@@ -441,7 +555,7 @@ class I18nCore {
             let kept = relevant;
             if (relevant !== handable) {
                 logger.warn(`Leaving a '__proto__' key of locale '${locale}' out of the snapshot: load data cannot carry it.`);
-                const lost = Object.keys(handable).filter((key) => !hasOwn(relevant, key) || relevant[key] !== handable[key]);
+                const lost = Object.keys(handable).filter((key) => !hasOwn(relevant, key) || !Object.is(relevant[key], handable[key]));
                 stripped.set(locale, lost);
                 // The namespace goes without its record, whole: data plain or unrecorded
                 // is kept on the client as data no loader delivered, which a plain
@@ -506,16 +620,10 @@ class I18nCore {
     };
     // -- internals --------------------------------------------------------------
     #translate(locale, key, params) {
-        const { parser, fallbackLocale, ...rest } = this.#config ?? {};
-        return translate({
-            parser,
-            key,
-            params,
-            translations: this.#translations,
-            locale,
-            fallbackLocale,
-            ...(hasOwn(rest, 'fallbackValue') ? { fallbackValue: rest.fallbackValue } : {}),
-        });
+        const config = this.#config;
+        const translations = this.#translations;
+        const fallbackLocale = config?.fallbackLocale;
+        return translate(config, locale, key, params, locale ? read(translations, locale) : undefined, fallbackLocale ? read(translations, fallbackLocale) : undefined);
     }
     /**
      * The fetches of `requests` from `route`, WITHOUT applying their data: each
@@ -600,16 +708,21 @@ class I18nCore {
      * supplied without a loader and from what each of its loaders last
      * delivered, so no key its source dropped survives and a sibling's part
      * stays in place. The preprocessed table of a
-     * locale that lost data is derived again from the raw one, since a custom
-     * `preprocess` may have renamed the keys that would have to go. Both tables
-     * are computed before anything is written, so a `preprocess` that throws
+     * locale that lost data is derived whole from the merged raw one, never
+     * merged, since a custom `preprocess` may have renamed the keys that would
+     * have to go and that table is what `preprocess` makes of the raw one. Both
+     * tables are computed before anything is written, so a `preprocess` that throws
      * records no loader and the next trigger fetches it again.
      */
     #applyDeliveries(applied) {
-        const { loaders = [] } = this.#config ?? {};
         // One load, however its deliveries were gathered: a preload claimed with
-        // it comes first, yet the loader declared later still wins.
-        const deliveries = [...applied].sort((a, b) => loaders.indexOf(a.loader) - loaders.indexOf(b.loader));
+        // it comes first, yet the loader declared later still wins. Only the order
+        // within a locale matters, so each delivery is placed once, among the
+        // loaders of its own locale.
+        const deliveries = applied
+            .map((delivery) => ({ delivery, position: this.#localeLoaders(delivery.loader.locale).indexOf(delivery.loader) }))
+            .sort((a, b) => a.position - b.position)
+            .map(({ delivery }) => delivery);
         const replaced = deliveries
             .filter(({ loader }) => this.#deliveries.has(loader))
             .map(({ loader }) => loader);
@@ -625,12 +738,13 @@ class I18nCore {
             ...acc,
             [locale]: Object.fromEntries(Object.entries(read(acc, locale) ?? {}).filter(([key]) => !isNamespaceKey(key, namespace))),
         }), this.#rawTranslations);
-        const seeded = this.#merged({ raw, translations: this.#translations }, this.#externalOf(replaced));
+        const derived = unique(replaced.map(({ locale }) => locale));
+        const seeded = this.#merged({ raw, translations: this.#translations }, this.#externalOf(replaced), derived);
         const merged = this.#merged(seeded, serialize([
             ...deliveries.filter(({ loader }) => !isReplaced(loader)),
             ...rebuilt,
-        ].map(({ loader, data }) => ({ ...loader, data }))));
-        const translations = unique(replaced.map(({ locale }) => locale)).reduce((acc, locale) => ({ ...acc, [locale]: this.#preprocess(read(merged.raw, locale)) }), merged.translations);
+        ].map(({ loader, data }) => ({ ...loader, data }))), derived);
+        const translations = derived.reduce((acc, locale) => ({ ...acc, [locale]: this.#preprocess(read(merged.raw, locale)) }), merged.translations);
         deliveries.forEach((delivery) => this.#record(delivery));
         this.#rawTranslations = merged.raw;
         this.#translations = translations;
@@ -662,10 +776,17 @@ class I18nCore {
             const masked = nested === undefined ? delivery.data : maskTranslations(delivery.data, nested) ?? {};
             // Dot notation, as `#preprocess` applies it, merges both spellings of a
             // key into one.
-            const dotted = typeof preprocess !== 'function' && preprocess !== 'none'
+            const dotted = dotNotates(preprocess)
                 ? maskOutputKeys(masked, new Set(Object.keys(toDotNotation(Object.fromEntries(own), preprocess === 'preserveArrays') ?? {})), loader.namespace, preprocess === 'preserveArrays') ?? {}
                 : masked;
-            this.#deliveries.set(loader, { ...delivery, data: dotted });
+            const seeded = { ...delivery, data: dotted };
+            this.#maskedFrom.set(seeded, this.#maskedFrom.get(delivery) ?? delivery);
+            // A call counting on what the loader showed counts on it seeded.
+            this.#inflight.forEach(({ unparked }) => unparked.forEach(({ handed }) => {
+                if (handed?.shown === delivery)
+                    handed.shown = seeded;
+            }));
+            this.#deliveries.set(loader, seeded);
         });
     }
     /**
@@ -772,9 +893,11 @@ class I18nCore {
     /**
      * Both tables with data keyed by sanitized locales merged in. Pure, so a
      * caller that writes only once both are computed keeps them consistent when
-     * a `preprocess` throws.
+     * a `preprocess` throws. `derived` names the locales whose preprocessed
+     * table the caller derives from the merged raw table itself; theirs keeps
+     * its place and is left as it was.
      */
-    #merged(tables, sanitized) {
+    #merged(tables, sanitized, derived = []) {
         logger.debug('Adding translations...');
         const translationLocales = Object.keys(sanitized);
         return {
@@ -782,10 +905,18 @@ class I18nCore {
                 ...acc,
                 [locale]: mergeTranslations(read(acc, locale) || {}, read(sanitized, locale) ?? {}, locale),
             }), tables.raw),
-            translations: translationLocales.reduce((acc, locale) => ({
-                ...acc,
-                [locale]: mergeTranslations(read(acc, locale) || {}, this.#preprocess(read(sanitized, locale)), locale),
-            }), tables.translations),
+            translations: translationLocales.reduce((acc, locale) => {
+                const table = read(acc, locale);
+                if (derived.includes(locale))
+                    return { ...acc, [locale]: table ?? {} };
+                // Checked right before `#preprocess` reads the same config, so the
+                // check and the preprocess that runs agree.
+                const fresh = table === undefined && dotNotates(this.#config?.preprocess);
+                const input = this.#preprocess(read(sanitized, locale));
+                // The dot notation builds the table fresh, so a locale without one yet
+                // takes it as it is.
+                return { ...acc, [locale]: fresh ? input : mergeTranslations(table || {}, input, locale) };
+            }, tables.translations),
         };
     }
     /**
@@ -820,7 +951,7 @@ class I18nCore {
         const { fallbackLocale } = this.#config ?? {};
         if (!inputLocale && !fallbackLocale)
             return undefined;
-        const all = this.locales;
+        const all = this.#served();
         // Nothing to match against yet; sanitizing here would only emit a
         // non-standard warning for a lookup that cannot succeed anyway.
         if (!all.length)
@@ -841,7 +972,7 @@ class I18nCore {
      * known, any request is kept: a config loaded later may serve it.
      */
     #unserved(locale) {
-        if (!this.locales.length || this.#resolveLocale(locale) !== undefined)
+        if (!this.#served().length || this.#resolveLocale(locale) !== undefined)
             return false;
         logger.debug(`Ignoring '${locale}' locale — nothing serves it.`);
         return true;
@@ -883,29 +1014,49 @@ class I18nCore {
     /** The namespaces of `sanitizedLocale` `snapshot()` leaves out — see there. */
     #unsnapshottable(sanitizedLocale, withRecords) {
         const { loaders = [] } = this.#config ?? {};
-        const own = loaders.filter(({ locale }) => locale === sanitizedLocale);
-        return unique(own.map(({ namespace }) => namespace)).filter((namespace) => {
-            const feeding = own.filter((loader) => loader.namespace === namespace);
+        // Grouped in one pass: a filter per namespace would be quadratic in the
+        // number of loaders.
+        const byNamespace = new Map();
+        loaders.forEach((loader) => {
+            if (loader.locale !== sanitizedLocale)
+                return;
+            const feeding = byNamespace.get(loader.namespace);
+            if (feeding)
+                feeding.push(loader);
+            else
+                byNamespace.set(loader.namespace, [loader]);
+        });
+        const named = new Set(read(this.#namespaceRecords, sanitizedLocale));
+        return Array.from(byNamespace).filter(([namespace, feeding]) => {
             const several = feeding.length > 1;
             const params = feeding.some(({ routes }) => capturesParams(routes));
             // Seeded data alone would keep the client's loaders from ever running.
-            const delivered = feeding.some((loader) => this.#loaderRecords.has(loader))
-                || (read(this.#namespaceRecords, sanitizedLocale) || []).includes(namespace);
+            const delivered = feeding.some((loader) => this.#loaderRecords.has(loader)) || named.has(namespace);
             if (!withRecords)
                 return several || params || !delivered;
             // Only a record lets the client replace the data once the params change.
             return params && (several || feeding.some((loader) => loader.id === null || !this.#loaderRecords.has(loader)));
-        });
+        }).map(([namespace]) => namespace);
+    }
+    /** The loaders of `sanitizedLocale` and of the fallback locale, in `loaders` order. */
+    #localeLoaders(sanitizedLocale) {
+        const config = this.#config;
+        if (this.#byLocale.config !== config)
+            this.#byLocale = { config, loaders: new Map() };
+        const known = this.#byLocale.loaders.get(sanitizedLocale);
+        if (known)
+            return known;
+        const { loaders = [], fallbackLocale } = config ?? {};
+        const selected = loaders.filter(({ locale }) => locale === sanitizedLocale || locale === fallbackLocale);
+        this.#byLocale.loaders.set(sanitizedLocale, selected);
+        return selected;
     }
     /**
      * The loaders of `sanitizedLocale` (and the fallback locale) whose routes
      * match `route`, with the params the route yields for each.
      */
     #matchLoaders(sanitizedLocale, route) {
-        const { loaders = [], fallbackLocale } = this.#config ?? {};
-        return loaders.flatMap((loader) => {
-            if (loader.locale !== sanitizedLocale && loader.locale !== fallbackLocale)
-                return [];
+        return this.#localeLoaders(sanitizedLocale).flatMap((loader) => {
             const params = routeParams(loader.routes, route);
             return params ? [{ loader, params, signature: paramsSignature(params) }] : [];
         });
@@ -917,12 +1068,9 @@ class I18nCore {
      * delivered last serves; only a loader with no record is asked, for none.
      */
     #matchNamespace(sanitizedLocale, namespace, route) {
-        const { loaders = [], fallbackLocale } = this.#config ?? {};
-        return loaders.flatMap((loader) => {
+        return this.#localeLoaders(sanitizedLocale).flatMap((loader) => {
             if (loader.namespace !== namespace)
                 return [];
-            if (loader.locale !== sanitizedLocale && loader.locale !== fallbackLocale)
-                return [];
             const params = routeParams(loader.routes, route);
             if (params)
                 return [{ loader, params, signature: paramsSignature(params) }];
@@ -963,22 +1111,24 @@ class I18nCore {
      * keep params its route asked for. Returns what it replaced.
      */
     #want(matching) {
-        const { loaders = [] } = this.#config ?? {};
-        const wants = new Map([
-            ...loaders.map((loader) => [loader, null]),
-            ...matching.map(({ loader, signature }) => [loader, signature]),
-        ]);
-        const replaced = new Map(Array.from(wants.keys(), (loader) => [loader, this.#wanted.get(loader)]));
-        wants.forEach((signature, loader) => this.#wanted.set(loader, signature));
+        const replaced = this.#wanted;
+        this.#wanted = { config: this.#config, signatures: new Map(matching.map(({ loader, signature }) => [loader, signature])) };
         return replaced;
     }
+    /** The params the next trigger asks `loader` for: `null` for none, `undefined` for any. */
+    #wantedOf(loader) {
+        const { config, signatures } = this.#wanted;
+        if (config === undefined || config !== this.#config)
+            return undefined;
+        return signatures.get(loader) ?? null;
+    }
     /**
-     * Starts an activating call: keeps the requested locale and the route it is
-     * about to replace — with the params `#load` adds, what is put back should
-     * it fail.
+     * Starts an activating call of the request `asked`: keeps the requested
+     * locale and the route it is about to replace — with the params `#load`
+     * adds, what is put back should it fail.
      */
-    #ask() {
-        const call = { replaced: { requestedLocale: this.#requestedLocale, route: this.#route, wanted: new Map() }, failed: false, threw: [], resumed: false };
+    #ask(asked) {
+        const call = { asked, replaced: { requestedLocale: this.#requestedLocale, route: this.#route }, failed: false, threw: [], resumed: false };
         this.#calls = [...this.#calls, call];
         return call;
     }
@@ -1008,15 +1158,24 @@ class I18nCore {
         });
         const before = { locale: this.#requestedLocale, route: this.#route };
         let threw;
+        // What the calls whose route stands asked for: an undo back to one of
+        // those requests puts back a request that failed.
+        let standing = [];
         for (let last = this.#calls.at(-1); last?.failed; last = this.#calls.at(-1)) {
+            if (last.routeStands)
+                standing = [...standing, last.asked];
             this.#undo(last);
             this.#calls = this.#calls.slice(0, -1);
             threw = [...threw ?? [], ...last.threw];
         }
         if (!threw)
             return undefined;
-        this.#rewant();
-        const changed = before.locale !== this.#requestedLocale || before.route !== this.#route;
+        // Back at a request that failed: what is shown keeps its records, and it
+        // is not loaded again by itself.
+        const resolved = this.#resolveLocale(this.#requestedLocale);
+        const again = standing.some(({ locale, route }) => route === this.#route && this.#resolveLocale(locale) === resolved);
+        this.#rewant(!again);
+        const changed = !again && (before.locale !== this.#requestedLocale || before.route !== this.#route);
         if (changed) {
             const onRoute = this.#route ? ` on '${this.#route}' route` : '';
             logger.debug(`Undoing the failed calls: the request is back to '${this.#requestedLocale}' locale${onRoute}.`);
@@ -1026,33 +1185,48 @@ class I18nCore {
     /**
      * Puts back what a failed call replaced. Whichever of the locale and the
      * route was not asked for before it stands: it is all there is for the next
-     * trigger to load.
+     * trigger to load. Of a call whose route stands, only the locale goes back.
      */
-    #undo({ replaced: { requestedLocale, route, wanted } }) {
+    #undo({ replaced: { requestedLocale, route, wanted }, routeStands }) {
         if (requestedLocale !== undefined)
             this.#requestedLocale = requestedLocale;
+        if (routeStands)
+            return;
         if (route !== undefined)
             this.#route = route;
-        wanted.forEach((signature, loader) => {
-            if (signature === undefined)
-                this.#wanted.delete(loader);
-            else
-                this.#wanted.set(loader, signature);
-        });
+        if (wanted)
+            this.#wanted = wanted;
+    }
+    /**
+     * Fails the calls whose data could not be applied, as control flow fails
+     * them, except that the route stands, whichever undo reaches them or a call
+     * before them: the caller is on it already. A request put back for that
+     * route is loaded there; one that is the same request again is not, as its
+     * data is what failed.
+     */
+    #failApply(calls) {
+        const last = Math.max(...calls.map((call) => this.#calls.indexOf(call)));
+        this.#calls.slice(0, last + 1).forEach((call) => { call.routeStands = true; });
+        const undone = this.#fail(calls, []);
+        if (undone?.changed)
+            this.#settleUndo(undone);
     }
     /**
      * The loaders the request an undo left in place selects: wanted for the
      * params its route yields, and no longer recorded as loaded for others —
      * whatever another load delivered for them meanwhile stays displayed until
-     * the request loads them again. Runs before the failed load applies what
-     * its other loaders delivered, so that is filtered by what is wanted now.
+     * the request loads them again, unless `drop` is off. Runs before the
+     * failed load applies what its other loaders delivered, so that is filtered
+     * by what is wanted now.
      */
-    #rewant() {
+    #rewant(drop) {
         const locale = this.#resolveLocale(this.#requestedLocale);
         if (!locale || this.#route === undefined)
             return;
         const matching = this.#matchLoaders(locale, this.#route);
         this.#want(matching);
+        if (!drop)
+            return;
         matching.forEach(({ loader, signature }) => {
             if (this.#loaderRecords.has(loader) && this.#loaderRecords.get(loader) !== signature)
                 this.#loaderRecords.delete(loader);
@@ -1084,14 +1258,22 @@ class I18nCore {
             const activating = Array.from(this.#inflight).some((entry) => entry.key === key && entry.calls.length && !entry.severed.size && entry.config === this.#config);
             if (activating)
                 return;
-            this.#applyWanted(this.#claimParked(matching).map(({ delivery }) => delivery));
+            // No caller waits on it: what fails here is logged, and never replaces
+            // what the failed load rejects with.
+            try {
+                this.#applyWanted(this.#claimParked(matching).map(({ delivery }) => delivery));
+            }
+            catch (error) {
+                logError(loadFailure(locale, route), error);
+                return;
+            }
             this.#activate(locale);
             return;
         }
         const threw = missing.some(({ loader, signature }) => controlFlow.some((flow) => flow.loader === loader && flow.signature === signature));
         if (!changed || threw)
             return;
-        const call = this.#ask();
+        const call = this.#ask({ locale: this.#requestedLocale, route });
         void this.#stand(call, this.#load(locale, route, call));
     }
     /**
@@ -1125,16 +1307,17 @@ class I18nCore {
      * activating `call` — never registers either, until an activating trigger
      * joins it.
      */
-    #load(requestedLocale, route, call, namespace) {
+    #load(requestedLocale, route, call, namespace, preloaded) {
         const locale = this.#resolveLocale(requestedLocale);
         if (!locale)
             return Promise.resolve();
+        const preload = call ? this.#preloadOf(preloaded, locale, route) : undefined;
         // Expiry is evaluated per activating trigger, BEFORE the in-flight check.
         // That order is safe: a locale is stamped only once its data arrived, so a
         // shared in-flight load cannot be invalidated by its own duplicates. A
         // warm trigger fills the tables and leaves their freshness to the next
-        // activating one.
-        if (call)
+        // activating one, and a call with a preload's token to that preload.
+        if (call && !preload)
             this.#invalidateExpired(locale, this.#config?.fallbackLocale);
         const matching = namespace === undefined ? this.#matchLoaders(locale, route) : this.#matchNamespace(locale, namespace, route);
         // Recorded before the in-flight check, so a trigger joining a load, or one
@@ -1143,7 +1326,36 @@ class I18nCore {
             call.replaced.wanted = this.#want(matching);
             this.#passHandOff(locale, route);
         }
-        return this.#loadSelection(locale, route, this.#inflightKey(locale, route, matching), matching, call ? [call] : []);
+        return this.#loadSelection(locale, route, this.#inflightKey(locale, route, matching), matching, call ? [call] : [], preload);
+    }
+    /** What `token` stands for while it serves a call for `locale` on `route`. A call reads it once, used or not. */
+    #preloadOf(token, locale, route) {
+        if (!token)
+            return undefined;
+        const preload = this.#preloads.get(token);
+        this.#preloads.delete(token);
+        if (preload && preload.config === this.#config && preload.epoch === this.#epoch && preload.locale === locale && preload.route === route)
+            return preload;
+        logger.debug('Ignoring a preload token that does not serve this call.');
+        return undefined;
+    }
+    /**
+     * The requests `preload` answered: while the loader shows what it showed as
+     * the preload resolved, or the answer itself, and — for a loader with
+     * `cache: false` — no load of another route that was fetching it then is
+     * still in flight, to land after the answer.
+     */
+    #answered({ answers, earlier }, requests) {
+        return requests.flatMap((request) => {
+            const { loader, signature } = request;
+            const answer = answers.find(({ delivery }) => delivery.loader === loader && delivery.signature === signature);
+            const shown = this.#deliveries.get(loader);
+            if (!answer || (shown !== answer.shown && shown !== answer.delivery))
+                return [];
+            const overtaken = loader.cache === false && earlier.some((load) => this.#inflight.has(load) && !load.severed.has(loader)
+                && load.fetches.some((fetch) => fetch.request.loader === loader && fetch.request.signature === signature));
+            return overtaken ? [] : [{ request, answer }];
+        });
     }
     /**
      * The key of a load in flight: what the trigger selected and the route it
@@ -1152,27 +1364,81 @@ class I18nCore {
      * navigation to it would wait on itself.
      */
     #inflightKey(locale, route, matching) {
-        const { loaders = [] } = this.#config ?? {};
-        return JSON.stringify([locale, route, ...matching.map(({ loader, signature }) => [loaders.indexOf(loader), signature])]);
+        const candidates = this.#localeLoaders(locale);
+        return JSON.stringify([locale, route, ...matching.map(({ loader, signature }) => [candidates.indexOf(loader), signature])]);
     }
-    /** Joins the load in flight under `key` that delivers what `selected` lacks, or starts one. */
-    #loadSelection(locale, route, key, selected, calls) {
-        const requests = this.#unloaded(selected);
-        const unparked = calls.length ? this.#claimParked(selected) : [];
+    /**
+     * Joins the load in flight under `key` that delivers what `selected` lacks,
+     * or starts one. What `preload` answered lands with it instead of being
+     * fetched.
+     */
+    #loadSelection(locale, route, key, selected, calls, preload) {
+        const unloaded = this.#unloaded(selected);
+        const answered = preload ? this.#answered(preload, unloaded) : [];
+        const requests = answered.length ? unloaded.filter((request) => !answered.some((answer) => answer.request === request)) : unloaded;
+        const handed = answered
+            .filter(({ request, answer }) => this.#deliveries.get(request.loader) !== answer.delivery)
+            .map(({ request, answer }) => ({ request, delivery: answer.delivery, handed: { shown: answer.shown } }));
+        const unparked = calls.length ? [...this.#claimParked(selected), ...handed] : [];
+        const refresh = answered.filter(({ answer }) => answer.shared);
+        if (calls.length)
+            this.#rerecord(answered.map(({ answer }) => answer.delivery).filter((delivery) => this.#deliveries.get(delivery.loader) === delivery));
         if (!requests.length) {
             // Nothing to fetch — the locale still becomes active (its data is
             // already present, parked or it has no loaders).
             if (calls.length) {
-                this.#applyWanted(unparked.map(({ delivery }) => delivery));
+                try {
+                    this.#applyWanted(unparked.map(({ delivery }) => delivery));
+                }
+                catch (error) {
+                    logError(loadFailure(locale, route), error);
+                    this.#failApply(calls);
+                    // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- passed on as thrown
+                    const promise = Promise.reject(error);
+                    promise.catch(() => undefined);
+                    return promise;
+                }
                 this.#activate(locale);
             }
+            this.#refresh(locale, route, refresh);
             return Promise.resolve();
         }
-        // What is parked lands with the load, so a call it fails puts it back.
-        const inflight = this.#joinable(key, requests);
+        // What is parked lands with the load, so a call it fails puts it back. A
+        // load in flight may deliver what the token answered a second time.
+        const inflight = answered.length ? undefined : this.#joinable(key, requests);
         if (inflight)
             return this.#join(inflight, calls, unparked);
-        return this.#start(locale, route, key, requests, calls, unparked);
+        const { promise } = this.#start(locale, route, key, requests, calls, unparked);
+        if (refresh.length)
+            promise.then(() => this.#refresh(locale, route, refresh), () => undefined);
+        return promise;
+    }
+    /**
+     * Records again what a preload showed itself and an expiry since dropped the
+     * records of: the preload judged the window at its request.
+     */
+    #rerecord(shown) {
+        const dropped = shown.filter(({ loader, signature }) => this.#loaderRecords.get(loader) !== signature);
+        dropped.forEach(({ loader, signature }) => this.#loaderRecords.set(loader, signature));
+        this.#stamp(dropped.filter(({ loader }) => loader.cache !== false).map(({ loader }) => loader.locale));
+    }
+    /**
+     * Fetches again, as a warm load, what a call showed from a preload's shared
+     * fetch: that fetch started before the preload's request. Only while it is
+     * shown and its params are still wanted — a later delivery is no older than
+     * the request.
+     */
+    #refresh(locale, route, answered) {
+        const requests = this.#destroyed ? [] : answered
+            .filter(({ request, answer }) => this.#shows(request.loader, answer.delivery) && this.#isWanted(request))
+            .map(({ request }) => request);
+        if (requests.length)
+            void this.#loadSelection(locale, route, this.#inflightKey(locale, route, requests), requests, []);
+    }
+    /** Whether `loader` still shows `delivery`, seeded or not. A reconfiguration replaces every delivery. */
+    #shows(loader, delivery) {
+        const shown = this.#deliveries.get(loader);
+        return shown !== undefined && (this.#maskedFrom.get(shown) ?? shown) === delivery;
     }
     /** The load in flight under `key` that delivers every one of `requests`. */
     #joinable(key, requests) {
@@ -1199,7 +1465,7 @@ class I18nCore {
      * before a trigger asked.
      */
     #isWanted({ loader, signature }) {
-        const wanted = this.#wanted.get(loader);
+        const wanted = this.#wantedOf(loader);
         if (wanted === undefined)
             return true;
         return (wanted ?? '') === signature;
@@ -1210,11 +1476,12 @@ class I18nCore {
      * others: a warm load parks what would replace it, unless it asks for no
      * params — `loadNamespace()` off the loader's routes. What an activating load
      * counts on stays parked until it settles. A loader with `cache: false` runs
-     * on every trigger that selects it, so nothing of it is parked.
+     * on every trigger that selects it, so nothing of it is parked. What fails
+     * to apply is fetched again.
      */
     #applyWanted(deliveries) {
         const wanted = deliveries.filter(({ loader, signature }) => {
-            const wanted = this.#wanted.get(loader);
+            const wanted = this.#wantedOf(loader);
             if (typeof wanted === 'string')
                 return wanted === signature;
             const previous = this.#deliveries.get(loader);
@@ -1225,8 +1492,25 @@ class I18nCore {
             && !this.#claimed(delivery.loader));
         parked.forEach((delivery) => this.#parked.set(delivery.loader, delivery));
         this.#stamp(parked.map(({ loader }) => loader.locale));
-        if (wanted.length)
+        if (!wanted.length)
+            return;
+        try {
             this.#applyDeliveries(wanted);
+        }
+        catch (error) {
+            // Parked no more, so the next trigger fetches it again, and a load in
+            // flight that claimed it fetches it again as a severed one.
+            wanted.forEach((delivery) => {
+                if (this.#parked.get(delivery.loader) !== delivery)
+                    return;
+                this.#parked.delete(delivery.loader);
+                this.#inflight.forEach((entry) => {
+                    if (entry.unparked.some((claim) => claim.delivery === delivery))
+                        entry.severed.add(delivery.loader);
+                });
+            });
+            throw error;
+        }
     }
     /** Takes the fetches `entry` waited on out of the table, once what they delivered is applied or parked. */
     #release({ fetches }) {
@@ -1300,12 +1584,21 @@ class I18nCore {
             // `destroy()` — that raced this load severed some of its loaders. Their
             // data predates the invalidation: applying it would resurrect the
             // dropped bookkeeping and permanently suppress the promised refetch.
-            const current = deliveries.filter(({ loader }) => !entry.severed.has(loader));
+            const claims = entry.unparked.filter(({ request }) => !entry.severed.has(request.loader));
             // What it counts on applies while still parked: a newer record of the
-            // same params dropped it, and an invalidation severed it.
-            const held = entry.unparked
-                .filter(({ request, delivery }) => !entry.severed.has(request.loader) && this.#parked.get(request.loader) === delivery)
+            // same params dropped it, and an invalidation severed it. What a token
+            // handed it applies while the loader shows what it showed at the call;
+            // a delivery of other params since is fetched again, as a severed
+            // loader is, and one of the same params stands.
+            const held = claims
+                .filter(({ request, delivery, handed }) => (handed ? this.#deliveries.get(request.loader) === handed.shown : this.#parked.get(request.loader) === delivery))
                 .map(({ delivery }) => delivery);
+            claims.forEach(({ request: { loader }, delivery, handed }) => {
+                const shown = this.#deliveries.get(loader);
+                if (handed && shown !== handed.shown && shown?.signature !== delivery.signature)
+                    entry.severed.add(loader);
+            });
+            const current = deliveries.filter(({ loader }) => !entry.severed.has(loader));
             const served = [...requests, ...entry.unparked.map(({ request }) => request)];
             rejection = this.#rejection(entry, locale, controlFlow);
             // The calls that share the load failed, whether its control flow rejects
@@ -1323,15 +1616,17 @@ class I18nCore {
             }
             catch (error) {
                 if (rejection)
-                    logError(`Failed to load translations for '${locale}' locale${onRoute}.`, error);
+                    logError(loadFailure(locale, route), error);
                 else
                     failure = { error };
             }
             this.#release(entry);
             if (undone)
                 this.#settleUndo(undone);
-            if (failure)
+            if (failure) {
+                this.#failApply(entry.calls);
                 throw failure.error;
+            }
             if (rejection)
                 throw rejection.value;
             // A load of params the route no longer asks for, whatever it returned,
@@ -1356,7 +1651,7 @@ class I18nCore {
             }
             logError(rejection
                 ? `Rejecting the load of '${locale}' locale${onRoute} with what the ${loaderName(rejection.loader)} loader threw.`
-                : `Failed to load translations for '${locale}' locale${onRoute}.`, error);
+                : loadFailure(locale, route), error);
         });
         // Resumed once per call: a loader that invalidates what it loads each time
         // it runs would otherwise be fetched again for as long as it keeps doing
@@ -1377,7 +1672,7 @@ class I18nCore {
         // Also marks the load handled, so one nobody awaits cannot terminate the
         // process; an awaiting caller still receives the rejection.
         promise.then(settle, settle);
-        return promise;
+        return entry;
     }
     /**
      * Finishes an activating load an invalidation cut `severed` off: it fetches