@urbicon-ui/i18n 6.1.4

package/dist/i18n/registry.svelte.d.ts

@@ -0,0 +1,93 @@
+import type { I18nError, Locale, PackageTranslations, PluralParams, TranslationLoader, TranslationOptions, TranslationParams, Translations } from './types';
+import { isLocaleSupported } from './types';
+/**
+ * Module-global translation **registry** — the static, request-identical half of
+ * the old `I18nService`.
+ *
+ * It holds only read-only translation *data* (package bundles, the global
+ * mirror, loaded/loading status) and stateless resolution logic. Every resolver
+ * takes the active `locale`/`fallbackLocale` as **explicit arguments** instead of
+ * reading a stored value, so a single module-global instance is safe to share
+ * across SSR requests: there is no mutable per-request state here. The mutable
+ * locale lives in the request-scoped {@link I18nState} context instead.
+ *
+ * The data fields stay reactive (`SvelteMap`/`SvelteSet`/`$state`) so that a
+ * package registering or a locale chunk loading *after* first render still
+ * invalidates the `$derived` expressions that read them — but those mutations are
+ * idempotent and identical for every request, so they cannot leak request state.
+ */
+export declare class I18nRegistry {
+    private packageTranslations;
+    private translations;
+    private loadedLocales;
+    private loadingLocales;
+    private translationLoaders;
+    private packageLoaders;
+    private loadingPackageLocales;
+    private pluralRulesCache;
+    private numberFormatCache;
+    /**
+     * Optional error sink. Set once by the app (e.g. via the provider) so loader
+     * failures surface somewhere; defaults to `console.warn`.
+     */
+    onError?: (error: I18nError) => void;
+    get registeredPackages(): string[];
+    get isLoading(): boolean;
+    private reportError;
+    registerPackage(packageName: string, translations: PackageTranslations): void;
+    registerTranslationLoader(locale: Locale, loader: TranslationLoader): void;
+    /**
+     * Register a per-package lazy loader for one locale (WP4 code-splitting). The
+     * loader returns that package's bundle for `locale` (typically
+     * `() => import('./translations/de').then((m) => m.default)`), kept out of the
+     * initial chunk until the locale is activated.
+     */
+    registerPackageLoader(packageName: string, locale: Locale, loader: () => Promise<Translations>): void;
+    hasLoader(locale: Locale): boolean;
+    isLoaded(locale: Locale): boolean;
+    private loaderKeyLocale;
+    addTranslations(locale: Locale, translations: Translations): void;
+    /**
+     * Load every lazy bundle registered for `locale` — the legacy global loader and
+     * all per-package loaders — merging each into the (reactive) registry so that
+     * `$derived` reads re-resolve once the chunks arrive. Idempotent: bundles
+     * already present (eager or previously loaded) are skipped. Returns `false` if
+     * any triggered load rejected.
+     */
+    loadLocale(locale: Locale): Promise<boolean>;
+    private loadGlobalLocale;
+    /**
+     * Load one package's bundle for `locale` via its registered loader and merge it
+     * into the package map (so the package-scoped hook lookup finds it) and the
+     * global mirror. Idempotent; no-op when the bundle is already present or no
+     * loader is registered.
+     */
+    loadPackageLocale(packageName: string, locale: Locale): Promise<boolean>;
+    /**
+     * Whether `locale` has any resolvable data (eager or already lazily loaded).
+     * Used by the request-scoped state to decide if switching to it is safe even
+     * when its loader rejected.
+     */
+    hasTranslations(locale: Locale): boolean;
+    translate(key: string, locale: Locale, fallbackLocale: Locale, params?: TranslationParams, options?: TranslationOptions | string): string;
+    pluralize(key: string, params: PluralParams, locale: Locale, fallbackLocale: Locale, options?: TranslationOptions): string;
+    private getPluralRule;
+    private interpolate;
+    private getNestedParam;
+    private getPackageTranslation;
+    private getTranslation;
+    private deepMerge;
+    getAvailableLocales(): Locale[];
+    getPackageLocales(packageName: string): Locale[];
+    hasPackage(packageName: string): boolean;
+    getPackageTranslations(packageName: string): Partial<Record<Locale, Translations>> | undefined;
+    exists(key: string, locale: Locale, packageName?: string): boolean;
+    formatNumber(value: number, locale: Locale, options?: Intl.NumberFormatOptions): string;
+    formatDate(date: Date, locale: Locale, options?: Intl.DateTimeFormatOptions): string;
+    formatRelativeTime(value: number, unit: Intl.RelativeTimeFormatUnit, locale: Locale): string;
+    formatTimeAgo(date: Date, locale: Locale, fallbackLocale: Locale): string;
+    /** Re-exported for callers that need the guard without importing from types. */
+    isLocaleSupported: typeof isLocaleSupported;
+    reportLoadError(error: I18nError): void;
+}
+export declare function getRegistry(): I18nRegistry;

package/dist/i18n/registry.svelte.js

@@ -0,0 +1,460 @@
+import { SvelteMap, SvelteSet } from 'svelte/reactivity';
+import { getDeepValue } from '../utils/deep-keys';
+import { isLocaleSupported } from './types';
+/**
+ * Module-global translation **registry** — the static, request-identical half of
+ * the old `I18nService`.
+ *
+ * It holds only read-only translation *data* (package bundles, the global
+ * mirror, loaded/loading status) and stateless resolution logic. Every resolver
+ * takes the active `locale`/`fallbackLocale` as **explicit arguments** instead of
+ * reading a stored value, so a single module-global instance is safe to share
+ * across SSR requests: there is no mutable per-request state here. The mutable
+ * locale lives in the request-scoped {@link I18nState} context instead.
+ *
+ * The data fields stay reactive (`SvelteMap`/`SvelteSet`/`$state`) so that a
+ * package registering or a locale chunk loading *after* first render still
+ * invalidates the `$derived` expressions that read them — but those mutations are
+ * idempotent and identical for every request, so they cannot leak request state.
+ */
+export class I18nRegistry {
+    // SvelteMap/SvelteSet are reactive-wrapped so mutations (add/delete) trigger
+    // downstream $derived recomputation. Plain Map/Set inside $state are
+    // shallow-reactive only.
+    packageTranslations = new SvelteMap();
+    translations = $state({});
+    loadedLocales = new SvelteSet();
+    loadingLocales = new SvelteSet();
+    // Non-reactive per-instance cache; SvelteMap is unnecessary here.
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    translationLoaders = new Map();
+    // Per-package lazy loaders (WP4 code-splitting), keyed `${packageName}::${locale}`.
+    // Registered at module-eval, read in setLocale/loadLocale (not in a $derived), so
+    // a plain Map suffices. The *loaded data* lands in the reactive packageTranslations,
+    // which is what re-resolves `$derived` reads when a chunk arrives.
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    packageLoaders = new Map();
+    // Reactive: `isLoading` derives from its size.
+    loadingPackageLocales = new SvelteSet();
+    // Per-locale Intl caches. Constructing an Intl.* object negotiates the locale
+    // on every `new`; caching by locale avoids that cost when plural()/formatNumber
+    // run inside a large {#each}. Keyed by locale only (options-bearing calls skip
+    // the cache — they are rare and varied).
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    pluralRulesCache = new Map();
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    numberFormatCache = new Map();
+    /**
+     * Optional error sink. Set once by the app (e.g. via the provider) so loader
+     * failures surface somewhere; defaults to `console.warn`.
+     */
+    onError;
+    get registeredPackages() {
+        return Array.from(this.packageTranslations.keys());
+    }
+    get isLoading() {
+        return this.loadingLocales.size > 0 || this.loadingPackageLocales.size > 0;
+    }
+    reportError(error) {
+        if (this.onError) {
+            this.onError(error);
+            return;
+        }
+        switch (error.type) {
+            case 'load-failed':
+                console.warn(`Failed to load translations for locale: ${error.locale}`, error.cause);
+                break;
+            case 'unsupported-locale':
+                console.warn(`Locale ${error.locale} is not supported`);
+                break;
+            case 'load-failed-no-fallback':
+                console.warn(`Failed to load locale ${error.locale}, falling back to current locale`);
+                break;
+        }
+    }
+    // --- registration / loading (static data; idempotent, request-identical) ---
+    registerPackage(packageName, translations) {
+        this.packageTranslations.set(packageName, translations);
+        Object.entries(translations).forEach(([locale, trans]) => {
+            this.addTranslations(locale, { [packageName]: trans });
+        });
+    }
+    registerTranslationLoader(locale, loader) {
+        this.translationLoaders.set(locale, loader);
+    }
+    /**
+     * Register a per-package lazy loader for one locale (WP4 code-splitting). The
+     * loader returns that package's bundle for `locale` (typically
+     * `() => import('./translations/de').then((m) => m.default)`), kept out of the
+     * initial chunk until the locale is activated.
+     */
+    registerPackageLoader(packageName, locale, loader) {
+        this.packageLoaders.set(`${packageName}::${locale}`, loader);
+    }
+    hasLoader(locale) {
+        if (this.translationLoaders.has(locale))
+            return true;
+        for (const key of this.packageLoaders.keys()) {
+            if (this.loaderKeyLocale(key) === locale)
+                return true;
+        }
+        return false;
+    }
+    // Reflects only *global* loader loads (registerTranslationLoader), not
+    // per-package lazy loads — a purely-lazy-package locale stays `false` here. The
+    // setLocale gate pairs it with hasLoader() and relies on load*Locale being
+    // idempotent, so the narrowed meaning is safe there; don't reuse it as a general
+    // "is this locale's data present" check (use packageTranslations/getPackageLocales).
+    isLoaded(locale) {
+        return this.loadedLocales.has(locale);
+    }
+    loaderKeyLocale(key) {
+        return key.slice(key.lastIndexOf('::') + 2);
+    }
+    addTranslations(locale, translations) {
+        if (!this.translations[locale]) {
+            this.translations[locale] = {};
+        }
+        this.translations[locale] = this.deepMerge(this.translations[locale], translations);
+    }
+    /**
+     * Load every lazy bundle registered for `locale` — the legacy global loader and
+     * all per-package loaders — merging each into the (reactive) registry so that
+     * `$derived` reads re-resolve once the chunks arrive. Idempotent: bundles
+     * already present (eager or previously loaded) are skipped. Returns `false` if
+     * any triggered load rejected.
+     */
+    async loadLocale(locale) {
+        const tasks = [this.loadGlobalLocale(locale)];
+        for (const key of this.packageLoaders.keys()) {
+            if (this.loaderKeyLocale(key) === locale) {
+                tasks.push(this.loadPackageLocale(key.slice(0, key.lastIndexOf('::')), locale));
+            }
+        }
+        const results = await Promise.all(tasks);
+        return results.every(Boolean);
+    }
+    // Legacy global-loader path. Returns true when there is nothing to do (no
+    // global loader / already loaded) — "no loader" is not a failure.
+    async loadGlobalLocale(locale) {
+        const loader = this.translationLoaders.get(locale);
+        if (!loader || this.loadedLocales.has(locale) || this.loadingLocales.has(locale)) {
+            return true;
+        }
+        this.loadingLocales.add(locale);
+        try {
+            const translations = await loader(locale);
+            this.addTranslations(locale, translations);
+            this.loadedLocales.add(locale);
+            return true;
+        }
+        catch (error) {
+            this.reportError({ type: 'load-failed', locale, cause: error });
+            return false;
+        }
+        finally {
+            this.loadingLocales.delete(locale);
+        }
+    }
+    /**
+     * Load one package's bundle for `locale` via its registered loader and merge it
+     * into the package map (so the package-scoped hook lookup finds it) and the
+     * global mirror. Idempotent; no-op when the bundle is already present or no
+     * loader is registered.
+     */
+    async loadPackageLocale(packageName, locale) {
+        if (this.packageTranslations.get(packageName)?.[locale])
+            return true;
+        const key = `${packageName}::${locale}`;
+        const loader = this.packageLoaders.get(key);
+        if (!loader || this.loadingPackageLocales.has(key))
+            return true;
+        this.loadingPackageLocales.add(key);
+        try {
+            const data = await loader();
+            // New object reference per merge so the SvelteMap notifies subscribers
+            // (SvelteMap.set only signals when the value reference changes — an in-place
+            // mutation would NOT re-run the $derived reads). `existing` is read AFTER the
+            // await, so two concurrent loads of different non-base locales for the same
+            // package (e.g. de + fr) each see the other's already-merged result and don't
+            // lose a write.
+            const existing = this.packageTranslations.get(packageName) ?? {};
+            this.packageTranslations.set(packageName, { ...existing, [locale]: data });
+            this.addTranslations(locale, { [packageName]: data });
+            return true;
+        }
+        catch (error) {
+            this.reportError({ type: 'load-failed', locale, cause: error });
+            return false;
+        }
+        finally {
+            this.loadingPackageLocales.delete(key);
+        }
+    }
+    /**
+     * Whether `locale` has any resolvable data (eager or already lazily loaded).
+     * Used by the request-scoped state to decide if switching to it is safe even
+     * when its loader rejected.
+     */
+    hasTranslations(locale) {
+        return (!!this.translations[locale] ||
+            Array.from(this.packageTranslations.values()).some((pkg) => !!pkg[locale]));
+    }
+    // --- resolution (locale threaded explicitly — no stored locale) ---
+    translate(key, locale, fallbackLocale, params, options) {
+        const opts = typeof options === 'string'
+            ? { packageName: options, fallbackToGlobal: true, interpolate: true }
+            : { fallbackToGlobal: true, interpolate: true, ...options };
+        let translation;
+        if (!opts.packageName && key.includes('.')) {
+            const potentialPackage = key.split('.')[0];
+            if (this.packageTranslations.has(potentialPackage)) {
+                const packageKey = key.substring(potentialPackage.length + 1);
+                translation = this.getPackageTranslation(potentialPackage, packageKey, locale);
+                if (translation) {
+                    return opts.interpolate ? this.interpolate(translation, locale, params) : translation;
+                }
+            }
+        }
+        if (opts.packageName) {
+            translation = this.getPackageTranslation(opts.packageName, key, locale);
+            if (translation) {
+                return opts.interpolate ? this.interpolate(translation, locale, params) : translation;
+            }
+            translation = this.getPackageTranslation(opts.packageName, key, fallbackLocale);
+            if (translation) {
+                return opts.interpolate ? this.interpolate(translation, locale, params) : translation;
+            }
+        }
+        if (opts.fallbackToGlobal !== false) {
+            translation = this.getTranslation(key, locale) || this.getTranslation(key, fallbackLocale);
+        }
+        if (!translation) {
+            translation = key;
+        }
+        return opts.interpolate ? this.interpolate(translation, locale, params) : translation;
+    }
+    pluralize(key, params, locale, fallbackLocale, options) {
+        const count = params.count;
+        const pluralKey = `${key}_plural`;
+        const pluralTranslation = this.translate(pluralKey, locale, fallbackLocale, undefined, {
+            ...options,
+            interpolate: false
+        });
+        if (pluralTranslation !== pluralKey) {
+            try {
+                const rules = JSON.parse(pluralTranslation);
+                const rule = this.getPluralRule(count, locale);
+                // `??`, not `||`: an intentional empty-string entry must survive. A
+                // well-formed object always provides `other`; JSON.parse does not enforce
+                // that, so if the parsed object lacks it (or holds a non-string), treat it
+                // as malformed and fall through to the base form via catch — never
+                // interpolate `undefined` (which would throw inside String.replace).
+                const selectedTranslation = rules[rule] ?? rules.other;
+                if (typeof selectedTranslation !== 'string') {
+                    throw new Error(`_plural object for "${key}" lacks a string "other" entry`);
+                }
+                return this.interpolate(selectedTranslation, locale, params);
+            }
+            catch {
+                // Malformed `_plural` JSON: fall through to the base form below rather
+                // than guess. fail-honest, not fail-wrong.
+            }
+        }
+        // No CLDR `_plural` object for this key. Return the base translation as-is
+        // (deterministically the singular/`other` form the author wrote) instead of
+        // the old anglocentric `+'s'` heuristic, which produced wrong strings for
+        // every non-English locale. Correct pluralization requires a `<key>_plural`
+        // entry; see PluralRules.
+        const singularTranslation = this.translate(key, locale, fallbackLocale, undefined, {
+            ...options,
+            interpolate: false
+        });
+        return this.interpolate(singularTranslation, locale, params);
+    }
+    // CLDR plural category for `count` in `locale`, delegated to the platform's
+    // Intl.PluralRules. Covers zero/one/two/few/many/other for any BCP-47 locale —
+    // consistent with formatNumber/formatDate, which already use Intl.
+    getPluralRule(count, locale) {
+        let rules = this.pluralRulesCache.get(locale);
+        if (!rules) {
+            rules = new Intl.PluralRules(locale);
+            this.pluralRulesCache.set(locale, rules);
+        }
+        return rules.select(count);
+    }
+    interpolate(text, locale, params) {
+        if (!params)
+            return text;
+        return text.replace(/\{\{([^}]+)\}\}/g, (match, key) => {
+            const trimmedKey = key.trim();
+            const value = this.getNestedParam(params, trimmedKey);
+            if (value === undefined || value === null) {
+                console.warn(`Missing translation parameter: ${trimmedKey}`);
+                return match;
+            }
+            if (typeof value === 'function') {
+                try {
+                    return value()?.toString() ?? match;
+                }
+                catch (error) {
+                    console.warn(`Error executing function parameter: ${trimmedKey}`, error);
+                    return match;
+                }
+            }
+            if (typeof value === 'number') {
+                return this.formatNumber(value, locale);
+            }
+            if (value instanceof Date) {
+                return this.formatDate(value, locale);
+            }
+            return String(value);
+        });
+    }
+    getNestedParam(params, path) {
+        return path.split('.').reduce((current, key) => {
+            return current && typeof current === 'object'
+                ? current[key]
+                : undefined;
+        }, params);
+    }
+    getPackageTranslation(packageName, key, locale) {
+        const pkgTranslations = this.packageTranslations.get(packageName);
+        const entry = pkgTranslations?.[locale];
+        if (entry) {
+            const value = getDeepValue(entry, key);
+            return typeof value === 'string' ? value : undefined;
+        }
+        return undefined;
+    }
+    getTranslation(key, locale) {
+        const entry = this.translations[locale];
+        if (entry) {
+            const value = getDeepValue(entry, key);
+            return typeof value === 'string' ? value : undefined;
+        }
+        return undefined;
+    }
+    deepMerge(target, source) {
+        const output = { ...target };
+        for (const key in source) {
+            if (Object.hasOwn(source, key)) {
+                const sourceValue = source[key];
+                const targetValue = target[key];
+                if (typeof sourceValue === 'object' &&
+                    sourceValue !== null &&
+                    !Array.isArray(sourceValue) &&
+                    typeof targetValue === 'object' &&
+                    targetValue !== null &&
+                    !Array.isArray(targetValue)) {
+                    output[key] = this.deepMerge(targetValue, sourceValue);
+                }
+                else {
+                    output[key] = sourceValue;
+                }
+            }
+        }
+        return output;
+    }
+    // --- introspection ---
+    getAvailableLocales() {
+        // Local accumulator — not reactive state.
+        // eslint-disable-next-line svelte/prefer-svelte-reactivity
+        const allLocales = new Set();
+        Object.keys(this.translations).forEach((locale) => {
+            allLocales.add(locale);
+        });
+        this.packageTranslations.forEach((packageTrans) => {
+            Object.keys(packageTrans).forEach((locale) => {
+                allLocales.add(locale);
+            });
+        });
+        this.translationLoaders.forEach((_, locale) => {
+            allLocales.add(locale);
+        });
+        // Locales reachable only through a not-yet-loaded per-package lazy loader.
+        this.packageLoaders.forEach((_, key) => {
+            allLocales.add(this.loaderKeyLocale(key));
+        });
+        return Array.from(allLocales);
+    }
+    getPackageLocales(packageName) {
+        // Eager/loaded locales plus any registered lazy loaders for the package.
+        // eslint-disable-next-line svelte/prefer-svelte-reactivity
+        const locales = new Set(Object.keys(this.packageTranslations.get(packageName) ?? {}));
+        const prefix = `${packageName}::`;
+        this.packageLoaders.forEach((_, key) => {
+            if (key.startsWith(prefix))
+                locales.add(this.loaderKeyLocale(key));
+        });
+        return Array.from(locales);
+    }
+    hasPackage(packageName) {
+        return this.packageTranslations.has(packageName);
+    }
+    getPackageTranslations(packageName) {
+        return this.packageTranslations.get(packageName);
+    }
+    exists(key, locale, packageName) {
+        if (packageName) {
+            return this.getPackageTranslation(packageName, key, locale) !== undefined;
+        }
+        return this.getTranslation(key, locale) !== undefined;
+    }
+    // --- formatting (locale threaded explicitly) ---
+    formatNumber(value, locale, options) {
+        if (options) {
+            return new Intl.NumberFormat(locale, options).format(value);
+        }
+        let fmt = this.numberFormatCache.get(locale);
+        if (!fmt) {
+            fmt = new Intl.NumberFormat(locale);
+            this.numberFormatCache.set(locale, fmt);
+        }
+        return fmt.format(value);
+    }
+    formatDate(date, locale, options) {
+        return new Intl.DateTimeFormat(locale, options).format(date);
+    }
+    formatRelativeTime(value, unit, locale) {
+        return new Intl.RelativeTimeFormat(locale).format(value, unit);
+    }
+    formatTimeAgo(date, locale, fallbackLocale) {
+        // Local timestamp — not reactive state.
+        // eslint-disable-next-line svelte/prefer-svelte-reactivity
+        const now = new Date();
+        const seconds = Math.round((now.getTime() - date.getTime()) / 1000);
+        const minutes = Math.round(seconds / 60);
+        const hours = Math.round(minutes / 60);
+        const days = Math.round(hours / 24);
+        const tr = (key, params) => this.translate(key, locale, fallbackLocale, params);
+        if (seconds < 45)
+            return tr('time.ago.now');
+        if (minutes < 45)
+            return tr(minutes === 1 ? 'time.units.minute' : 'time.units.minutes', { count: minutes });
+        if (hours < 22)
+            return tr(hours === 1 ? 'time.units.hour' : 'time.units.hours', { count: hours });
+        if (days < 30)
+            return tr(days === 1 ? 'time.units.day' : 'time.units.days', { count: days });
+        return this.formatDate(date, locale);
+    }
+    /** Re-exported for callers that need the guard without importing from types. */
+    isLocaleSupported = isLocaleSupported;
+    reportLoadError(error) {
+        this.reportError(error);
+    }
+}
+// Lazy, hoisted accessor for the process-wide registry. Holding the registry at
+// module scope is correct *because* it carries no per-request mutable locale —
+// only static, request-identical translation data. But it is built on first
+// touch (not at module top-level) and reached through this hoisted function so
+// that a consumer chunk's top-level `createPackageI18n` side-effect — which
+// Vite 8 / Rolldown may order before this module's body — still finds a callable
+// binding and an initialised instance, instead of a value in the temporal dead
+// zone (the `Cannot read properties of undefined (reading 'registerPackage')`
+// class of bug the old lazy singleton guarded against).
+let _registry;
+export function getRegistry() {
+    _registry ??= new I18nRegistry();
+    return _registry;
+}

package/dist/i18n/resolve-locale.d.ts

@@ -0,0 +1,41 @@
+import { type Locale } from './types';
+/**
+ * Header-like source for {@link resolveLocale}. Pass a `Request` (its `cookie` and
+ * `accept-language` headers are read) or a plain object with the raw header
+ * strings — keeps the helper framework-agnostic.
+ */
+export interface LocaleSource {
+    /** Raw `Cookie` request header, e.g. `theme=dark; urbicon-locale=de`. */
+    cookie?: string | null;
+    /** Raw `Accept-Language` request header, e.g. `de-DE,de;q=0.9,en;q=0.8`. */
+    acceptLanguage?: string | null;
+}
+export interface ResolveLocaleOptions {
+    /**
+     * Locales the app actually ships data for. Resolution never returns a locale
+     * outside this set. Defaults to the locales currently registered in the
+     * registry (so it tracks "data optional"), falling back to all
+     * {@link SUPPORTED_LOCALES} if nothing is registered yet.
+     */
+    supportedLocales?: readonly Locale[];
+    /** Returned when neither cookie nor Accept-Language yields a supported locale. @default 'en' */
+    defaultLocale?: Locale;
+    /** Name of the cookie holding the persisted locale choice. @default 'urbicon-locale' */
+    cookieName?: string;
+}
+/**
+ * Resolve the initial locale for a request, server-side: persisted cookie first,
+ * then the browser's `Accept-Language`, then the default. Feed the result to
+ * `<I18nProvider locale={…}>` so SSR and hydration agree (no client-only
+ * `navigator.language` guess, no hydration mismatch).
+ *
+ * ```ts
+ * // +layout.server.ts
+ * export const load = ({ request }) => ({ locale: resolveLocale(request) });
+ * ```
+ *
+ * Detection is the consumer's choice — this helper is optional. Persisting the
+ * cookie on switch is the consumer's job too (e.g. in the provider's
+ * `onLocaleChange`); this only reads it back.
+ */
+export declare function resolveLocale(source: Request | LocaleSource, options?: ResolveLocaleOptions): Locale;

package/dist/i18n/resolve-locale.js

@@ -0,0 +1,81 @@
+import { getRegistry } from './registry.svelte';
+import { SUPPORTED_LOCALES } from './types';
+function readHeaders(source) {
+    if (typeof Request !== 'undefined' && source instanceof Request) {
+        return {
+            cookie: source.headers.get('cookie'),
+            acceptLanguage: source.headers.get('accept-language')
+        };
+    }
+    return source;
+}
+function parseCookie(header, name) {
+    if (!header)
+        return undefined;
+    for (const part of header.split(';')) {
+        const eq = part.indexOf('=');
+        if (eq === -1)
+            continue;
+        if (part.slice(0, eq).trim() === name) {
+            return decodeURIComponent(part.slice(eq + 1).trim());
+        }
+    }
+    return undefined;
+}
+/**
+ * Parse `Accept-Language` and return the first base language (`en` from `en-US`)
+ * present in `supported`, honouring the `q` weighting order.
+ */
+function parseAcceptLanguage(header, supported) {
+    if (!header)
+        return undefined;
+    const ranked = header
+        .split(',')
+        .map((part) => {
+        const [tag, ...params] = part.trim().split(';');
+        const q = params.find((p) => p.trim().startsWith('q='));
+        const weight = q ? Number.parseFloat(q.trim().slice(2)) : 1;
+        return { tag: tag.trim().toLowerCase(), weight: Number.isNaN(weight) ? 0 : weight };
+    })
+        .filter((entry) => entry.tag && entry.weight > 0)
+        .sort((a, b) => b.weight - a.weight);
+    for (const { tag } of ranked) {
+        const base = tag.split('-')[0];
+        if (supported.has(base))
+            return base;
+    }
+    return undefined;
+}
+/**
+ * Resolve the initial locale for a request, server-side: persisted cookie first,
+ * then the browser's `Accept-Language`, then the default. Feed the result to
+ * `<I18nProvider locale={…}>` so SSR and hydration agree (no client-only
+ * `navigator.language` guess, no hydration mismatch).
+ *
+ * ```ts
+ * // +layout.server.ts
+ * export const load = ({ request }) => ({ locale: resolveLocale(request) });
+ * ```
+ *
+ * Detection is the consumer's choice — this helper is optional. Persisting the
+ * cookie on switch is the consumer's job too (e.g. in the provider's
+ * `onLocaleChange`); this only reads it back.
+ */
+export function resolveLocale(source, options = {}) {
+    const available = getRegistry().getAvailableLocales();
+    const supportedList = options.supportedLocales ?? (available.length > 0 ? available : SUPPORTED_LOCALES);
+    const supported = new Set(supportedList);
+    const fallback = options.defaultLocale ?? 'en';
+    const cookieName = options.cookieName ?? 'urbicon-locale';
+    const { cookie, acceptLanguage } = readHeaders(source);
+    // 1. Persisted explicit choice.
+    const fromCookie = parseCookie(cookie, cookieName);
+    if (fromCookie && supported.has(fromCookie))
+        return fromCookie;
+    // 2. Browser preference.
+    const fromHeader = parseAcceptLanguage(acceptLanguage, supported);
+    if (fromHeader)
+        return fromHeader;
+    // 3. Default.
+    return fallback;
+}