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

package/README.md

@@ -1,126 +1,401 @@
 
-
 [![npm version](https://badge.fury.io/js/@sveltekit-i18n%2Fbase.svg)](https://badge.fury.io/js/@sveltekit-i18n%2Fbase) ![](https://github.com/sveltekit-i18n/base/workflows/Tests/badge.svg)
 
 # @sveltekit-i18n/base
-This repository contains the base functionality of [sveltekit-i18n](https://github.com/sveltekit-i18n/lib) and provides support for external message [parsers](https://github.com/sveltekit-i18n/parsers).
 
+Core i18n functionality for SvelteKit with support for custom message parsers. This package provides the foundation for [sveltekit-i18n](https://github.com/sveltekit-i18n/lib) and can be used standalone when you need maximum flexibility with custom parsers.
+
+## When to use @sveltekit-i18n/base
+
+**Use this package if you:**
+- Need a custom message parser (like ICU, Fluent, or your own format)
+- Want full control over message interpolation
+- Are building a custom i18n solution
+
+**Use [sveltekit-i18n](https://github.com/sveltekit-i18n/lib) if you:**
+- Want the quickest setup with sensible defaults
+- Are happy with the default placeholder/modifier syntax
+- Don't need custom parsers
+
+## Key Features
+
+✅ **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  
+✅ **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
+
+```bash
+npm install @sveltekit-i18n/base
+```
+
+You'll also need a parser:
 
-## Key features
+```bash
+# Choose one:
+npm install @sveltekit-i18n/parser-default
+npm install @sveltekit-i18n/parser-icu
+# or create your own
+```
+
+## Quick Start
+
+### 1. Create translation files
 
-✅ SvelteKit ready\
-✅ SSR support\
-✅ Custom parsers – you can use any message syntax you need\
-✅ Custom data sources – no matter if you are using local files or remote API to get your translations\
-✅ Module-based – your translations are loaded for visited pages only (and only once!)\
-✅ Component-scoped translations – you can create multiple instances with custom definitions\
-✅ TS support\
-✅ No external dependencies
+```jsonc
+// src/lib/translations/en/common.json
+{
+  "greeting": "Hello, {{name}}!",
+  "farewell": "Goodbye!"
+}
+```
 
-## Usage
+### 2. Setup with a parser
 
-Setup `translations.js` in your lib folder...
 ```javascript
-import i18n from '@sveltekit-i18n/base';
-// use your preferred parser (or create your own)
+// src/lib/translations/index.js
+import { I18n } from '@sveltekit-i18n/base';
 import parser from '@sveltekit-i18n/parser-default';
-// import parser from '@sveltekit-i18n/parser-icu';
 
-/** @type {import('@sveltekit-i18n/parser-default').Config} */
-const config = ({
-  parser: parser({/* Parser options */}),
+/** @type {import('@sveltekit-i18n/base').Config.T} */
+const config = {
+  parser: parser({ /* parser options */ }),
   loaders: [
     {
       locale: 'en',
       key: 'common',
-      loader: async () => (
-        await import('./en/common.json')
-      ).default,
-    },
-    {
-      locale: 'en',
-      key: 'home',
-      routes: ['/'], // you can use regexes as well!
-      loader: async () => (
-        await import('./en/home.json')
-      ).default,
-    },
-    {
-      locale: 'en',
-      key: 'about',
-      routes: ['/about'],
-      loader: async () => (
-        await import('./en/about.json')
-      ).default,
+      loader: async () => (await import('./en/common.json')).default,
     },
     {
       locale: 'cs',
       key: 'common',
-      loader: async () => (
-        await import('./cs/common.json')
-      ).default,
-    },
-    {
-      locale: 'cs',
-      key: 'home',
-      routes: ['/'],
-      loader: async () => (
-        await import('./cs/home.json')
-      ).default,
-    },
-    {
-      locale: 'cs',
-      key: 'about',
-      routes: ['/about'],
-      loader: async () => (
-        await import('./cs/about.json')
-      ).default,
+      loader: async () => (await import('./cs/common.json')).default,
     },
   ],
-});
+};
 
-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);
 ```
 
-...load your translations in `+layout.js`...
+### 3. Load translations in your layout
 
-```js
-import { loadTranslations } from '$lib/translations';
+```javascript
+// src/routes/+layout.js
+import { i18n } from '$lib/translations';
 
-/** @type {import('@sveltejs/kit').Load} */
+/** @type {import('./$types').LayoutLoad} */
 export const load = async ({ url }) => {
   const { pathname } = url;
+  const initLocale = 'en';
 
-  const initLocale = 'en'; // get from cookie, user session, ...
-
-  await loadTranslations(initLocale, pathname); // keep this just before the `return`
+  await i18n.loadTranslations(initLocale, pathname);
 
   return {};
-}
+};
 ```
 
-...and include your translations within pages and components.
+> **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';
-
-  const pageName = 'This page is Home page!';
+  import { i18n } from '$lib/translations';
 </script>
 
-<div>
-  <h2>{$t('common.page', { pageName })}</h2>
-  <p>{$t('home.content')}</p>
-</div>
+<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
+
+```javascript
+import i18n from '@sveltekit-i18n/base';
+import parser from '@sveltekit-i18n/parser-icu';
+
+const config = {
+  parser: parser(),
+  loaders: [/* ... */],
+};
+```
+
+```json
+{
+  "items": "You have {count, plural, =0 {no items} one {# item} other {# items}}."
+}
+```
+
+### Custom Parser
+
+```javascript
+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);
+  },
+});
+
+const config = {
+  parser: customParser(),
+  loaders: [/* ... */],
+};
+```
+
+Learn more about [creating custom parsers](https://github.com/sveltekit-i18n/parsers#creating-custom-parsers).
+
+## Configuration Options
+
+### `parser` (required)
+
+Message parser instance. See [Parsers](https://github.com/sveltekit-i18n/parsers).
+
+### `loaders`
+
+Array of loader configurations:
+
+```javascript
+loaders: [
+  {
+    locale: 'en',           // Required: locale identifier
+    key: 'common',          // Required: translation namespace
+    loader: async () => {}, // Required: async function returning translations
+    routes: ['/about'],     // Optional: load only for specific routes
+  },
+]
+```
+
+Both `loaders` and a loader's `routes` accept readonly arrays, so a whole-config `as const` is fine.
+
+### `translations`
+
+Synchronous translations loaded immediately:
+
+```javascript
+translations: {
+  en: {
+    'app.name': 'My App',
+  },
+}
+```
+
+### `initLocale`
+
+Initialize with a specific locale immediately:
+
+```javascript
+initLocale: 'en'
+```
+
+### `fallbackLocale`
+
+Fallback when translation is missing:
+
+```javascript
+fallbackLocale: 'en'
+```
+
+**Note:** This loads translations for both current locale and fallback locale, which may impact performance.
+
+### `fallbackValue`
+
+Default return value when translation key is not found:
+
+```javascript
+fallbackValue: '...' // Default: returns the key itself
+```
+
+### `preprocess`
+
+Transform translations after loading:
+
+```javascript
+preprocess: 'full' // 'full' | 'preserveArrays' | 'none' | custom function
+```
+
+- `'full'` (default): Flattens all nested objects to dot notation
+- `'preserveArrays'`: Flattens objects but preserves arrays
+- `'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`
+
+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: 3600000 // Translations older than 1 hour refetch on the next 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).
+
+### `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`
+
+Logging configuration:
+
+```javascript
+log: {
+  level: 'warn',        // 'error' | 'warn' | 'debug'
+  prefix: '[i18n]: ',   // Log prefix
+  logger: console,      // Custom logger
+}
+```
+
+## API Reference
+
+### Reactive properties
+
+- `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
+
+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)
+
+## Documentation
+
+- 📖 [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
+- 💡 [Examples](https://github.com/sveltekit-i18n/lib/tree/master/examples) – Real-world usage examples
+
+## TypeScript Support
+
+```typescript
+import { I18n, type Config } from '@sveltekit-i18n/base';
+import parser from '@sveltekit-i18n/parser-default';
+
+// 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
+
+For general contribution guidelines, see the [Contributing Guide](https://github.com/sveltekit-i18n/lib/blob/master/CONTRIBUTING.md) in the main library repository.
+
+For issues specific to base functionality, create a ticket [here](https://github.com/sveltekit-i18n/lib/issues).
+
+## Changelog
 
-## More info
-[Parsers](https://github.com/sveltekit-i18n/parsers)\
-[Docs](https://github.com/sveltekit-i18n/base/tree/master/docs/README.md)\
-[Examples](https://github.com/sveltekit-i18n/lib/tree/master/examples#parsers)\
-[Changelog](https://github.com/sveltekit-i18n/base/releases)
+See [Releases](https://github.com/sveltekit-i18n/base/releases) for version history.
 
+## License
 
-## Issues
-If you are facing some issues related to the base functionality, create a ticket [here](https://github.com/sveltekit-i18n/lib/issues).
+MIT

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;