@sveltekit-i18n/base 3.0.1 → 3.1.0-next.0

package/README.md

@@ -30,10 +30,18 @@ Core i18n functionality for SvelteKit with support for custom message parsers. T
 ✅ **TypeScript** – Locales inferred from your config, keys and payloads from a [`schema`](#schema)  
 ✅ **Zero dependencies** – Lightweight and fast
 
+## Requirements
+
+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.
+
 ## Installation
 
 ```bash
 npm install @sveltekit-i18n/base
+# bun add @sveltekit-i18n/base
+# deno add npm:@sveltekit-i18n/base
 ```
 
 You'll also need a parser:
@@ -42,7 +50,8 @@ You'll also need a parser:
 # Choose one:
 npm install @sveltekit-i18n/parser-curly
 npm install @sveltekit-i18n/parser-icu
-# or create your own
+npm install @sveltekit-i18n/parser-mf2
+npm install @sveltekit-i18n/parser-i18next
 ```
 
 ## Quick Start
@@ -60,70 +69,80 @@ npm install @sveltekit-i18n/parser-icu
 ### 2. Setup with a parser
 
 ```javascript
-// src/lib/translations/index.js
-import { I18n } from '@sveltekit-i18n/base';
+// src/lib/i18n.js
+import { defineI18n } from '@sveltekit-i18n/base/kit';
 import parser from '@sveltekit-i18n/parser-curly';
 
-/** @type {import('@sveltekit-i18n/base').Config.T} */
-const config = {
+export const config = {
   parser: parser({ onReport: null, /* other parser options */ }),
   loaders: [
     {
-      locale: 'en',
-      key: 'common',
-      loader: async () => (await import('./en/common.json')).default,
-    },
-    {
-      locale: 'cs',
-      key: 'common',
-      loader: async () => (await import('./cs/common.json')).default,
+      locale: ['en', 'cs'],
+      namespace: 'common',
+      loader: async ({ locale, namespace }) => (await import(`./translations/${locale}/${namespace}.json`)).default,
     },
   ],
 };
 
-// One reactive instance. Do NOT destructure its value properties — reading
-// them off the instance is what makes templates reactive. (`t`/`l` are
-// functions and stay reactive even when destructured, since the tracked reads
-// happen at call time. In a component, `const { loading } = $derived(i18n)`
-// destructures value reads without losing reactivity.)
-export const i18n = new I18n(config);
+export const { handle, load, use, get } = defineI18n(config);
 ```
 
-### 3. Load translations in your layout
+### 3. Wire it into SvelteKit
 
 ```javascript
-// src/routes/+layout.js
-import { i18n } from '$lib/translations';
+// src/hooks.server.js
+export { handle } from '$lib/i18n';
+```
 
-/** @type {import('./$types').LayoutLoad} */
-export const load = async ({ url }) => {
-  const { pathname } = url;
-  const initLocale = 'en';
+```javascript
+// src/routes/+layout.server.js and src/routes/+layout.js — the same line in both
+export { load } from '$lib/i18n';
+```
 
-  await i18n.loadTranslations(initLocale, pathname);
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script>
+  import { use } from '$lib/i18n';
 
-  return {};
-};
+  let { data, children } = $props();
+
+  use(() => data);
+</script>
+
+{@render children()}
+```
+
+```html
+<!-- src/app.html -->
+<html lang="%lang%" dir="%dir%">
 ```
 
-> **Rendering per-visitor locales on the server?** The instance above is a
-> module-level singleton — on the server it is shared by every request in the
-> process, so concurrent visitors overwrite each other's locale. Use one
-> instance per request and hand its data to the client with `snapshot()`:
-> see [Server-Side Rendering](./docs/README.md#server-side-rendering).
+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](./docs/README.md#sveltekit) for the details and
+[Server-Side Rendering](./docs/README.md#server-side-rendering) for wiring it
+by hand.
 
 ### 4. Use in components
 
 ```svelte
 <script>
-  import { i18n } from '$lib/translations';
+  import { get } from '$lib/i18n';
+
+  const i18n = get();
 </script>
 
 <p>{i18n.t('common.greeting', { name: 'World' })}</p>
 ```
 
 The call reads the reactive translation table and locale, so the text updates
-automatically when either changes — no stores, no `$` prefix.
+automatically when either changes — no stores, no `$` prefix. Do NOT
+destructure the instance's value properties: reading them off the instance is
+what makes templates reactive. (`t`/`l` are functions and stay reactive even
+when destructured, since the tracked reads happen at call time. In a component,
+`const { loading } = $derived(i18n)` destructures value reads without losing
+reactivity.)
 
 ## Using Different Parsers
 
@@ -179,18 +198,47 @@ Array of loader configurations:
 loaders: [
   {
     locale: 'en',           // Required: locale identifier
-    key: 'common',          // Required: translation namespace
+    namespace: 'common',    // Required: translation namespace
     loader: async () => {}, // Required: async function returning translations
     routes: ['/about'],     // Optional: load only for specific routes
   },
 ]
 ```
 
+`locale` and `namespace` each take a list as well. Such a descriptor stands for one loader per locale and namespace pair, and the loader receives the pair it is loading, so one computed loader can replace a descriptor per file:
+
+```javascript
+loaders: [
+  {
+    locale: ['en', 'cs'],
+    namespace: ['common', 'nav'],
+    loader: async ({ locale, namespace }) => (await import(`./${locale}/${namespace}.json`)).default,
+  },
+]
+```
+
+A named capture group in a `RegExp` route is a load parameter: its match reaches the loader as `params`, and the loader runs again when it changes, its new data replacing the old:
+
+```javascript
+{
+  locale: 'en',
+  namespace: 'article',
+  routes: [/^\/article\/(?<articleId>[^/]+)/],
+  loader: async ({ locale, params }) => (await fetch(`/api/articles/${params.articleId}/i18n/${locale}`)).json(),
+}
+```
+
+See [route params](./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`](./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](./docs/README.md#loader-required).
+
 Both `loaders` and a loader's `routes` accept readonly arrays, so a whole-config `as const` is fine.
 
 ### `translations`
 
-Synchronous translations loaded immediately:
+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()`](./docs/README.md#hydrateenvelope) instead:
 
 ```javascript
 translations: {
@@ -256,7 +304,7 @@ Hand-write it for a small set of messages, or point the slot at a generated arti
 
 ### `cache`
 
-Time in milliseconds the loaded translations stay fresh for. By default, loaded translations never expire — loaders run once per locale and key (a loader's `routes` only decide whether a load trigger considers it, not how often it runs).
+Time in milliseconds the loaded translations stay fresh for. By default, loaded translations never expire — each loader (but one with [`cache: false`](./docs/README.md#cache-optional)) runs once per locale and [route params](./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):
 
@@ -315,38 +363,57 @@ log: {
 - `l(locale, key, ...params)` – translate for an explicit locale
 - `locale` – the ACTIVE locale; assignment is a fire-and-forget `setLocale()`
 - `locales` – available locales
-- `loading` – `true` while any load is in flight
+- `loading` – `true` while any activating load is in flight; a `{ activate: false }` load counts only once an activating trigger joins it
 - `initialized` – locale and route set, translations present
 - `translations` / `rawTranslations` – the (pre/post-preprocess) tables
 
 ### Methods
 
-Load-triggering methods return the promise of the matching load — concurrent duplicate triggers share one in-flight load (and its promise) instead of fetching twice.
+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?)` – load translations for locale and route; `route` defaults to the current one
+- `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
+- `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
 - `loadConfig(config)` – (re)configure the instance
-- `addTranslations(translations)` – add synchronous translations
-- `snapshot()` – serialize the active locale (and the fallback) for the current route, shaped like `config.translations` so the receiving instance hydrates by passing it to `addTranslations()`
-- `invalidate(locale?)` – mark loaded translations stale (one locale, or all); loaders run again on the next load trigger, and a load still in flight for an invalidated locale settles with its data discarded
+- `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
+- `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
 
 ### Utilities
 
-Two helpers the instance uses internally ship from a separate subpath, for code that has to match the library's own behavior:
+Pure helpers ship from a separate subpath, for the code around the instance that has to match the library's own behavior or decide which locale to ask for:
 
 ```javascript
-import { sanitizeLocales, toDotNotation } from '@sveltekit-i18n/base/utils';
+import { matchLocale, resolveLoaders, sanitizeLocales, textDirection, toDotNotation } from '@sveltekit-i18n/base/utils';
 ```
 
 - `toDotNotation(input, preserveArrays?)` – the flattening behind [`preprocess`](#preprocess), for a custom `preprocess` that still wants dot notation
+- `resolveLoaders(loaders, sanitizeLocales?)` – normalizes `config.loaders` the way the instance does, into one loader per locale and namespace pair, for code that reads a config from outside the instance
 - `sanitizeLocales(...locales)` – normalizes a locale from a URL, cookie or `Accept-Language` header the way the instance does, so it can be compared against `locale`
+- `matchLocale(requested, available)` – picks the configured locale a visitor asked for, from an `Accept-Language` header or `navigator.languages`, falling back from `en-GB` to `en` and answering `undefined` when nothing matches
+- `textDirection(locale)` – `'ltr'` or `'rtl'` for a `dir` attribute, from the script the tag spells or the one `Intl.Locale#maximize()` adds, with no list of languages to keep
+
+### SvelteKit
+
+```javascript
+import { defineI18n } from '@sveltekit-i18n/base/kit';
+
+export const { handle, load, use, get } = defineI18n(config, { preferredLocale });
+```
+
+- `handle` – the `hooks.server.js` hook; fills `%lang%` and `%dir%` in `app.html`'s `<html>` tag
+- `load` – the root layout's `load`, exported from `+layout.server.js` and `+layout.js` alike: negotiates the locale, loads it on the server per request and hands it to the one instance a browser tab keeps
+- `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](./docs/README.md)
 
 ## Documentation
 
+- 🌐 [sveltekit-i18n.github.io](https://sveltekit-i18n.github.io) – The documentation site, with a live playground
 - 📖 [Full API Documentation](./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
@@ -382,8 +449,10 @@ The locales survive only when the config reaches the constructor as a literal
 ## Related Packages
 
 - [sveltekit-i18n](https://github.com/sveltekit-i18n/lib) – Complete solution, with the Curly Message Format parser included
-- [@sveltekit-i18n/parser-curly](https://github.com/sveltekit-i18n/parsers/tree/master/parser-curly) – [Curly Message Format](https://github.com/curly-message/spec) parser
+- [@sveltekit-i18n/parser-curly](https://github.com/sveltekit-i18n/parsers/tree/master/parser-curly) – [Curly Message Format](https://curlymessage.dev) parser
 - [@sveltekit-i18n/parser-icu](https://github.com/sveltekit-i18n/parsers/tree/master/parser-icu) – ICU message format parser
+- [@sveltekit-i18n/parser-mf2](https://github.com/sveltekit-i18n/parsers/tree/master/parser-mf2) – [Unicode MessageFormat 2](https://unicode.org/reports/tr35/tr35-messageFormat.html) parser
+- [@sveltekit-i18n/parser-i18next](https://github.com/sveltekit-i18n/parsers/tree/master/parser-i18next) – [i18next](https://www.i18next.com) interpolation and formatting syntax parser
 - [Extensions](https://github.com/sveltekit-i18n/extensions) – Official extensions for the `config.extensions` pipe
 
 ## Contributing
@@ -396,6 +465,11 @@ For issues specific to base functionality, create a ticket [here](https://github
 
 See [Releases](https://github.com/sveltekit-i18n/base/releases) for version history.
 
+## Sponsor
+
+You can support the maintenance of this package through
+[GitHub Sponsors](https://github.com/sponsors/sveltekit-i18n).
+
 ## License
 
 MIT

package/dist/I18n.svelte.d.ts

@@ -1,11 +1,13 @@
-import type { Config, Extension, Parser, Schema, Translations } from './types.js';
+import type { Config, Extension, Loader, Parser, Schema, Snapshot, Translations } from './types.js';
 declare class I18nCore<ParserParams extends Parser.Params = any, ParserOutput = string, TranslationSchema = never, LocaleUnion extends string = string> {
     #private;
     constructor(config?: Config.T<ParserParams, ParserOutput>);
     /**
      * The active locale. Reading it is reactive; assigning it is a shorthand for
      * a fire-and-forget `setLocale()` — the value therefore updates once the
-     * locale's translations resolved, not synchronously on assignment.
+     * locale's translations resolved, not synchronously on assignment. It does
+     * not advance when a loader throws SvelteKit's `redirect()` or an `error()`
+     * below 500, which an assignment only logs.
      */
     get locale(): Config.LocaleInput<LocaleUnion> | undefined;
     set locale(value: Config.LocaleInput<LocaleUnion> | undefined);
@@ -25,43 +27,114 @@ declare class I18nCore<ParserParams extends Parser.Params = any, ParserOutput =
     /** Like `t`, for an explicit locale. */
     l: Translations.LocalTranslationFunction<ParserParams, ParserOutput, TranslationSchema, LocaleUnion>;
     /**
-     * Public entry for (re)configuration. The failure is reported here and the
-     * promise marked handled, so a fire-and-forget call cannot become an
-     * unhandled rejection; an awaiting caller still receives it.
+     * Public entry for (re)configuration. It returns the promise of the
+     * `initLocale` load, which reports its own failure; a config that fails to
+     * apply is reported here. Either way the promise is marked handled, so a
+     * fire-and-forget call cannot become an unhandled rejection; an awaiting
+     * caller still receives it.
      */
     loadConfig: (config: Config.T<ParserParams, ParserOutput>) => Promise<void>;
     setLocale: (locale?: Config.LocaleInput<LocaleUnion>) => Promise<void>;
-    setRoute: (route: string) => Promise<void>;
-    loadTranslations: (locale: Config.LocaleInput<LocaleUnion>, route?: string) => Promise<void>;
+    setRoute: (input: string) => Promise<void>;
     /**
-     * Marks loaded translations stale — for one locale, or all of them. Loaders
-     * run again on the NEXT load trigger; the call itself starts no load and
-     * keeps the currently displayed translations in place. A load still in
-     * flight for an invalidated locale is severed: it settles, but its data is
-     * discarded — it predates the invalidation.
+     * `{ activate: false }` only fills the tables: it leaves the requested
+     * locale, the route and `locale` untouched and does not count towards
+     * `loading` — what is rendered does not change: data of a loader whose route
+     * params differ from the ones the current route asks for is kept aside, the
+     * latest per loader, and the activating trigger that asks for them applies
+     * it. It
+     * leaves `cache` expiry to the next activating trigger. A loader's
+     * `redirect()` or `error()` below 500 rejects it all the same.
      */
-    invalidate: (locale?: Config.LocaleInput<LocaleUnion>) => void;
+    loadTranslations: (locale: Config.LocaleInput<LocaleUnion>, route?: string, { activate }?: {
+        activate?: boolean;
+    }) => Promise<void>;
+    /**
+     * Loads one namespace for the active locale (or `locale`), whatever the
+     * routes of its loaders say — for what an interaction needs rather than a
+     * route: a modal, a panel, an editor. Warm, like `{ activate: false }`: it
+     * changes neither the locale nor `loading`, and it leaves `cache` expiry to
+     * the next activating trigger. It honours the load records, so calling it
+     * on every interaction fetches once — a loader with `cache: false` runs each
+     * time on its routes — and what it loads stays loaded across routes. A
+     * loader's `redirect()` or `error()` below 500 rejects it.
+     */
+    loadNamespace: (namespace: Loader.Key, locale?: Config.LocaleInput<LocaleUnion>) => Promise<void>;
+    /**
+     * Marks loaded translations stale — for one locale or all of them, and for
+     * one namespace or all of them. Loaders run again on the NEXT load trigger;
+     * the call itself starts no load and keeps the currently displayed
+     * translations in place. A loader still in flight for what was invalidated
+     * is severed: its load settles, but what it returns or throws is discarded —
+     * it predates the invalidation — and an activating trigger fetches it again,
+     * once, before its locale activates. It leaves it to the next trigger when
+     * another loader of its load threw SvelteKit's control flow that still
+     * counts, which rejects the trigger, and when the refetch is severed too. A
+     * namespace invalidation leaves the locale's `cache` window where it was.
+     */
+    invalidate: (locale?: Config.LocaleInput<LocaleUnion>, namespace?: Loader.Key) => void;
     addTranslations: (translations?: Translations.SerializedTranslations) => void;
+    /**
+     * Restores the state `snapshot({ records: true })` captured on another
+     * instance: its data, its load records, the active locale and the route.
+     * A loader named by a record does not run again for the same params — one
+     * with `cache: false` only for the pass the envelope arrived with; data no
+     * record names is displayed but keeps no loader from running. An envelope
+     * without `records` is a plain hand-off instead: every namespace its data
+     * names keeps its loaders without params from running, and holds one with
+     * `cache: false` back for that pass. Nothing
+     * happens for `undefined`, so a load whose server half sent nothing can call
+     * it unconditionally.
+     */
+    hydrate: (envelope?: Snapshot.Envelope) => void;
     /**
      * Serializes what this instance holds for the active locale and the fallback
-     * locale, narrowed to the current route: a key owned only by loaders that do
-     * not match the route is left out. The result is shaped like
-     * `config.translations`, so a client hydrates by passing it to
-     * `addTranslations()` — the bookkeeping derived from it then keeps the
-     * matching loaders from fetching the same data again. Apply it to the
-     * instance rather than assigning it to `config.translations`: the payload is
-     * a subset — two locales, and nothing of a key its loaders claim for another
-     * route — so assigning it would drop the rest of the config's own data.
-     * A literal `__proto__` key is left out: the serializer SvelteKit hands load
-     * data to refuses an object that carries one.
+     * locale. The result is shaped like `config.translations`, and a client
+     * hands it over with `hydrate({ translations })`: a plain hand-off, whose
+     * namespace records keep the matching loaders without params from fetching
+     * it again and hold one with `cache: false` back for that pass. Passed to
+     * `addTranslations()` or assigned to `config.translations` it only seeds,
+     * and every loader runs again.
+     * A namespace plain data cannot hand over is left out, for the client to
+     * load: one fed by several loaders, whose record would suppress a part the
+     * payload lacks; one whose loader's routes can capture params, whose data a
+     * plain hand-off keeps as data no loader delivered, so the next params could
+     * not replace it; and one none of whose loaders delivered here and no
+     * hand-off named, whose seeded data would keep the client's loaders from
+     * ever running.
+     * A literal `__proto__` key is left out too, and with records its
+     * namespace's loaders are, and a namespace whose loader captures params,
+     * without them a namespace a loader serves, so the client loads it whole: the serializer SvelteKit hands load data to refuses an
+     * object that carries one. A locale
+     * named `__proto__` is left out altogether.
+     *
+     * `{ records: true }` returns an envelope for `hydrate()` instead: the same
+     * data, the loaders that delivered it, the active locale and the route. The
+     * records name each loader, so a namespace fed by several loaders is handed
+     * over too, and so is one a loader delivered for route params while its
+     * record says so — not a namespace with both, whose data the client could
+     * not split between them. What was seeded into the namespace of a loader
+     * whose routes capture params travels apart as `seeds`, so it outlives new
+     * params there, and reaches the client where the namespace is left out.
      */
-    snapshot: () => Translations.SerializedTranslations;
+    snapshot: {
+        (options?: {
+            records?: false;
+        }): Translations.SerializedTranslations;
+        (options: {
+            records: true;
+        }): Snapshot.Envelope;
+        (options?: {
+            records?: boolean;
+        }): Translations.SerializedTranslations | Snapshot.Envelope;
+    };
     /**
      * Detaches the instance from its loading lifecycle: in-flight loads settle
-     * with their data discarded, `loading` drops to `false`, and every further
-     * load or mutation call is ignored with a warning. Reads (`t`, `l`, `locale`,
-     * `translations`, `snapshot`) keep working, so a component still tearing down
-     * renders its last state instead of breaking. Idempotent.
+     * with whatever their loaders return or throw discarded, `loading` drops to
+     * `false`, and every further load or mutation call is ignored with a warning.
+     * Reads (`t`, `l`, `locale`, `translations`, `snapshot`) keep working, so a
+     * component still tearing down renders its last state instead of breaking.
+     * Idempotent.
      */
     destroy: () => void;
 }