@sveltekit-i18n/base 3.1.1 → 3.2.0

package/README.md

@@ -122,8 +122,8 @@ 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](./docs/README.md#sveltekit) for the details and
-[Server-Side Rendering](./docs/README.md#server-side-rendering) for wiring it
+[SvelteKit](https://github.com/sveltekit-i18n/base/blob/3.2.0/docs/README.md#sveltekit) for the details and
+[Server-Side Rendering](https://github.com/sveltekit-i18n/base/blob/3.2.0/docs/README.md#server-side-rendering) for wiring it
 by hand.
 
 ### 4. Use in components
@@ -232,11 +232,11 @@ 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](./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.2.0/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 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`](https://github.com/sveltekit-i18n/base/blob/3.2.0/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).
+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.2.0/docs/README.md#loader-required).
 
 Both `loaders` and a loader's `routes` accept readonly arrays, so a whole-config `as const` is fine.
 
@@ -251,11 +251,11 @@ import { PUBLIC_BASE_PATH } from '$env/static/public';
 basePath: PUBLIC_BASE_PATH
 ```
 
-See [`basePath`](./docs/README.md#basepath).
+See [`basePath`](https://github.com/sveltekit-i18n/base/blob/3.2.0/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:
+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.2.0/docs/README.md#hydrateenvelope) instead:
 
 ```javascript
 translations: {
@@ -267,13 +267,13 @@ translations: {
 
 ### `initLocale`
 
-Initialize with a specific locale immediately:
+The initial locale, used when nothing else decides:
 
 ```javascript
 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.
+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.2.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.2.0/docs/README.md#hydrateenvelope) by hand — its load starts before the hand-off can be applied.
 
 ### `fallbackLocale`
 
@@ -295,7 +295,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`](./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.2.0/docs/README.md#sanitizelocales).
 
 ### `preprocess`
 
@@ -334,11 +334,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`](./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.2.0/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`](./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).
+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.2.0/docs/README.md#cache-optional)) runs once per locale and [route params](https://github.com/sveltekit-i18n/base/blob/3.2.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).
 
 Set a finite value when your loaders fetch from a source that can change at runtime (e.g. a CMS):
 
@@ -399,7 +399,7 @@ log: {
 - `locales` – available locales
 - `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
+- `translations` / `rawTranslations` – the tables after and before preprocessing
 
 ### Methods
 
@@ -443,12 +443,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](./docs/README.md)
+Full API documentation: [docs/README.md](https://github.com/sveltekit-i18n/base/blob/3.2.0/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
+- 📖 [Full API Documentation](https://github.com/sveltekit-i18n/base/blob/3.2.0/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
@@ -479,7 +479,7 @@ 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.
+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.2.0/docs/README.md#typescript) for both.
 
 ## Related Packages
 

package/dist/I18n.svelte.js

@@ -1,5 +1,5 @@
 import { untrack } from 'svelte';
-import { capturesParams, fetchTranslation, hasOwn, loaderName, mergeFetched, mergeTranslations, omitProtoKeys, paramsSignature, read, resolveLoaders, routeParams, sanitizerFactory, sanitizeTranslationLocales, serialize, servedLocales, toDotNotation, translate, unique, withoutBasePath } from './utils.js';
+import { capturesParams, fetchTranslation, hasOwn, loaderName, maskOutputKeys, maskTranslations, mergeFetched, mergeTranslations, omitProtoKeys, paramsSignature, read, resolveLoaders, routeParams, sanitizerFactory, sanitizeTranslationLocales, serialize, servedLocales, toDotNotation, translate, unique, withoutBasePath } from './utils.js';
 import { logError, logger, loggerFactory, setLogger } from './logger.js';
 const defaultCache = Number.POSITIVE_INFINITY;
 /**
@@ -650,6 +650,23 @@ class I18nCore {
     #addSanitized(sanitized) {
         this.#mergeTranslations(sanitized);
         this.#keepExternal(sanitized);
+        const { preprocess } = this.#config ?? {};
+        // Seeded over what a loader delivered before, so a rebuild of the
+        // namespace, which lays the seeds under every delivery, keeps it on top
+        // until that loader delivers again.
+        this.#deliveries.forEach((delivery, loader) => {
+            const own = Object.entries(read(sanitized, loader.locale) ?? {}).filter(([key]) => isNamespaceKey(key, loader.namespace));
+            if (!own.length)
+                return;
+            const nested = read(read(sanitized, loader.locale), loader.namespace);
+            const masked = nested === undefined ? delivery.data : maskTranslations(delivery.data, nested) ?? {};
+            // Dot notation, as `#preprocess` applies it, merges both spellings of a
+            // key into one.
+            const dotted = typeof preprocess !== 'function' && preprocess !== 'none'
+                ? maskOutputKeys(masked, new Set(Object.keys(toDotNotation(Object.fromEntries(own), preprocess === 'preserveArrays') ?? {})), loader.namespace, preprocess === 'preserveArrays') ?? {}
+                : masked;
+            this.#deliveries.set(loader, { ...delivery, data: dotted });
+        });
     }
     /**
      * Applies plain hand-off data. It records every namespace the data names,

package/dist/kit/define.svelte.js

@@ -78,7 +78,9 @@ export const defineI18n = (config, options = {}) => {
         if (chosen !== undefined)
             return { locale: chosen, preferred: true };
         return {
-            locale: [ranges, ...defaults].reduce((found, candidate) => found ?? matchLocale(candidate, available), undefined),
+            // Last, the first locale served: a config that serves one never renders
+            // a page without a locale.
+            locale: [ranges, ...defaults].reduce((found, candidate) => found ?? matchLocale(candidate, available), undefined) ?? available[0],
             preferred: false,
         };
     };

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. `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.
+         * The initial locale. With `defineI18n()` from `/kit`, the locale a visitor gets when neither `preferredLocale` nor what the visitor's browser asks for (`Accept-Language`, or `navigator.languages` without a server `load`) names a locale the config serves; it loads only when negotiation picks it, and without it, or when it matches no locale served, `fallbackLocale` and then the first locale served take that role. With `new I18n(config)`, the constructor loads it right away – leave it out of a config whose instance you `hydrate()` by hand, since its load starts before the hand-off can be applied.
          */
         initLocale?: InitLocale;
         /**
@@ -646,9 +646,11 @@ export declare namespace Translations {
     type SerializedTranslations = LocaleIndexed<DotNotation.Input>;
     /**
      * What `t`/`l` yield. The parser's output on the paths that reach the parser,
-     * and a plain string on the ones that cannot: an empty key, no locale, or a
-     * config carrying no parser. `O` is `string` for every parser that returns
-     * one, which collapses the union everywhere it is not needed.
+     * and a plain string on the misses: `''` for an empty key or no locale, the
+     * key itself for a missing translation. Two paths hand back data unchecked:
+     * a configured `fallbackValue`, and the stored value while the config
+     * carries no parser. `O` is `string` for every parser that returns one,
+     * which collapses the union everywhere it is not needed.
      */
     type Translated<O> = O | string;
     type TranslationFunction<P extends Parser.Params = Parser.Params, O = string, S = never> = <K extends Schema.Key<S>>(key: K, ...restParams: Schema.Params<S, K, P>) => Translated<O>;

package/dist/utils.d.ts

@@ -54,6 +54,8 @@ export declare const toDotNotation: DotNotation.T;
 export declare const unique: <V>(values: readonly V[]) => V[];
 export declare const resolveLoaders: (input?: readonly Loader.LoaderModule[], sanitizeLocales?: Config.SanitizeLocales) => Loader.Resolved[];
 export declare const mergeTranslations: (target: any, source: any, path: string, onConflict?: (path: string) => void) => any;
+export declare const maskTranslations: (target: any, source: any) => any;
+export declare const maskOutputKeys: (target: any, keys: ReadonlySet<string>, prefix: string, preserveArrays?: boolean) => any;
 export declare const omitProtoKeys: (value: any) => any;
 export declare const serialize: (input: Array<Loader.Resolved & {
     data: any;

package/dist/utils.js

@@ -492,6 +492,42 @@ export const mergeTranslations = (target, source, path, onConflict) => {
         [key]: hasOwn(acc, key) ? mergeTranslations(read(acc, key), read(source, key), `${path}.${key}`, onConflict) : read(source, key),
     }), target);
 };
+// What of `target` still shows once `source` is merged over it: the branches
+// both hold as objects keep what `source` leaves out, and anything else it
+// sets is gone. `undefined` when `source` replaces the whole of `target`.
+export const maskTranslations = (target, source) => {
+    if (!isMergeable(target) || !isMergeable(source))
+        return undefined;
+    return Object.keys(target).reduce((acc, key) => {
+        if (!hasOwn(source, key))
+            return { ...acc, [key]: read(target, key) };
+        const masked = maskTranslations(read(target, key), read(source, key));
+        return masked === undefined ? acc : { ...acc, [key]: masked };
+    }, {});
+};
+// What of `target`, dot-notated under `prefix`, still shows once `keys` are
+// dot-notated beside it: a leaf whose key is among them is gone. A key spelled
+// with dots and a nested branch meet only there, after `preprocess`. Unless
+// `preserveArrays`, an array is walked as `toDotNotation` walks it, and one
+// that lost an item keeps the others under their indexes. What lost nothing is
+// returned as it is, and an array that lost no item and holds nothing but its
+// items stays one.
+export const maskOutputKeys = (target, keys, prefix, preserveArrays = false) => {
+    const walked = Array.isArray(target) ? !preserveArrays : isMergeable(target);
+    if (!walked)
+        return keys.has(prefix) ? undefined : target;
+    const entries = Object.keys(target).flatMap((key) => {
+        const masked = maskOutputKeys(read(target, key), keys, `${prefix}.${key}`, preserveArrays);
+        return masked === undefined ? [] : [[key, masked]];
+    });
+    if (entries.length === Object.keys(target).length) {
+        if (entries.every(([key, value]) => Object.is(value, read(target, key))))
+            return target;
+        if (Array.isArray(target) && entries.every(([key], index) => key === `${index}`))
+            return entries.map(([, value]) => value);
+    }
+    return entries.reduce((acc, [key, value]) => ({ ...acc, [key]: value }), {});
+};
 const isPlainObject = (value) => {
     if (!value || typeof value !== 'object')
         return false;

package/package.json

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