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

package/dist/exports/kit.d.ts

@@ -0,0 +1,2 @@
+export { defineI18n } from '../kit/define.svelte.js';
+export type { Kit } from '../kit/types.js';

package/dist/exports/kit.js

@@ -0,0 +1 @@
+export { defineI18n } from '../kit/define.svelte.js';

package/dist/exports/utils.d.ts

@@ -1,2 +1,2 @@
-export { sanitizeLocales, toDotNotation } from '../utils.js';
+export { matchLocale, resolveLoaders, sanitizeLocales, textDirection, toDotNotation } from '../utils.js';
 export type { DotNotation } from '../types.js';

package/dist/exports/utils.js

@@ -1 +1 @@
-export { sanitizeLocales, toDotNotation } from '../utils.js';
+export { matchLocale, resolveLoaders, sanitizeLocales, textDirection, toDotNotation } from '../utils.js';

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export { default, I18n } from './I18n.svelte.js';
-export type { Config, Extension, Loader, Logger, Parser, Schema, Translations } from './types.js';
+export type { Config, Extension, Loader, Logger, Parser, Schema, Snapshot, Translations } from './types.js';

package/dist/kit/define.svelte.d.ts

@@ -0,0 +1,9 @@
+import { I18n } from '../I18n.svelte.js';
+import type { Config } from '../types.js';
+import type { Kit } from './types.js';
+/**
+ * Wires SvelteKit to an instance of `config`: a `handle` hook, the root
+ * layout's `load`, and `use()` / `get()` for components. The server builds an
+ * instance per request; the browser keeps one per tab.
+ */
+export declare const defineI18n: <const C extends Config.T<any, any> = Config.T<any, any>>(config: C, options?: Kit.Options) => Kit.T<InstanceType<typeof I18n<C>>>;

package/dist/kit/define.svelte.js

@@ -0,0 +1,178 @@
+import { getContext, setContext, untrack } from 'svelte';
+import { BROWSER } from '#kit-env';
+import { serverHalf } from '#kit-server';
+import { I18n } from '../I18n.svelte.js';
+import { logError, loggerFactory, setLogger } from '../logger.js';
+import { configLocales, matchLocale, sanitizerFactory, textDirection } from '../utils.js';
+// Registry-wide, so two copies of this package meet: the context key, and the
+// key of the pass the universal branch hands `use()` in `data`.
+const KEY = Symbol.for('@sveltekit-i18n/base/kit');
+const passOf = (data) => data?.[KEY];
+const isServerEvent = (event) => 'cookies' in event;
+/**
+ * Wires SvelteKit to an instance of `config`: a `handle` hook, the root
+ * layout's `load`, and `use()` / `get()` for components. The server builds an
+ * instance per request; the browser keeps one per tab.
+ */
+export const defineI18n = (config, options = {}) => {
+    // The constructor would start an `initLocale` load of its own, next to the
+    // negotiated one; here `initLocale` is a negotiation candidate instead. The
+    // wiring drives the core itself, whatever the extensions make of it.
+    const create = () => new I18n({ ...config, initLocale: undefined, extensions: undefined });
+    const pipe = (i18n) => (config.extensions ?? []).reduce((acc, extension) => extension(acc), i18n);
+    const sanitize = sanitizerFactory(config.sanitizeLocales);
+    const sanitized = (locale) => (locale ? sanitize(locale)[0] : undefined);
+    let configured;
+    // `initLocale` and `fallbackLocale`, spelled as the config's locales are and
+    // so sanitized alike.
+    let defaults = [];
+    // Resolved on first use, never at import, and once: resolving the loaders
+    // and sanitizing reports what is wrong with them.
+    const locales = () => {
+        if (configured)
+            return configured;
+        if (config.log)
+            setLogger(loggerFactory(config.log));
+        try {
+            configured = configLocales(config);
+        }
+        catch {
+            // The instance reports a malformed config itself.
+            configured = [];
+        }
+        defaults = [sanitized(config.initLocale), sanitized(config.fallbackLocale)];
+        return configured;
+    };
+    let reported = false;
+    const preferred = (event) => {
+        try {
+            return options.preferredLocale?.(event);
+        }
+        catch (error) {
+            if (!reported)
+                logError('`preferredLocale` failed. Negotiating without it.', error);
+            reported = true;
+            return undefined;
+        }
+    };
+    // What `preferredLocale` returns is the visitor's, so it goes through a
+    // custom sanitizer silently — a value it rejects is matched as it is — and
+    // never through the default one, which warns on every tag `Intl` does not
+    // know: either would turn a visitor's cookie into a report per request.
+    const visitorSanitized = (locale) => {
+        const { sanitizeLocales: custom } = config;
+        if (!locale || typeof custom !== 'function')
+            return locale;
+        try {
+            const result = custom(`${locale}`);
+            return result ? `${result}` : locale;
+        }
+        catch {
+            return locale;
+        }
+    };
+    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 server = serverHalf({ create, negotiate, locales, basePath: config.basePath });
+    // Browser only: the tab's instance, the server's answer at the last commit,
+    // and the locale that commit is switching to with the one it switches from,
+    // which only `use()` writes. A server keeps nothing between requests.
+    const tab = { committed: false };
+    // The locale the tab shows once the wiring's own switch lands: that switch
+    // is no client change, while a locale that moved from where it started is.
+    const heading = (i18n) => {
+        const active = untrack(() => i18n.locale);
+        return tab.switching && tab.switching.from === active ? tab.switching.to : active;
+    };
+    const universalLoad = async (event) => {
+        const route = event.url.pathname;
+        const payload = event.data?.i18n;
+        const fresh = !BROWSER || !tab.i18n;
+        const i18n = fresh ? create() : tab.i18n;
+        const surface = fresh ? pipe(i18n) : tab.surface;
+        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);
+        if (BROWSER)
+            Object.assign(tab, { i18n, surface });
+        if (fresh) {
+            if (payload?.translations)
+                i18n.hydrate({ ...payload, translations: payload.translations });
+            // No preload runs before the first navigation completes, so the pass
+            // that builds the instance may activate it.
+            await (answer ? i18n.loadTranslations(answer, route) : i18n.setRoute(route));
+        }
+        else {
+            // Warm only: this pass may be a preload, which must not change what is
+            // shown. The commit switches to a changed answer, or else stays.
+            const target = (answer !== tab.answer ? answer : undefined) ?? heading(i18n);
+            if (target)
+                await i18n.loadTranslations(target, route, { activate: false });
+        }
+        const pass = { i18n, surface, locale: answer, route, seen };
+        return { ...event.data, i18n: surface, [KEY]: pass };
+    };
+    const load = ((event) => (isServerEvent(event) ? server.load(event) : universalLoad(event)));
+    const use = (data) => {
+        const first = passOf(data());
+        if (!first)
+            throw new Error('[i18n]: `use()` found no data from `load`. Export `load` from the root `+layout.js`.');
+        const { i18n, surface } = first;
+        setContext(KEY, surface);
+        // `data` moves only when a navigation commits; a preload leaves it. The
+        // answer is compared with the last commit's, so a client `setLocale()`
+        // stands until the server answers differently, and an answer given before
+        // the active locale changed is stale.
+        $effect.pre(() => {
+            const pass = passOf(data());
+            if (!pass)
+                return;
+            if (!tab.committed || (pass.locale !== tab.answer && heading(pass.i18n) === pass.seen)) {
+                const { locale } = pass;
+                const previous = tab.answer;
+                tab.committed = true;
+                tab.answer = locale;
+                if (locale !== undefined) {
+                    const switching = { from: untrack(() => pass.i18n.locale), to: locale };
+                    const done = () => {
+                        if (tab.switching === switching)
+                            tab.switching = undefined;
+                    };
+                    tab.switching = switching;
+                    // A switch that failed, and that no later call landed either, leaves
+                    // the answer to the next commit.
+                    pass.i18n.loadTranslations(locale, pass.route).then(done, () => {
+                        done();
+                        if (tab.answer === locale && untrack(() => pass.i18n.locale) !== locale)
+                            tab.answer = previous;
+                    });
+                    return;
+                }
+            }
+            void pass.i18n.setRoute(pass.route);
+        });
+        $effect(() => {
+            const { locale } = i18n;
+            if (!locale)
+                return;
+            document.documentElement.lang = locale;
+            document.documentElement.dir = textDirection(locale);
+        });
+        return surface;
+    };
+    const get = () => {
+        const surface = getContext(KEY);
+        if (!surface)
+            throw new Error('[i18n]: `get()` found no instance. Call `use(() => data)` in the root `+layout.svelte`.');
+        return surface;
+    };
+    return { handle: server.handle, load, use, get };
+};

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

@@ -0,0 +1 @@
+export declare const BROWSER: boolean;

package/dist/kit/env.browser.js

@@ -0,0 +1 @@
+export const BROWSER = true;

package/dist/kit/env.d.ts

@@ -0,0 +1 @@
+export declare const BROWSER: boolean;

package/dist/kit/env.js

@@ -0,0 +1 @@
+export const BROWSER = false;

package/dist/kit/internal.d.ts

@@ -0,0 +1,16 @@
+import type { I18n } from '../I18n.svelte.js';
+import type { Kit } from './types.js';
+/** 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;
+    /** The locales the config serves. */
+    locales: () => string[];
+    basePath: string | undefined;
+};
+export type ServerHalf = {
+    handle: Kit.T['handle'];
+    load: (event: Kit.ServerLoadEvent) => Promise<{
+        i18n: Kit.Payload;
+    }>;
+};

package/dist/kit/internal.js

@@ -0,0 +1 @@
+export {};

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

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

package/dist/kit/server.browser.js

@@ -0,0 +1,6 @@
+const serverOnly = () => {
+    throw new Error('[i18n]: `handle` and the server branch of `load` run on the server only.');
+};
+// What `#kit-server` resolves to under the `browser` condition: the browser
+// bundle carries this instead of the server half.
+export const serverHalf = () => ({ handle: serverOnly, load: serverOnly });

package/dist/kit/server.d.ts

@@ -0,0 +1,2 @@
+import type { ServerHalf, Shared } from './internal.js';
+export declare const serverHalf: ({ create, negotiate, locales, basePath }: Shared) => ServerHalf;

package/dist/kit/server.js

@@ -0,0 +1,72 @@
+import { logger } from '../logger.js';
+import { matchLocale, routePrefix, textDirection, withoutBasePath } from '../utils.js';
+export const serverHalf = ({ create, negotiate, locales, basePath }) => {
+    const answer = (event) => negotiate(event, event.request.headers.get('accept-language'));
+    let warned = false;
+    // A base path SvelteKit strips and `basePath` does not keeps every
+    // route-scoped loader from matching, silently. Here, on the server only, so
+    // the matcher stays out of the browser bundle.
+    const check = (event) => {
+        if (warned)
+            return;
+        const available = locales();
+        const found = routePrefix(event.url.pathname, event.route.id);
+        if (!found)
+            return;
+        const segments = found.split('/');
+        const last = segments[segments.length - 1].toLowerCase();
+        // A locale segment in front of the route is a `reroute` that strips it,
+        // spelled in the URL as a language (`en`) or a region (`en-gb`) of one.
+        const isLocale = matchLocale(last, available) !== undefined;
+        const prefix = isLocale ? segments.slice(0, -1).join('/') : found;
+        if (!prefix || withoutBasePath(prefix, basePath) === '/')
+            return;
+        warned = true;
+        logger.warn(`'${prefix}' precedes the route SvelteKit matched. If it is kit.paths.base, set basePath: '${prefix}'.`);
+    };
+    return {
+        handle: ({ event, resolve }) => {
+            let lang;
+            // Negotiated only for a chunk that asks for it, so a data request never
+            // negotiates here; a function replacement is inserted as it is.
+            const negotiated = () => {
+                if (lang === undefined) {
+                    check(event);
+                    lang = answer(event) ?? '';
+                }
+                return lang;
+            };
+            let filled = false;
+            // Only the `<html>` start tag is filled: the template writes it, while
+            // the head and the body carry the app's content, where a placeholder
+            // stays as it is written.
+            return Promise.resolve(resolve(event, {
+                transformPageChunk: ({ html }) => {
+                    if (filled)
+                        return html;
+                    filled = true;
+                    const start = html.search(/<html[\s>]/i);
+                    const end = start === -1 ? -1 : html.indexOf('>', start) + 1;
+                    if (end < 1)
+                        return html;
+                    const tag = html.slice(start, end)
+                        .replaceAll('%lang%', negotiated)
+                        .replaceAll('%dir%', () => textDirection(negotiated()));
+                    return html.slice(0, start) + tag + html.slice(end);
+                },
+            }));
+        },
+        load: async (event) => {
+            // Read before anything returns: SvelteKit re-runs a load on a
+            // navigation only for what it read.
+            const route = event.url.pathname;
+            check(event);
+            const locale = 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 }) };
+        },
+    };
+};

package/dist/kit/types.d.ts

@@ -0,0 +1,83 @@
+import type { I18n } from '../I18n.svelte.js';
+import type { Snapshot } from '../types.js';
+export declare namespace Kit {
+    /**
+     * 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.
+     */
+    type Event = {
+        url: URL;
+        params: Partial<Record<string, string>>;
+        route: {
+            id: string | null;
+        };
+        cookies?: {
+            get: (name: string) => string | undefined;
+        };
+        request?: Request;
+        locals?: Record<string, any>;
+    };
+    type RequestEvent = Event & Required<Pick<Event, 'cookies' | 'request'>>;
+    type ServerLoadEvent = RequestEvent & {
+        isDataRequest: boolean;
+    };
+    type UniversalLoadEvent = Event & {
+        data: Record<string, any> | null;
+    };
+    type Resolve = (event: any, options?: {
+        transformPageChunk?: (input: {
+            html: string;
+            done: boolean;
+        }) => string | undefined;
+    }) => Response | Promise<Response>;
+    /**
+     * What the server branch of `load` returns under `i18n`: the negotiated
+     * 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 Options = {
+        /**
+         * The visitor's choice, read from the event: a cookie, a route param, a
+         * 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.
+         *
+         * @example
+         * preferredLocale: (event) => event.cookies?.get('lang')
+         */
+        preferredLocale?: (event: Event) => string | null | undefined;
+    };
+    /** What `defineI18n()` returns. Each member is a plain function, so it can be exported on its own. */
+    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;
+            resolve: Resolve;
+        }) => Promise<Response>;
+        /** The root layout's `load`, exported from `+layout.server.js` and `+layout.js` alike. */
+        load: {
+            (event: ServerLoadEvent): Promise<{
+                i18n: Payload;
+            }>;
+            <E extends UniversalLoadEvent>(event: E): Promise<Omit<NonNullable<E['data']>, 'i18n'> & {
+                i18n: Instance;
+            }>;
+            (event: UniversalLoadEvent): Promise<{
+                i18n: Instance;
+            }>;
+        };
+        /**
+         * Called once, in the root layout's script, with a getter of its `data`.
+         * Provides the instance to every component below, and follows each
+         * navigation as it commits. Returns the instance.
+         */
+        use: (data: () => object | null | undefined) => Instance;
+        /** The instance `use()` provided, in any component below the root layout. */
+        get: () => Instance;
+    };
+}

package/dist/kit/types.js

@@ -0,0 +1 @@
+export {};