@sveltekit-i18n/base 1.3.8 → 3.0.0-next.0

package/README.md

@@ -19,13 +19,15 @@ Core i18n functionality for SvelteKit with support for custom message parsers. T
 
 ## Key Features
 
-✅ **SvelteKit ready** – Full SSR and CSR support  
+✅ **Svelte 5 runes** – One reactive instance, no stores  
+✅ **Framework ready** – Full SSR and CSR support  
 ✅ **Parser-agnostic** – Use any message syntax you need  
 ✅ **Custom data sources** – Load translations from anywhere (files, APIs, databases)  
 ✅ **Module-based** – Translations load only for visited pages  
 ✅ **Route-aware** – Automatic loading based on SvelteKit routes  
 ✅ **Component-scoped** – Multiple translation instances with custom definitions  
-✅ **TypeScript** – Full type support  
+✅ **Extensible** – Pipe the instance through [extensions](#extensions) to reshape or augment its surface  
+✅ **TypeScript** – Locales inferred from your config, keys and payloads from a [`schema`](#schema)  
 ✅ **Zero dependencies** – Lightweight and fast
 
 ## Installation
@@ -47,7 +49,7 @@ npm install @sveltekit-i18n/parser-icu
 
 ### 1. Create translation files
 
-```json
+```jsonc
 // src/lib/translations/en/common.json
 {
   "greeting": "Hello, {{name}}!",
@@ -59,10 +61,10 @@ npm install @sveltekit-i18n/parser-icu
 
 ```javascript
 // src/lib/translations/index.js
-import i18n from '@sveltekit-i18n/base';
+import { I18n } from '@sveltekit-i18n/base';
 import parser from '@sveltekit-i18n/parser-default';
 
-/** @type {import('@sveltekit-i18n/base').Config} */
+/** @type {import('@sveltekit-i18n/base').Config.T} */
 const config = {
   parser: parser({ /* parser options */ }),
   loaders: [
@@ -79,36 +81,50 @@ const config = {
   ],
 };
 
-export const { t, locale, locales, loading, loadTranslations } = new i18n(config);
+// 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);
 ```
 
 ### 3. Load translations in your layout
 
 ```javascript
 // src/routes/+layout.js
-import { loadTranslations } from '$lib/translations';
+import { i18n } from '$lib/translations';
 
 /** @type {import('./$types').LayoutLoad} */
 export const load = async ({ url }) => {
   const { pathname } = url;
   const initLocale = 'en';
-  
-  await loadTranslations(initLocale, pathname);
-  
+
+  await i18n.loadTranslations(initLocale, pathname);
+
   return {};
 };
 ```
 
+> **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).
+
 ### 4. Use in components
 
 ```svelte
 <script>
-  import { t } from '$lib/translations';
+  import { i18n } from '$lib/translations';
 </script>
 
-<p>{$t('common.greeting', { name: 'World' })}</p>
+<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.
+
 ## Using Different Parsers
 
 ### ICU Message Format
@@ -170,6 +186,8 @@ loaders: [
 ]
 ```
 
+Both `loaders` and a loader's `routes` accept readonly arrays, so a whole-config `as const` is fine.
+
 ### `translations`
 
 Synchronous translations loaded immediately:
@@ -221,15 +239,61 @@ preprocess: 'full' // 'full' | 'preserveArrays' | 'none' | custom function
 - `'none'`: No preprocessing
 - Custom function: `(input) => transformedOutput`
 
+### `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:
+
+```typescript
+type TranslationSchema = {
+  'common.greeting': { name: string };
+  'common.farewell': never;
+};
+
+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.
+
 ### `cache`
 
-Server-side cache duration in milliseconds:
+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).
+
+Set a finite value when your loaders fetch from a source that can change at runtime (e.g. a CMS):
 
 ```javascript
-cache: 86400000 // Default: 24 hours
+cache: 3600000 // Translations older than 1 hour refetch on the next load
 ```
 
-Set to `Number.POSITIVE_INFINITY` to disable cache refresh.
+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).
+
+### `extensions`
+
+Pipes the constructed instance through extension functions, left to right. Each extension receives the surface produced so far (the raw instance for the first one) and returns the surface handed on — `new I18n(config)` evaluates to the last extension's output:
+
+```javascript
+import stores from '@sveltekit-i18n/extension-stores';
+
+const { t, locale, loading } = new I18n({
+  ...config,
+  extensions: [stores],
+});
+```
+
+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:
+
+```javascript
+const withGreeting = (i18n) => Object.assign(i18n, {
+  greet: (name) => i18n.t('common.greeting', { name }),
+});
+
+export const i18n = new I18n({ ...config, extensions: [withGreeting] });
+
+i18n.greet('World');
+```
+
+**Notes:**
+- Applied at construction time only — a later `loadConfig()` call ignores this property.
+- When an extension returns a new object, the result is no longer `instanceof I18n`; the original instance stays reachable through whatever the extension exposes (the official extensions expose it as `instance`).
 
 ### `log`
 
@@ -245,20 +309,39 @@ log: {
 
 ## API Reference
 
-### Stores
+### Reactive properties
 
-- `t` – Translation function store
-- `locale` – Current locale (writable)
-- `locales` – Available locales (readable)
-- `loading` – Loading state (readable)
-- `initialized` – Initialization state (readable)
-- `translations` – All loaded translations (readable)
+- `t(key, ...params)` – translate for the active locale (reactive function)
+- `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
+- `initialized` – locale and route set, translations present
+- `translations` / `rawTranslations` – the (pre/post-preprocess) tables
 
 ### Methods
 
-- `loadTranslations(locale, route)` – Load translations for locale and route
-- `setLocale(locale)` – Change current locale
-- `setRoute(route)` – Update current route
+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.
+
+- `loadTranslations(locale, route?)` – load translations for locale and route; `route` defaults to the current one
+- `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 from it
+- `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
+- `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:
+
+```javascript
+import { sanitizeLocales, toDotNotation } from '@sveltekit-i18n/base/utils';
+```
+
+- `toDotNotation(input, preserveArrays?)` – the flattening behind [`preprocess`](#preprocess), for a custom `preprocess` that still wants dot notation
+- `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`
 
 Full API documentation: [docs/README.md](./docs/README.md)
 
@@ -272,21 +355,36 @@ Full API documentation: [docs/README.md](./docs/README.md)
 ## TypeScript Support
 
 ```typescript
-import i18n, { type Config } from '@sveltekit-i18n/base';
+import { I18n, type Config } from '@sveltekit-i18n/base';
 import parser from '@sveltekit-i18n/parser-default';
-import type { Config as ParserConfig } from '@sveltekit-i18n/parser-default';
 
-const config: Config<ParserConfig> = {
+// 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>];
+
+const config: Config.T<Params> = {
   parser: parser(),
   loaders: [/* ... */],
 };
 ```
 
+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`):
+
+```typescript
+const i18n = new I18n({ parser: parser(), initLocale: 'en', fallbackLocale: 'de' });
+
+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](./docs/README.md#typescript) for both.
+
 ## Related Packages
 
 - [sveltekit-i18n](https://github.com/sveltekit-i18n/lib) – Complete solution with default parser
 - [@sveltekit-i18n/parser-default](https://github.com/sveltekit-i18n/parsers/tree/master/parser-default) – Default message parser
 - [@sveltekit-i18n/parser-icu](https://github.com/sveltekit-i18n/parsers/tree/master/parser-icu) – ICU message format parser
+- [Extensions](https://github.com/sveltekit-i18n/extensions) – Official extensions for the `config.extensions` pipe
 
 ## Contributing
 

package/dist/I18n.svelte.d.ts

@@ -0,0 +1,80 @@
+import type { Config, Extension, Parser, Schema, 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.
+     */
+    get locale(): Config.LocaleInput<LocaleUnion> | undefined;
+    set locale(value: Config.LocaleInput<LocaleUnion> | undefined);
+    get translations(): Translations.SerializedTranslations;
+    get rawTranslations(): Translations.SerializedTranslations;
+    loading: boolean;
+    locales: Config.LocaleInput<LocaleUnion>[];
+    initialized: boolean;
+    /**
+     * Translates `key` for the active locale. Reactive wherever reads are
+     * tracked: the call reads the translation table and locale, so a component
+     * using `{i18n.t('key')}` re-renders when either changes.
+     */
+    t: Translations.TranslationFunction<ParserParams, ParserOutput, TranslationSchema>;
+    /** Like `t`, for an explicit locale. */
+    l: Translations.LocalTranslationFunction<ParserParams, ParserOutput, TranslationSchema, LocaleUnion>;
+    /**
+     * Applies a config. Overridable extension seam — `sveltekit-i18n` wires its
+     * default parser by extending this method.
+     */
+    configLoader(config: Config.T<ParserParams, ParserOutput>): Promise<void>;
+    /**
+     * 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.
+     */
+    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>;
+    /**
+     * 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.
+     */
+    invalidate: (locale?: Config.LocaleInput<LocaleUnion>) => void;
+    addTranslations: (translations?: Translations.SerializedTranslations) => 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 handing it back to the
+     * constructor — the bookkeeping derived from it then keeps the matching
+     * loaders from fetching the same data again.
+     */
+    snapshot: () => Translations.SerializedTranslations;
+    /**
+     * 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.
+     */
+    destroy: () => void;
+}
+/**
+ * A class declaration cannot annotate its constructor's return type, so the
+ * extension pipe's construction-time type lives on this construct signature
+ * instead: parser params and output are inferred from `config.parser`, locales
+ * are narrowed to the ones the config names, and the returned surface is the
+ * instance type folded through the `config.extensions` tuple
+ * (`const` keeps it a tuple without `as const` at the call site).
+ */
+interface I18nConstructor {
+    new <const C extends Config.T<any, any> = Config.T<any, any>>(config?: C): Extension.Piped<I18nCore<Parser.FromConfig<C>, Parser.OutputFromConfig<C>, Schema.FromConfig<C>, Config.LocalesFromConfig<C>>, Extension.FromConfig<C>>;
+}
+declare const I18n: I18nConstructor;
+type I18n<ParserParams extends Parser.Params = any, ParserOutput = string, TranslationSchema = never, LocaleUnion extends string = string> = I18nCore<ParserParams, ParserOutput, TranslationSchema, LocaleUnion>;
+export { I18n };
+export default I18n;