@sveltekit-i18n/base 3.3.0 → 3.3.2

package/README.md

@@ -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.3.0/docs/README.md#sveltekit) for the details and
-[Server-Side Rendering](https://github.com/sveltekit-i18n/base/blob/3.3.0/docs/README.md#server-side-rendering) for wiring it
+[SvelteKit](https://github.com/sveltekit-i18n/base/blob/3.3.2/docs/README.md#sveltekit) for the details and
+[Server-Side Rendering](https://github.com/sveltekit-i18n/base/blob/3.3.2/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.3.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.2/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, 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.0/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.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.2/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.2/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.3.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.2/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.3.0/docs/README.md#basepath).
+See [`basePath`](https://github.com/sveltekit-i18n/base/blob/3.3.2/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.3.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.2/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.3.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.3.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.2/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.2/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.3.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.2/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.3.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.2/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.3.0/docs/README.md#cache-optional)) runs once per locale and [route params](https://github.com/sveltekit-i18n/base/blob/3.3.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.2/docs/README.md#cache-optional)) runs once per locale and [route params](https://github.com/sveltekit-i18n/base/blob/3.3.2/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):
 
@@ -361,7 +366,15 @@ const { t, locale, loading } = new I18n({
 });
 ```
 
-An extension may augment the instance in place, or replace the surface entirely (like the store adapter above). Official extensions live in the [extensions](https://github.com/sveltekit-i18n/extensions) repository; a custom extension is just a function:
+An extension may augment the instance in place, or replace the surface entirely (like the store adapter above). The official extensions live in the [extensions](https://github.com/sveltekit-i18n/extensions) repository:
+
+- [@sveltekit-i18n/extension-stores](https://github.com/sveltekit-i18n/extensions/tree/master/extension-stores) – replaces the instance with the Svelte-store surface of v2 (`$t`, `$locale`, `$loading`, …), the instance it received at `instance`
+- [@sveltekit-i18n/extension-html](https://github.com/sveltekit-i18n/extensions/tree/master/extension-html) – adds a `T` component that renders the markup a message carries as elements and Svelte components, from an allowlist, with no `{@html}`
+- [@sveltekit-i18n/extension-typed-access](https://github.com/sveltekit-i18n/extensions/tree/master/extension-typed-access) – keys as members of `t`: `i18n.t.home.title()` beside `i18n.t('home.title')`, typed from the [`schema`](#schema)
+
+Their order matters. `stores` returns no instance, so it goes after the other two: `[typedAccess, stores]` hands out the tree as `$t.home.title()`, and with `[html({ onReport: null }), stores]` the component is at `instance.T`. `html` after `typedAccess` adds `T` beside the tree, while before it `T` is typed at `instance.T` only. Each package's README has the details, and [lib's examples](https://github.com/sveltekit-i18n/lib/tree/master/examples#extensions) run each one.
+
+A custom extension is just a function:
 
 ```javascript
 const withGreeting = (i18n) => Object.assign(i18n, {
@@ -444,12 +457,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.3.0/docs/README.md)
+Full API documentation: [docs/README.md](https://github.com/sveltekit-i18n/base/blob/3.3.2/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.3.0/docs/README.md) – Complete reference
+- 📖 [Full API Documentation](https://github.com/sveltekit-i18n/base/blob/3.3.2/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
@@ -480,7 +493,9 @@ 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.3.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.2/docs/README.md#typescript) for both.
+
+Keys as members of `t` — `i18n.t.home.title()` beside `i18n.t('home.title')` — come from [@sveltekit-i18n/extension-typed-access](https://github.com/sveltekit-i18n/extensions/tree/master/extension-typed-access), an official [extension](#extensions) typed from the same schema. It reads the keys nested by segment that [@sveltekit-i18n/typegen](https://github.com/sveltekit-i18n/typegen) registers beside the schema, as `tree`, and groups the keys itself without them; the core reads none of it.
 
 ## Related Packages
 

package/dist/kit/backend.browser.d.ts

@@ -0,0 +1,2 @@
+import type { serverHalf as ServerHalf } from './backend.js';
+export declare const serverHalf: typeof ServerHalf;

package/dist/kit/define.svelte.js

@@ -48,6 +48,7 @@ export const defineI18n = (config, options = {}) => {
     let reported = false;
     const preferred = (event) => {
         try {
+            // Typed for string params; a param a matcher parsed misses as no locale.
             return options.preferredLocale?.(event);
         }
         catch (error) {

package/dist/kit/internal.d.ts

@@ -1,5 +1,7 @@
 import type { I18n } from '../I18n.svelte.js';
 import type { Kit } from './types.js';
+/** The params of an event the wiring reads: SvelteKit 3 hands a param its matcher parsed as it parsed it. */
+export type Params = Partial<Record<string, Kit.ParamValue>>;
 /** The negotiated locale, and whether `preferredLocale` gave it. */
 export type Negotiated = {
     locale: string | undefined;
@@ -8,7 +10,7 @@ export type Negotiated = {
 /** What the server half needs from the factory. */
 export type Shared = {
     create: () => I18n;
-    negotiate: (event: Kit.Event, ranges: string | readonly string[] | null | undefined) => Negotiated;
+    negotiate: (event: Kit.Event<Params>, ranges: string | readonly string[] | null | undefined) => Negotiated;
     /** The locales the config serves. */
     locales: () => string[];
     basePath: string | undefined;
@@ -21,7 +23,7 @@ export type Shared = {
 };
 export type ServerHalf = {
     handle: Kit.T['handle'];
-    load: (event: Kit.ServerLoadEvent) => Promise<{
+    load: (event: Kit.ServerLoadEvent<Params>) => Promise<{
         i18n: Kit.Payload;
     }>;
     /** The instance a page render loaded for `payload`, handed out once. */

package/dist/kit/types.d.ts

@@ -1,15 +1,18 @@
 import type { I18n } from '../I18n.svelte.js';
 import type { Snapshot } from '../types.js';
 export declare namespace Kit {
+    /** A route param as SvelteKit 3 types it: a string, or what its matcher parsed it to. */
+    type ParamValue = string | number | boolean | bigint;
     /**
-     * The members of a SvelteKit load or request event the wiring reads.
-     * SvelteKit's own event types are assignable to it. The server-only members
-     * are optional, since an app without a server load hands the universal one,
-     * which has none.
+     * The members of a SvelteKit load or request event the wiring reads. The
+     * default `Params` are string params, as SvelteKit 2 hands them; SvelteKit 3
+     * hands a param its matcher parsed as it parsed it, and `Kit.T` accepts
+     * events of any params. The server-only members are optional, since an app
+     * without a server load hands the universal one, which has none.
      */
-    type Event = {
+    type Event<Params extends Partial<Record<string, ParamValue>> = Partial<Record<string, string>>> = {
         url: URL;
-        params: Partial<Record<string, string>>;
+        params: Params;
         route: {
             id: string | null;
         };
@@ -19,11 +22,11 @@ export declare namespace Kit {
         request?: Request;
         locals?: Record<string, any>;
     };
-    type RequestEvent = Event & Required<Pick<Event, 'cookies' | 'request'>>;
-    type ServerLoadEvent = RequestEvent & {
+    type RequestEvent<Params extends Partial<Record<string, ParamValue>> = Partial<Record<string, string>>> = Event<Params> & Required<Pick<Event<Params>, 'cookies' | 'request'>>;
+    type ServerLoadEvent<Params extends Partial<Record<string, ParamValue>> = Partial<Record<string, string>>> = RequestEvent<Params> & {
         isDataRequest: boolean;
     };
-    type UniversalLoadEvent = Event & {
+    type UniversalLoadEvent<Params extends Partial<Record<string, ParamValue>> = Partial<Record<string, string>>> = Event<Params> & {
         data: Record<string, any> | null;
     };
     type Resolve = (event: any, options?: {
@@ -51,8 +54,12 @@ export declare namespace Kit {
          * profile in `locals`. It is tried before `Accept-Language` (without a
          * server load, before `navigator.languages`), and a value no configured
          * locale matches is skipped; a custom `sanitizeLocales` is applied to it
-         * first. It runs on every navigation and every
-         * preload, so it must be pure: it reads the event and writes nothing.
+         * first. Under SvelteKit 3 a param its matcher parsed reaches the event
+         * parsed, whatever the default `Event` type says: annotate the event as
+         * `Kit.Event<Partial<Record<string, Kit.ParamValue>>>` to see it, and
+         * return a string, since a number is no locale. It runs on every
+         * navigation and every preload, so it must be pure: it reads the event
+         * and writes nothing.
          * With a server load it runs in the browser only on a root error page
          * rendered without the server's data (an unknown URL a static host answers
          * with its fallback page): a navigation to a prerendered page takes the
@@ -63,22 +70,27 @@ export declare namespace Kit {
          */
         preferredLocale?: (event: Event) => string | null | undefined;
     };
-    /** What `defineI18n()` returns. Each member is a plain function, so it can be exported on its own. */
+    /**
+     * What `defineI18n()` returns. Each member is a plain function, so it can be
+     * exported on its own. `handle` and `load` take events of `any` params: a
+     * member implemented by hand annotates its event (for `handle`,
+     * `Kit.RequestEvent`) to read them typed.
+     */
     type T<Instance = I18n> = {
         /** A `handle` hook: fills `%lang%` in the `<html>` tag of `app.html` with the negotiated locale, and `%dir%` with its direction. */
         handle: (input: {
-            event: RequestEvent;
+            event: RequestEvent<Partial<Record<string, any>>>;
             resolve: Resolve;
         }) => Promise<Response>;
         /** The root layout's `load`, exported from `+layout.server.js` and `+layout.js` alike. */
         load: {
-            (event: ServerLoadEvent): Promise<{
+            (event: ServerLoadEvent<Partial<Record<string, any>>>): Promise<{
                 i18n: Payload;
             }>;
-            <E extends UniversalLoadEvent>(event: E): Promise<Omit<NonNullable<E['data']>, 'i18n'> & {
+            <E extends UniversalLoadEvent<Partial<Record<string, any>>>>(event: E): Promise<Omit<NonNullable<E['data']>, 'i18n'> & {
                 i18n: Instance;
             }>;
-            (event: UniversalLoadEvent): Promise<{
+            (event: UniversalLoadEvent<Partial<Record<string, any>>>): Promise<{
                 i18n: Instance;
             }>;
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sveltekit-i18n/base",
-  "version": "3.3.0",
+  "version": "3.3.2",
   "description": "Base functionality of sveltekit-i18n library with a support for external message parsers.",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -28,8 +28,8 @@
       "default": "./dist/kit/env.js"
     },
     "#kit-server": {
-      "browser": "./dist/kit/server.browser.js",
-      "default": "./dist/kit/server.js"
+      "browser": "./dist/kit/backend.browser.js",
+      "default": "./dist/kit/backend.js"
     }
   },
   "scripts": {

package/dist/kit/server.browser.d.ts

@@ -1,2 +0,0 @@
-import type { serverHalf as ServerHalf } from './server.js';
-export declare const serverHalf: typeof ServerHalf;