@sveltekit-i18n/base 3.2.0 → 3.3.1

package/README.md

@@ -34,9 +34,9 @@ Core i18n functionality for SvelteKit with support for custom message parsers. T
 
 Svelte 5 or newer, and one of Node 22+, Bun 1.2+ or Deno 2+. The package is
 ESM-only and imports no `node:` module, so every runtime that runs your
-SvelteKit build runs it. The [`/kit`](#sveltekit) subpath needs SvelteKit 2;
-the SvelteKit behaviour the docs describe is checked against 2.70 and the 3.0
-prerelease.
+SvelteKit build runs it. The [`/kit`](#sveltekit) subpath needs SvelteKit 2
+or 3; the SvelteKit behaviour the docs describe is checked against 2.70 and
+3.0.
 
 ## Installation
 
@@ -91,20 +91,26 @@ export const { handle, load, use, get } = defineI18n(config);
 
 ### 3. Wire it into SvelteKit
 
+`#lib` is the `imports` entry `sv create` scaffolds in a SvelteKit 3 app's
+`package.json`. A SvelteKit 2 app adds the same entry,
+`"imports": { "#lib/*": "./src/lib/*" }`, or imports from `$lib/i18n` — as
+it must on Vite 5 when `i18n` is a `.ts` file imported from a `.js` module or
+a plain `<script>`.
+
 ```javascript
 // src/hooks.server.js
-export { handle } from '$lib/i18n';
+export { handle } from '#lib/i18n.js';
 ```
 
 ```javascript
 // src/routes/+layout.server.js and src/routes/+layout.js — the same line in both
-export { load } from '$lib/i18n';
+export { load } from '#lib/i18n.js';
 ```
 
 ```svelte
 <!-- src/routes/+layout.svelte -->
 <script>
-  import { use } from '$lib/i18n';
+  import { use } from '#lib/i18n.js';
 
   let { data, children } = $props();
 
@@ -122,15 +128,15 @@ export { load } from '$lib/i18n';
 The server picks the visitor's locale from the `Accept-Language` header (or
 from a cookie, with `preferredLocale`), loads it per request and hands it to
 the browser, so nothing loads twice and no visitor sees another's locale. See
-[SvelteKit](https://github.com/sveltekit-i18n/base/blob/3.2.0/docs/README.md#sveltekit) for the details and
-[Server-Side Rendering](https://github.com/sveltekit-i18n/base/blob/3.2.0/docs/README.md#server-side-rendering) for wiring it
+[SvelteKit](https://github.com/sveltekit-i18n/base/blob/3.3.1/docs/README.md#sveltekit) for the details and
+[Server-Side Rendering](https://github.com/sveltekit-i18n/base/blob/3.3.1/docs/README.md#server-side-rendering) for wiring it
 by hand.
 
 ### 4. Use in components
 
 ```svelte
 <script>
-  import { get } from '$lib/i18n';
+  import { get } from '#lib/i18n.js';
 
   const i18n = get();
 </script>
@@ -232,30 +238,29 @@ A named capture group in a `RegExp` route is a load parameter: its match reaches
 }
 ```
 
-`API_ORIGIN` stands for an origin such as `https://api.example.com`: a loader runs on the server too, where `fetch` takes only an absolute URL. See [route params](https://github.com/sveltekit-i18n/base/blob/3.2.0/docs/README.md#route-params) for the rules.
+`API_ORIGIN` stands for an origin such as `https://api.example.com`: a loader runs on the server too, where `fetch` takes only an absolute URL. See [route params](https://github.com/sveltekit-i18n/base/blob/3.3.1/docs/README.md#route-params) for the rules.
 
-A loader whose source does the caching itself — a SvelteKit remote `query`, an SWR layer, an HTTP cache — sets `cache: false`. It then runs on every load trigger that selects it, and `config.cache` does not apply to it; only a hydrated snapshot holds it back, for the locale and route it was rendered for. See [the loader's `cache`](https://github.com/sveltekit-i18n/base/blob/3.2.0/docs/README.md#cache-optional).
+A loader whose source does the caching itself — a SvelteKit remote `query`, an SWR layer, an HTTP cache — sets `cache: false`. It then runs on every load trigger that selects it, sharing a fetch of it already in flight for the same params and route, and `config.cache` does not apply to it; only a hydrated snapshot holds it back, for the locale and route it was rendered for, until another locale or route is requested or a `preload()` runs, and a call handed a [`preload()`](https://github.com/sveltekit-i18n/base/blob/3.3.1/docs/README.md#preloadlocale-route) token shows what that preload fetched instead of running it again. See [the loader's `cache`](https://github.com/sveltekit-i18n/base/blob/3.3.1/docs/README.md#cache-optional).
 
-A loader that throws is logged, and the rest of the load lands without its data; it runs again on the next load trigger. SvelteKit's `redirect()` and an `error()` below 500 (told by their shape: an own `status` with a `location` or a `body`, on a value that is not an `Error`) are logged too, but they also reject the load, so a SvelteKit `load` awaiting the call hands them to SvelteKit; the rejected call is undone — what it replaced goes back — unless a later call that has not failed came in the meantime. See [the loader](https://github.com/sveltekit-i18n/base/blob/3.2.0/docs/README.md#loader-required).
+A loader that throws is logged, and the rest of the load lands without its data; it runs again on the next load trigger. SvelteKit's `redirect()` and an `error()` below 500 (told by their shape: an own `status` with a `location` or a `body`, on a value that is not an `Error`) are logged too, but they also reject the load, so a SvelteKit `load` awaiting the call hands them to SvelteKit; the rejected call is undone — what it replaced goes back — unless a later call that has not failed came in the meantime. See [the loader](https://github.com/sveltekit-i18n/base/blob/3.3.1/docs/README.md#loader-required).
 
 Both `loaders` and a loader's `routes` accept readonly arrays, so a whole-config `as const` is fine.
 
 ### `basePath`
 
-The path the app is served under — SvelteKit's `kit.paths.base`. Every route handed in loses it on the way in, on a segment boundary only (under `/repo`, `/repo/about` is `/about`), so loader `routes` name the app's own paths. Set both from one environment variable:
+The path the app is served under — SvelteKit's `paths.base`. Every route handed in loses it on the way in, on a segment boundary only (under `/repo`, `/repo/about` is `/about`), so loader `routes` name the app's own paths. Set both from one environment variable:
 
 ```javascript
-// svelte.config.js: kit: { paths: { base: process.env.PUBLIC_BASE_PATH ?? '' } }
-import { PUBLIC_BASE_PATH } from '$env/static/public';
-
-basePath: PUBLIC_BASE_PATH
+// SvelteKit 3, vite.config.js: sveltekit({ paths: { base: process.env.VITE_BASE_PATH ?? '' } })
+// SvelteKit 2, svelte.config.js: kit: { paths: { base: process.env.VITE_BASE_PATH ?? '' } }
+basePath: import.meta.env.VITE_BASE_PATH
 ```
 
-See [`basePath`](https://github.com/sveltekit-i18n/base/blob/3.2.0/docs/README.md#basepath).
+See [`basePath`](https://github.com/sveltekit-i18n/base/blob/3.3.1/docs/README.md#basepath).
 
 ### `translations`
 
-Synchronous translations, available immediately. They seed the tables: the loaders of a namespace they name still run and merge into it. Hand a server's state over with [`hydrate()`](https://github.com/sveltekit-i18n/base/blob/3.2.0/docs/README.md#hydrateenvelope) instead:
+Synchronous translations, available immediately. They seed the tables: the loaders of a namespace they name still run and merge into it. Hand a server's state over with [`hydrate()`](https://github.com/sveltekit-i18n/base/blob/3.3.1/docs/README.md#hydrateenvelope) instead:
 
 ```javascript
 translations: {
@@ -273,7 +278,7 @@ The initial locale, used when nothing else decides:
 initLocale: 'en'
 ```
 
-With [`defineI18n()`](#sveltekit) it is the locale a visitor gets when nothing they prefer is served, and it loads only when negotiation picks it ([Which locale](https://github.com/sveltekit-i18n/base/blob/3.2.0/docs/README.md#which-locale)). With `new I18n(config)` the constructor loads it right away, so leave it out of a config whose instance you [`hydrate()`](https://github.com/sveltekit-i18n/base/blob/3.2.0/docs/README.md#hydrateenvelope) by hand — its load starts before the hand-off can be applied.
+With [`defineI18n()`](#sveltekit) it is the locale a visitor gets when nothing they prefer is served, and it loads only when negotiation picks it ([Which locale](https://github.com/sveltekit-i18n/base/blob/3.3.1/docs/README.md#which-locale)). With `new I18n(config)` the constructor loads it right away, so leave it out of a config whose instance you [`hydrate()`](https://github.com/sveltekit-i18n/base/blob/3.3.1/docs/README.md#hydrateenvelope) by hand — its load starts before the hand-off can be applied.
 
 ### `fallbackLocale`
 
@@ -295,7 +300,7 @@ fallbackValue: '...' // Default: returns the key itself
 
 ### `sanitizeLocales`
 
-How locale identifiers are normalized before they key anything: `true` (default) resolves them to their ISO form through `Intl` (`'en-us'` is `'en-US'`), `false` keeps them as authored, and a function normalizes them your way. See [`sanitizeLocales`](https://github.com/sveltekit-i18n/base/blob/3.2.0/docs/README.md#sanitizelocales).
+How locale identifiers are normalized before they key anything: `true` (default) resolves them to their ISO form through `Intl` (`'en-us'` is `'en-US'`), `false` keeps them as authored, and a function normalizes them your way. See [`sanitizeLocales`](https://github.com/sveltekit-i18n/base/blob/3.3.1/docs/README.md#sanitizelocales).
 
 ### `preprocess`
 
@@ -334,11 +339,11 @@ Or state it per instance — only its type is read, so the value can stay empty
 const i18n = new I18n({ ...config, schema: {} as TranslationSchema });
 ```
 
-Hand-write it for a small set of messages, or generate it — [@sveltekit-i18n/typegen](https://github.com/sveltekit-i18n/typegen), a separate package, generates one. A schema whose keys are not a closed set (`schema: {}`) types nothing and keeps the registry out, so keys stay plain strings. A library never registers. The registry needs base 3.1 or newer. See [`schema`](https://github.com/sveltekit-i18n/base/blob/3.2.0/docs/README.md#schema) for the full rules.
+Hand-write it for a small set of messages, or generate it — [@sveltekit-i18n/typegen](https://github.com/sveltekit-i18n/typegen), a separate package, generates one. A schema whose keys are not a closed set (`schema: {}`) types nothing and keeps the registry out, so keys stay plain strings. A library never registers. The registry needs base 3.1 or newer. See [`schema`](https://github.com/sveltekit-i18n/base/blob/3.3.1/docs/README.md#schema) for the full rules.
 
 ### `cache`
 
-Time in milliseconds the loaded translations stay fresh for. By default, loaded translations never expire — each loader (but one with [`cache: false`](https://github.com/sveltekit-i18n/base/blob/3.2.0/docs/README.md#cache-optional)) runs once per locale and [route params](https://github.com/sveltekit-i18n/base/blob/3.2.0/docs/README.md#route-params) (a loader's `routes` decide whether a load trigger considers it, and the params their named groups capture decide when it runs again).
+Time in milliseconds the loaded translations stay fresh for. By default, loaded translations never expire — each loader (but one with [`cache: false`](https://github.com/sveltekit-i18n/base/blob/3.3.1/docs/README.md#cache-optional)) runs once per locale and [route params](https://github.com/sveltekit-i18n/base/blob/3.3.1/docs/README.md#route-params) (a loader's `routes` decide whether a load trigger considers it, and the params their named groups capture decide when it runs again).
 
 Set a finite value when your loaders fetch from a source that can change at runtime (e.g. a CMS):
 
@@ -346,7 +351,7 @@ Set a finite value when your loaders fetch from a source that can change at runt
 cache: 3600000 // Translations older than 1 hour refetch on the next activating load
 ```
 
-Expiry is evaluated by the next activating load trigger (`setLocale`, `setRoute`, `loadTranslations`); a warm load — `loadTranslations(…, { activate: false })` or `loadNamespace()` — fills the tables without evaluating it. Set to `0` to treat translations as always stale (refetch on every activating load trigger). A loader with `cache: false` is outside the window. You can also drop the loaded state manually at any time with [`invalidate()`](#methods).
+Expiry is evaluated by the next activating load trigger (`setLocale`, `setRoute`, `loadTranslations`) or `preload()`; a warm load — `loadTranslations(…, { activate: false })` or `loadNamespace()` — fills the tables without evaluating it, and a call handed a `preload()` token leaves it to that preload. Set to `0` to treat translations as always stale (refetch on every activating load trigger). A loader with `cache: false` is outside the window. You can also drop the loaded state manually at any time with [`invalidate()`](#methods).
 
 ### `extensions`
 
@@ -405,14 +410,15 @@ log: {
 
 Load-triggering methods return the promise of the matching load — concurrent duplicate triggers from one route share one in-flight load (and its promise) instead of fetching twice.
 
-- `loadTranslations(locale, route?, options?)` – load translations for locale and route; `route` defaults to the current one, and `{ activate: false }` only fills the tables without switching to them
+- `loadTranslations(locale, route?, options?)` – load translations for locale and route; `route` defaults to the current one, `{ activate: false }` only fills the tables without switching to them, and `{ preloaded }` takes a `preload()` token
+- `preload(locale, route?)` – the request of a navigation that may never commit (a router's `load`, a hover's included): it judges freshness and runs `cache: false` loaders as an activating call would, shows nothing, and resolves to a token the commit's `loadTranslations()` or `setRoute()` takes as `{ preloaded }` to show what it fetched instead of fetching it again
 - `loadNamespace(namespace, locale?)` – load one namespace on demand, whatever its loaders' routes, without switching to it; it stays loaded across routes
 - `setLocale(locale)` – request a locale; loads once a route is known
-- `setRoute(route)` – update the current route
+- `setRoute(route, options?)` – update the current route; `{ preloaded }` takes a `preload()` token
 - `loadConfig(config)` – (re)configure the instance
 - `addTranslations(translations)` – seed synchronous translations; the loaders of their namespaces still run and merge into them
 - `snapshot(options?)` – serialize what the active locale (and the fallback) holds; `{ records: true }` returns the envelope `hydrate()` restores, with the loaders that delivered, the active locale and the route, and no argument returns the data alone, shaped like `config.translations`, for a plain `hydrate({ translations })`
-- `hydrate(envelope?)` – restore a server's snapshot: its data, its load records (so those loaders do not run again — one with `cache: false` only for the locale and route it was rendered for), its locale and its route; an envelope without records keeps the loaders of the namespaces its data names from running
+- `hydrate(envelope?)` – restore a server's snapshot: its data, its load records (so those loaders do not run again — one with `cache: false` only for the locale and route it was rendered for, until a `preload()` runs or `invalidate()` covers it), its locale and its route; an envelope without records keeps the loaders of the namespaces its data names from running
 - `invalidate(locale?, namespace?)` – mark loaded translations stale (one locale or all, one namespace or all); loaders run again on the next load trigger, and a loader still in flight for what was invalidated settles with whatever it returns or throws discarded — an activating trigger fetches it again before it activates, unless another loader of its load threw SvelteKit's control flow
 - `destroy()` – detach a per-request or per-component instance: in-flight loads settle discarded, further load and mutation calls are ignored, reads keep working
 
@@ -443,12 +449,12 @@ export const { handle, load, use, get } = defineI18n(config, { preferredLocale }
 - `use(() => data)` – called once in the root `+layout.svelte`; provides the instance, follows every navigation and keeps `<html lang>` and `<html dir>` in sync
 - `get()` – the instance, in any component below the root layout
 
-Full API documentation: [docs/README.md](https://github.com/sveltekit-i18n/base/blob/3.2.0/docs/README.md)
+Full API documentation: [docs/README.md](https://github.com/sveltekit-i18n/base/blob/3.3.1/docs/README.md)
 
 ## Documentation
 
 - 🌐 [sveltekit-i18n.github.io](https://sveltekit-i18n.github.io) – The documentation site, with a live playground
-- 📖 [Full API Documentation](https://github.com/sveltekit-i18n/base/blob/3.2.0/docs/README.md) – Complete reference
+- 📖 [Full API Documentation](https://github.com/sveltekit-i18n/base/blob/3.3.1/docs/README.md) – Complete reference
 - 📚 [Main Library Docs](https://github.com/sveltekit-i18n/lib/tree/master/docs/INDEX.md) – Guides, tutorials, and best practices
 - 🎨 [Parsers](https://github.com/sveltekit-i18n/parsers) – Available parsers and how to create your own
 - 💡 [Examples](https://github.com/sveltekit-i18n/lib/tree/master/examples) – Real-world usage examples
@@ -470,7 +476,7 @@ const config: Config.T<Params> = {
 };
 ```
 
-Two more things are inferred from the config itself. [`schema`](#schema) types the keys and payloads of `t`/`l`, and every locale the config names — loader locales, `initLocale`, `fallbackLocale` and the keys of `translations` — completes the locale arguments and reads (`setLocale`, `loadTranslations`, `loadNamespace`, `invalidate`, `l`, `locale`, `locales`):
+Two more things are inferred from the config itself. [`schema`](#schema) types the keys and payloads of `t`/`l`, and every locale the config names — loader locales, `initLocale`, `fallbackLocale` and the keys of `translations` — completes the locale arguments and reads (`setLocale`, `loadTranslations`, `loadNamespace`, `preload`, `invalidate`, `l`, `locale`, `locales`):
 
 ```typescript
 const i18n = new I18n({ parser: parser({ onReport: null }), initLocale: 'en', fallbackLocale: 'de' });
@@ -479,7 +485,7 @@ i18n.setLocale('en'); // 'en' | 'de' autocomplete here
 i18n.setLocale('sv'); // still accepted — the union is a hint, not a constraint
 ```
 
-The locales survive only when the config reaches the constructor as a literal — inline, as above, or a separate object with `as const`. An annotated or separately widened config, and any config with one dynamic locale source (`loaders: locales.map(...)`), leaves them plain `string`. See [TypeScript](https://github.com/sveltekit-i18n/base/blob/3.2.0/docs/README.md#typescript) for both.
+The locales survive only when the config reaches the constructor as a literal — inline, as above, or a separate object with `as const`. An annotated or separately widened config, and any config with one dynamic locale source (`loaders: locales.map(...)`), leaves them plain `string`. See [TypeScript](https://github.com/sveltekit-i18n/base/blob/3.3.1/docs/README.md#typescript) for both.
 
 ## Related Packages
 

package/dist/I18n.svelte.d.ts

@@ -35,7 +35,14 @@ declare class I18nCore<ParserParams extends Parser.Params = any, ParserOutput =
      */
     loadConfig: (config: Config.T<ParserParams, ParserOutput>) => Promise<void>;
     setLocale: (locale?: Config.LocaleInput<LocaleUnion>) => Promise<void>;
-    setRoute: (input: string) => Promise<void>;
+    /**
+     * With `{ preloaded }`, the token of a `preload()` for the requested locale
+     * and this route, it shows what that preload fetched — see
+     * `loadTranslations()`.
+     */
+    setRoute: (input: string, options?: {
+        preloaded?: Loader.Preloaded | undefined;
+    }) => Promise<void>;
     /**
      * `{ activate: false }` only fills the tables: it leaves the requested
      * locale, the route and `locale` untouched and does not count towards
@@ -45,10 +52,46 @@ declare class I18nCore<ParserParams extends Parser.Params = any, ParserOutput =
      * 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: Config.LocaleInput<LocaleUnion>, route?: string, { activate }?: {
+    loadTranslations: (locale: Config.LocaleInput<LocaleUnion>, route?: string, { activate, preloaded }?: {
         activate?: boolean;
+        preloaded?: Loader.Preloaded | undefined;
     }) => Promise<void>;
+    /**
+     * 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: Config.LocaleInput<LocaleUnion>, route?: string) => Promise<Loader.Preloaded | undefined>;
     /**
      * Loads one namespace for the active locale (or `locale`), whatever the
      * routes of its loaders say — for what an interaction needs rather than a