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

package/README.md

@@ -34,7 +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.
+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.
 
 ## Installation
 
@@ -171,8 +173,10 @@ import i18n from '@sveltekit-i18n/base';
 
 const customParser = () => ({
   parse: (value, params) => {
-    // Your custom interpolation logic
-    return value.replace(/\{(\w+)\}/g, (_, key) => params[0]?.[key] ?? key);
+    // Your custom interpolation logic; `parse` must not throw on a non-string value
+    return typeof value === 'string'
+      ? value.replace(/\{(\w+)\}/g, (_, key) => params[0]?.[key] ?? key)
+      : value;
   },
 });
 
@@ -236,6 +240,19 @@ A loader that throws is logged, and the rest of the load lands without its data;
 
 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:
+
+```javascript
+// svelte.config.js: kit: { paths: { base: process.env.PUBLIC_BASE_PATH ?? '' } }
+import { PUBLIC_BASE_PATH } from '$env/static/public';
+
+basePath: PUBLIC_BASE_PATH
+```
+
+See [`basePath`](./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()`](./docs/README.md#hydrateenvelope) instead:
@@ -256,6 +273,8 @@ Initialize with a specific locale immediately:
 initLocale: 'en'
 ```
 
+With [`defineI18n()`](#sveltekit) it loads nothing: it is a negotiation candidate. Leave it out of a config whose instance you [`hydrate()`](./docs/README.md#hydrateenvelope) by hand — its load starts in the constructor, before the hand-off can be applied.
+
 ### `fallbackLocale`
 
 Fallback when translation is missing:
@@ -274,6 +293,10 @@ Default return value when translation key is not found:
 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`](./docs/README.md#sanitizelocales).
+
 ### `preprocess`
 
 Transform translations after loading:
@@ -289,18 +312,29 @@ preprocess: 'full' // 'full' | 'preserveArrays' | 'none' | custom function
 
 ### `schema`
 
-A map of translation key to the payload its message expects (`never` for a message that takes none). Supplying it types `t`/`l` — keys autocomplete, an unknown key is a type error, and the payload argument is checked. Only its type is read, so the value can stay empty at runtime:
+A map of translation key to the payload its message expects (`never` for a message that takes none). It types `t`/`l` — keys autocomplete, an unknown key is a type error, and the payload argument is checked. Register it once for the app, in a global script, and every instance whose config states no `schema` is typed by it:
 
 ```typescript
-type TranslationSchema = {
+// src/i18n-schema.d.ts — no top-level import or export
+interface TranslationSchema {
   'common.greeting': { name: string };
   'common.farewell': never;
-};
+}
 
+declare namespace SvelteKitI18n {
+  interface Register {
+    schema: TranslationSchema;
+  }
+}
+```
+
+Or state it per instance — only its type is read, so the value can stay empty at runtime, and a stated schema wins over the registry:
+
+```typescript
 const i18n = new I18n({ ...config, schema: {} as TranslationSchema });
 ```
 
-Hand-write it for a small set of messages, or point the slot at a generated artifact. A schema whose keys are not a closed set is ignored, and keys stay plain strings. See [`schema`](./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`](./docs/README.md#schema) for the full rules.
 
 ### `cache`
 
@@ -309,10 +343,10 @@ Time in milliseconds the loaded translations stay fresh for. By default, loaded
 Set a finite value when your loaders fetch from a source that can change at runtime (e.g. a CMS):
 
 ```javascript
-cache: 3600000 // Translations older than 1 hour refetch on the next load
+cache: 3600000 // Translations older than 1 hour refetch on the next activating load
 ```
 
-Set to `0` to treat translations as always stale (refetch on every load trigger). 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`); 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).
 
 ### `extensions`
 
@@ -423,11 +457,12 @@ Full API documentation: [docs/README.md](./docs/README.md)
 
 ```typescript
 import { I18n, type Config } from '@sveltekit-i18n/base';
-import parser from '@sveltekit-i18n/parser-curly';
+import parser, { type Parser } from '@sveltekit-i18n/parser-curly';
 
 // The parser's params – the rest parameters of `t`/`l`. Annotate only when the
-// config lives on its own; `new I18n({ ... })` infers them.
-type Params = [payload?: Record<string, unknown>];
+// config lives on its own; `new I18n({ ... })` infers them. Take the tuple from
+// the parser rather than spelling it by hand.
+type Params = Parser.Params;
 
 const config: Config.T<Params> = {
   parser: parser({ onReport: null }),
@@ -435,7 +470,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`, `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`, `invalidate`, `l`, `locale`, `locales`):
 
 ```typescript
 const i18n = new I18n({ parser: parser({ onReport: null }), initLocale: 'en', fallbackLocale: 'de' });
@@ -454,6 +489,7 @@ The locales survive only when the config reaches the constructor as a literal
 - [@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
+- [@sveltekit-i18n/typegen](https://github.com/sveltekit-i18n/typegen) – Generates the [`schema`](#schema) type from your translation files
 
 ## Contributing
 

package/dist/kit/define.svelte.js

@@ -74,7 +74,13 @@ export const defineI18n = (config, options = {}) => {
     const negotiate = (event, ranges) => {
         // First: it sets the config's logger, which `preferred` reports through.
         const available = locales();
-        return [visitorSanitized(preferred(event)), ranges, ...defaults].reduce((found, candidate) => found ?? matchLocale(candidate, available), undefined);
+        const chosen = matchLocale(visitorSanitized(preferred(event)), available);
+        if (chosen !== undefined)
+            return { locale: chosen, preferred: true };
+        return {
+            locale: [ranges, ...defaults].reduce((found, candidate) => found ?? matchLocale(candidate, available), undefined),
+            preferred: false,
+        };
     };
     const server = serverHalf({ create, negotiate, locales, basePath: config.basePath });
     // Browser only: the tab's instance, the server's answer at the last commit,
@@ -96,11 +102,13 @@ export const defineI18n = (config, options = {}) => {
         const seen = heading(i18n);
         // A live server sends the tables on a page render only, so a later pass
         // that carries them read a prerendered file, whose locale was negotiated
-        // at build time, without the visitor. Node and Deno define
-        // `navigator.languages` too, from the server's own environment.
-        const answer = !fresh && payload?.translations
-            ? tab.answer
-            : payload ? payload.locale : negotiate(event, BROWSER ? navigator.languages : undefined);
+        // at build time, without the visitor: it counts only when the build's
+        // `preferredLocale` gave it. Node and Deno define `navigator.languages`
+        // too, from the server's own environment.
+        const prerendered = !fresh && payload?.translations;
+        const answer = prerendered
+            ? (payload.preferred ? payload.locale : tab.answer)
+            : payload ? payload.locale : negotiate(event, BROWSER ? navigator.languages : undefined).locale;
         if (BROWSER)
             Object.assign(tab, { i18n, surface });
         if (fresh) {

package/dist/kit/internal.d.ts

@@ -1,9 +1,14 @@
 import type { I18n } from '../I18n.svelte.js';
 import type { Kit } from './types.js';
+/** The negotiated locale, and whether `preferredLocale` gave it. */
+export type Negotiated = {
+    locale: string | undefined;
+    preferred: boolean;
+};
 /** What the server half needs from the factory. */
 export type Shared = {
     create: () => I18n;
-    negotiate: (event: Kit.Event, ranges: string | readonly string[] | null | undefined) => string | undefined;
+    negotiate: (event: Kit.Event, ranges: string | readonly string[] | null | undefined) => Negotiated;
     /** The locales the config serves. */
     locales: () => string[];
     basePath: string | undefined;

package/dist/kit/server.js

@@ -32,7 +32,7 @@ export const serverHalf = ({ create, negotiate, locales, basePath }) => {
             const negotiated = () => {
                 if (lang === undefined) {
                     check(event);
-                    lang = answer(event) ?? '';
+                    lang = answer(event).locale ?? '';
                 }
                 return lang;
             };
@@ -61,12 +61,12 @@ export const serverHalf = ({ create, negotiate, locales, basePath }) => {
             // navigation only for what it read.
             const route = event.url.pathname;
             check(event);
-            const locale = answer(event);
+            const { locale, preferred } = answer(event);
             if (event.isDataRequest)
                 return { i18n: { locale, route: withoutBasePath(route, basePath) } };
             const i18n = create();
             await (locale ? i18n.loadTranslations(locale, route) : i18n.setRoute(route));
-            return { i18n: i18n.snapshot({ records: true }) };
+            return { i18n: { ...i18n.snapshot({ records: true }), ...(preferred ? { preferred: true } : {}) } };
         },
     };
 };

package/dist/kit/types.d.ts

@@ -37,7 +37,14 @@ export declare namespace Kit {
      * locale and the route always, the tables and their records on a page
      * render only. Plain data, for `devalue`.
      */
-    type Payload = Omit<Snapshot.Envelope, 'translations'> & Partial<Pick<Snapshot.Envelope, 'translations'>>;
+    type Payload = Omit<Snapshot.Envelope, 'translations'> & Partial<Pick<Snapshot.Envelope, 'translations'>> & {
+        /**
+         * Set on a page render when `preferredLocale` gave the locale. A
+         * prerendered page's data is that render, so a navigation to one takes
+         * its locale only when the build's `preferredLocale` gave it.
+         */
+        preferred?: true;
+    };
     type Options = {
         /**
          * The visitor's choice, read from the event: a cookie, a route param, a
@@ -46,6 +53,9 @@ export declare namespace Kit {
          * 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.
+         * With a server load it runs on the server only: a navigation to a
+         * prerendered page takes the locale it gave at build time, and otherwise
+         * keeps the tab's.
          *
          * @example
          * preferredLocale: (event) => event.cookies?.get('lang')

package/dist/types.d.ts

@@ -83,7 +83,7 @@ export declare namespace Config {
          */
         translations?: Translations.T;
         /**
-         * If you set this property, translations will be initialized immediately using this locale.
+         * If you set this property, translations will be initialized immediately using this locale. `defineI18n()` from `/kit` loads nothing for it: there it is a negotiation candidate. Leave it out of a config whose instance you `hydrate()` by hand – its load starts in the constructor, before the hand-off can be applied.
          */
         initLocale?: InitLocale;
         /**
@@ -129,20 +129,21 @@ export declare namespace Config {
         parser: Parser.T<P, O>;
         /**
          * A key schema — a map of translation key to the payload its message
-         * expects (`never` for a message without parameters). Supplying it types
-         * `t`/`l`: keys autocomplete and a wrong payload is a type error. Only its
-         * TYPE is read, so a generated artifact may export a value that is empty
-         * at runtime — as long as that value is TYPED, e.g.
-         * `export const schema = {} as TranslationSchema`. A schema whose keys are not a
-         * closed set (an open index signature, or no keys at all) is ignored and
-         * keys stay plain strings. Read at construction time only: a later
-         * `loadConfig()` cannot retype the instance, and `config.extensions`
-         * erases the instance's type parameters entirely.
+         * expects (`never` for a message without parameters). It types `t`/`l`:
+         * keys autocomplete and a wrong payload is a type error. Left out, the
+         * schema the app registers in `SvelteKitI18n.Register` types the
+         * instance; stated, it wins over the registry. Only its TYPE is read, so
+         * the value may be empty at runtime — as long as it is TYPED, e.g.
+         * `{} as TranslationSchema`. A schema whose keys are not a closed set (an
+         * open index signature, or no keys at all, as in `schema: {}`) types
+         * nothing and keeps the registry out: keys stay plain strings. Read at
+         * construction time only: a later `loadConfig()` cannot retype the
+         * instance, and an extension typed by a fixed return type erases the
+         * instance's type parameters, while one typed by an `Extension.Operator`
+         * (`Extension.Generic`) keeps them.
          *
          * @example
-         * import { schema } from './generated/i18n-schema.js';
-         *
-         * const i18n = new I18n({ ...config, schema });
+         * const i18n = new I18n({ ...config, schema: {} as TranslationSchema });
          */
         schema?: S;
         /**
@@ -162,11 +163,11 @@ export declare namespace Config {
          */
         basePath?: string;
         /**
-         * Time in milliseconds the loaded translations stay fresh for. Once a locale's translations are older, the next load trigger runs its loaders again. By default, loaded translations never expire – call `invalidate()` (or set a finite `cache`) when your translation source can change at runtime, e.g. a CMS.
+         * Time in milliseconds the loaded translations stay fresh for. Once a locale's translations are older, the next activating load trigger (`setLocale()`, `setRoute()`, `loadTranslations()`) runs its loaders again; a warm load – `loadTranslations(…, { activate: false })` or `loadNamespace()` – fills the tables without evaluating the window. By default, loaded translations never expire – call `invalidate()` (or set a finite `cache`) when your translation source can change at runtime, e.g. a CMS. A loader with `cache: false` is outside the window.
          *
          * @default Number.POSITIVE_INFINITY
          *
-         * @tip Set to `0` to treat translations as always stale (refetch on every load trigger).
+         * @tip Set to `0` to treat translations as always stale (refetch on every activating load trigger).
          */
         cache?: number;
         /**
@@ -442,7 +443,7 @@ export declare namespace Parser {
      * with anything yields the other kind. `'date'` covers both date and time
      * formatting and means `Date | number`. `'function'` is a rich-text callback,
      * the shape ICU tags require. `'boolean'` is here for parsers that can prove
-     * it – neither official parser can, since both compare stringified values.
+     * it – no official parser can, since each compares stringified values.
      */
     type ParamKind = 'unknown' | 'string' | 'number' | 'boolean' | 'date' | 'function';
     /**
@@ -462,7 +463,7 @@ export declare namespace Parser {
         kind?: ParamKind | readonly ParamKind[];
         /**
          * Values the message names explicitly – a hint for authoring tools, never
-         * an exhaustive set. Both official parsers fall back to a default branch
+         * an exhaustive set. Every official parser falls back to a default branch
          * for anything unlisted, so this must not be used to close a union. Omit it
          * where the listed values are not values at all (numeric thresholds, plural
          * categories) or mean the opposite (an inequality's operands).
@@ -485,7 +486,7 @@ export declare namespace Parser {
             branch: string;
         }[];
     };
-    /** Diagnostic context for an extractor. Neither official parser needs it to extract. */
+    /** Diagnostic context for an extractor. No official parser needs it to extract. */
     type ExtractContext = {
         key?: Key;
         locale?: Locale;
@@ -509,6 +510,19 @@ export declare namespace Parser {
      */
     type ExtractParamsFactory<O = unknown> = (options?: O) => ExtractParams;
 }
+declare global {
+    namespace SvelteKitI18n {
+        /**
+         * The app's type registry, filled by a generated global script
+         * (`interface Register { schema: TranslationSchema }`). Its `schema` types
+         * every instance whose config states none. Every copy of the core declares
+         * it empty, and a library never registers: the registry covers the whole
+         * program.
+         */
+        interface Register {
+        }
+    }
+}
 export declare namespace Schema {
     /**
      * A schema types calls only when its keys form a specific, closed set. An
@@ -517,10 +531,25 @@ export declare namespace Schema {
      * they degrade to no schema at all.
      */
     type HasClosedKeys<S> = [keyof S & string] extends [never] ? false : string extends keyof S ? false : true;
-    /** The key schema carried by a config; `never` when there is none to use. */
-    export type FromConfig<C> = C extends {
-        schema?: infer S extends object;
-    } ? (HasClosedKeys<S> extends true ? S : never) : never;
+    /** `S` when its keys are a closed set, `never` otherwise. A union schema is taken whole. */
+    type Closed<S> = [S] extends [object] ? (HasClosedKeys<S> extends true ? S : never) : never;
+    /** What a config's `schema` slot holds; `unknown` when it is absent or typed `any`. */
+    type Slot<C> = C extends {
+        schema?: infer S;
+    } ? S : unknown;
+    /** The key schema `SvelteKitI18n.Register` carries; `never` when it carries none to use. */
+    export type Registered = SvelteKitI18n.Register extends {
+        schema: infer S;
+    } ? Closed<S> : never;
+    /**
+     * The key schema a config types its instance with; `never` when there is
+     * none to use. A slot the config states decides — a closed schema is that
+     * schema, one without a closed key set (`{}`) opts out to plain string keys
+     * — while an absent slot, or one typed `any` (a plain `Config.T`
+     * annotation), reads the registry. A union of configs yields the union of
+     * their schemas.
+     */
+    export type FromConfig<C> = C extends unknown ? (unknown extends Slot<C> ? Registered : Closed<Slot<C>>) : never;
     /**
      * The key schema an instance was built with; `never` when it carries none.
      * The counterpart of `FromConfig` for code handed a constructed surface

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sveltekit-i18n/base",
-  "version": "3.1.0-next.0",
+  "version": "3.1.0-next.2",
   "description": "Base functionality of sveltekit-i18n library with a support for external message parsers.",
   "type": "module",
   "types": "./dist/index.d.ts",