@urbicon-ui/i18n 6.1.4

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

@@ -0,0 +1,107 @@
+import type { I18nError, Locale, PluralParams, TranslationOptions, TranslationParams } from './types';
+/**
+ * The constant base locale used for read-tolerant resolution when no
+ * `<I18nProvider>` is mounted. A constant — never global mutable state — so a
+ * provider-less render is SSR-safe and identical on server and client (no
+ * hydration mismatch), and reads never leak across requests. Consumers who need
+ * a different or switchable locale mount a provider.
+ */
+export declare const BASE_LOCALE: Locale;
+/**
+ * Request-scoped reactive locale state. The *only* mutable per-request i18n
+ * value — created by `<I18nProvider>` and read through the context. Encapsulated:
+ * `locale` is exposed read-only; switching goes through `setLocale`.
+ */
+export declare class I18nState {
+    #private;
+    /** Fallback locale used when a key is missing in the active locale. */
+    readonly fallbackLocale: Locale;
+    constructor(locale?: Locale, fallbackLocale?: Locale);
+    get locale(): Locale;
+    /**
+     * Switch the active locale in place (reactive — no reload). Returns `false`
+     * (and reports `unsupported-locale`) for an unsupported locale, without
+     * switching. For a supported locale the switch is applied immediately and
+     * `true` is returned ("switch initiated"): if a lazy loader is registered and
+     * the data isn't present yet, the load is triggered (not awaited) so the
+     * `$derived` reads re-resolve once the chunk lands. Use `registry.loadLocale`
+     * directly when you need to await.
+     *
+     * The async failure is not silent: if that load rejects AND no data exists for
+     * the locale (so reads can't even fall back to it), `load-failed-no-fallback`
+     * is reported to the error sink — the loud signal that "the language you
+     * switched to can't be rendered". (No-op today, where all bundles are eager.)
+     */
+    setLocale(locale: Locale): boolean;
+}
+/** Set the request-scoped locale state. Called by `<I18nProvider>`. */
+export declare function provideI18nState(state: I18nState): I18nState;
+/**
+ * Read the request-scoped locale state, or `undefined` when no `<I18nProvider>`
+ * is mounted above (read-tolerant). Must be called during component init.
+ */
+export declare function useI18nState(): I18nState | undefined;
+/**
+ * Provide the request-scoped locale state from a component's own init, and return
+ * it. This is the primitive behind `<I18nProvider>`; reach for it directly when
+ * the **same** component both provides i18n and renders translated content —
+ * e.g. a root `+layout.svelte` whose own chrome uses `t`. (A child
+ * `<I18nProvider>` cannot serve the parent that mounts it, because context only
+ * flows downward; calling `provideI18n` in the parent's script puts the state on
+ * that component's own context map, which its own `useI18n()`/`use<Pkg>I18n()`
+ * then reads.)
+ *
+ * Pass `locale` as a reactive getter (`() => data.locale`) to keep it controlled:
+ * a prop/load change is synced into the state, while an in-place `setLocale`
+ * switch (which doesn't change the getter's value) is never clobbered.
+ *
+ * Must be called during component initialisation.
+ */
+export declare function provideI18n(locale: Locale | (() => Locale), fallbackLocale?: Locale): I18nState;
+/**
+ * General i18n hook for locale control and locale-aware formatting/resolution.
+ *
+ * Read paths (`locale`, `t`, formatters) are tolerant: without a provider they
+ * resolve against {@link BASE_LOCALE}. The write path (`setLocale`) is strict:
+ * without a provider it throws, because there is no request-scoped state to
+ * mutate — "you asked to switch the language but never mounted an
+ * `<I18nProvider>`". Call during component initialisation.
+ */
+export interface I18nApi {
+    /** Active locale (reactive). Falls back to {@link BASE_LOCALE} without a provider. */
+    readonly locale: Locale;
+    /** Locales with registered data or a loader (reactive). */
+    readonly availableLocales: Locale[];
+    /** Whether a lazy locale load is in flight (reactive). */
+    readonly isLoading: boolean;
+    /** Switch the active locale. Throws without a provider. */
+    setLocale(locale: Locale): boolean;
+    t(key: string, params?: TranslationParams, options?: TranslationOptions | string): string;
+    plural(key: string, params: PluralParams, options?: TranslationOptions): string;
+    exists(key: string, packageName?: string): boolean;
+    formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
+    formatDate(date: Date, options?: Intl.DateTimeFormatOptions): string;
+    formatRelativeTime(value: number, unit: Intl.RelativeTimeFormatUnit): string;
+    formatTimeAgo(date: Date): string;
+}
+export declare function useI18n(): I18nApi;
+export interface I18nConfigureOptions {
+    /**
+     * Routes i18n errors — a lazy locale load that rejects (`load-failed`,
+     * `load-failed-no-fallback`), or a `setLocale` with an unsupported code
+     * (`unsupported-locale`) — to your handler instead of the default
+     * `console.warn`. The hook for telemetry (Sentry, structured logging).
+     */
+    onError?: (error: I18nError) => void;
+}
+/**
+ * App-global i18n configuration. Call **once at startup** (module scope or root
+ * setup), not per-request: the handler lives on the process-wide registry, so a
+ * per-request assignment under concurrent SSR would race. Without it, errors fall
+ * back to `console.warn`.
+ *
+ * ```ts
+ * configureI18n({ onError: (e) => reportToSentry(e) });
+ * ```
+ */
+export declare function configureI18n(options: I18nConfigureOptions): void;

package/dist/i18n/context.svelte.js

@@ -0,0 +1,167 @@
+import { getContext, hasContext, setContext, untrack } from 'svelte';
+import { getRegistry } from './registry.svelte';
+import { isLocaleSupported } from './types';
+/**
+ * The constant base locale used for read-tolerant resolution when no
+ * `<I18nProvider>` is mounted. A constant — never global mutable state — so a
+ * provider-less render is SSR-safe and identical on server and client (no
+ * hydration mismatch), and reads never leak across requests. Consumers who need
+ * a different or switchable locale mount a provider.
+ */
+export const BASE_LOCALE = 'en';
+/**
+ * Request-scoped reactive locale state. The *only* mutable per-request i18n
+ * value — created by `<I18nProvider>` and read through the context. Encapsulated:
+ * `locale` is exposed read-only; switching goes through `setLocale`.
+ */
+export class I18nState {
+    // Private $state field: external code can read `.locale` but must go through
+    // `setLocale` to change it (validation + lazy-load trigger live there).
+    #locale = $state(BASE_LOCALE);
+    /** Fallback locale used when a key is missing in the active locale. */
+    fallbackLocale;
+    constructor(locale = BASE_LOCALE, fallbackLocale = BASE_LOCALE) {
+        this.#locale = locale;
+        this.fallbackLocale = fallbackLocale;
+    }
+    get locale() {
+        return this.#locale;
+    }
+    /**
+     * Switch the active locale in place (reactive — no reload). Returns `false`
+     * (and reports `unsupported-locale`) for an unsupported locale, without
+     * switching. For a supported locale the switch is applied immediately and
+     * `true` is returned ("switch initiated"): if a lazy loader is registered and
+     * the data isn't present yet, the load is triggered (not awaited) so the
+     * `$derived` reads re-resolve once the chunk lands. Use `registry.loadLocale`
+     * directly when you need to await.
+     *
+     * The async failure is not silent: if that load rejects AND no data exists for
+     * the locale (so reads can't even fall back to it), `load-failed-no-fallback`
+     * is reported to the error sink — the loud signal that "the language you
+     * switched to can't be rendered". (No-op today, where all bundles are eager.)
+     */
+    setLocale(locale) {
+        const registry = getRegistry();
+        if (!isLocaleSupported(locale)) {
+            registry.reportLoadError({ type: 'unsupported-locale', locale });
+            return false;
+        }
+        if (registry.hasLoader(locale) && !registry.isLoaded(locale)) {
+            // loadLocale never rejects (it reports `load-failed` internally); inspect
+            // its boolean result to surface the harder "switched but unrenderable" case.
+            registry.loadLocale(locale).then((ok) => {
+                if (!ok && !registry.hasTranslations(locale)) {
+                    registry.reportLoadError({ type: 'load-failed-no-fallback', locale });
+                }
+            });
+        }
+        this.#locale = locale;
+        return true;
+    }
+}
+// Symbol key + explicit typed accessors rather than svelte's `createContext`:
+// its generated getter calls `e.missing_context()` (throws) when no provider is
+// mounted, which is incompatible with the read-tolerant contract below (a
+// provider-less <Button> must still render its ARIA strings in baseLocale). A
+// Symbol is collision-free and type-safe — the convention's intent ("no string
+// keys") holds; only the throw-on-missing semantics are traded for tolerance.
+const I18N_CONTEXT_KEY = Symbol('urbicon-ui-i18n');
+/** Set the request-scoped locale state. Called by `<I18nProvider>`. */
+export function provideI18nState(state) {
+    return setContext(I18N_CONTEXT_KEY, state);
+}
+/**
+ * Read the request-scoped locale state, or `undefined` when no `<I18nProvider>`
+ * is mounted above (read-tolerant). Must be called during component init.
+ */
+export function useI18nState() {
+    return hasContext(I18N_CONTEXT_KEY) ? getContext(I18N_CONTEXT_KEY) : undefined;
+}
+/**
+ * Provide the request-scoped locale state from a component's own init, and return
+ * it. This is the primitive behind `<I18nProvider>`; reach for it directly when
+ * the **same** component both provides i18n and renders translated content —
+ * e.g. a root `+layout.svelte` whose own chrome uses `t`. (A child
+ * `<I18nProvider>` cannot serve the parent that mounts it, because context only
+ * flows downward; calling `provideI18n` in the parent's script puts the state on
+ * that component's own context map, which its own `useI18n()`/`use<Pkg>I18n()`
+ * then reads.)
+ *
+ * Pass `locale` as a reactive getter (`() => data.locale`) to keep it controlled:
+ * a prop/load change is synced into the state, while an in-place `setLocale`
+ * switch (which doesn't change the getter's value) is never clobbered.
+ *
+ * Must be called during component initialisation.
+ */
+export function provideI18n(locale, fallbackLocale = BASE_LOCALE) {
+    const getLocale = typeof locale === 'function' ? locale : () => locale;
+    const state = new I18nState(untrack(getLocale), fallbackLocale);
+    provideI18nState(state);
+    if (typeof locale === 'function') {
+        // Controlled sync: depend on the getter only (untrack the state read) so a
+        // prop change flows in but setLocale() is not reverted.
+        $effect(() => {
+            const next = getLocale();
+            if (next !== untrack(() => state.locale)) {
+                state.setLocale(next);
+            }
+        });
+    }
+    // Ensure the initial active + fallback locales' lazy bundles are loaded (WP4) —
+    // a no-op when everything is eager. Client-only (effects don't run during SSR),
+    // so a lazy non-base initial locale renders the fallback on the server and the
+    // first client paint, then re-resolves once the chunk lands. Subsequent switches
+    // load via setLocale. Read untracked → runs once on mount, not on every switch.
+    $effect(() => {
+        const registry = getRegistry();
+        void registry.loadLocale(untrack(() => state.locale));
+        void registry.loadLocale(state.fallbackLocale);
+    });
+    return state;
+}
+export function useI18n() {
+    const state = useI18nState();
+    const registry = getRegistry();
+    const localeOf = () => state?.locale ?? BASE_LOCALE;
+    const fallbackOf = () => state?.fallbackLocale ?? BASE_LOCALE;
+    return {
+        get locale() {
+            return localeOf();
+        },
+        get availableLocales() {
+            return registry.getAvailableLocales();
+        },
+        get isLoading() {
+            return registry.isLoading;
+        },
+        setLocale(locale) {
+            if (!state) {
+                throw new Error('[i18n] setLocale() requires an <I18nProvider>. Without a provider the locale ' +
+                    'is the constant base locale and cannot change. Wrap your app root in ' +
+                    '<I18nProvider locale={…}> to enable locale switching.');
+            }
+            return state.setLocale(locale);
+        },
+        t: (key, params, options) => registry.translate(key, localeOf(), fallbackOf(), params, options),
+        plural: (key, params, options) => registry.pluralize(key, params, localeOf(), fallbackOf(), options),
+        exists: (key, packageName) => registry.exists(key, localeOf(), packageName),
+        formatNumber: (value, options) => registry.formatNumber(value, localeOf(), options),
+        formatDate: (date, options) => registry.formatDate(date, localeOf(), options),
+        formatRelativeTime: (value, unit) => registry.formatRelativeTime(value, unit, localeOf()),
+        formatTimeAgo: (date) => registry.formatTimeAgo(date, localeOf(), fallbackOf())
+    };
+}
+/**
+ * App-global i18n configuration. Call **once at startup** (module scope or root
+ * setup), not per-request: the handler lives on the process-wide registry, so a
+ * per-request assignment under concurrent SSR would race. Without it, errors fall
+ * back to `console.warn`.
+ *
+ * ```ts
+ * configureI18n({ onError: (e) => reportToSentry(e) });
+ * ```
+ */
+export function configureI18n(options) {
+    getRegistry().onError = options.onError;
+}

package/dist/i18n/package-integration.d.ts

@@ -0,0 +1,118 @@
+import type { CreatePackageTypes, Locale, PackageI18n, PackageTranslations, TranslationParams, TranslationSchema, Translations, TypedTranslationFunction } from './types';
+export interface CreatePackageI18nOptions {
+    /**
+     * Per-locale lazy loaders (WP4 code-splitting). Each returns the package's
+     * bundle for that locale as a dynamic-import chunk, e.g.
+     * `() => import('./translations/de').then((m) => m.default)`. Listed locales
+     * stay out of the initial bundle until activated by the provider / `setLocale`;
+     * the eager bundle passed in `translations` (typically `en`) is the base/
+     * fallback. Compile-time key parity is NOT checked for lazy locales — pair with
+     * `validatePackageTranslations` in a test to guard parity at runtime/CI.
+     */
+    loaders?: Partial<Record<Locale, () => Promise<Translations>>>;
+}
+/**
+ * Creates a standardized i18n integration for a package.
+ *
+ * Generic over the `en` bundle: with `<const T>` the literal key/param types of
+ * `en` flow through `PackageI18n<T>` into a fully typed `t` — real `DeepKeys<T>`
+ * plus `ExtractParams`, so `t('dialog.close')` autocompletes and
+ * `t('dialog.nope')` is a compile error. Other locales are checked against
+ * `TranslationSchema<T>` (T's structure with its string values widened), which
+ * enforces key parity at compile time while allowing locale-specific strings.
+ *
+ * Opt-in code-splitting (WP4): pass `options.loaders` to keep non-base locales
+ * out of the initial bundle as dynamic-import chunks, loaded only when activated.
+ */
+export declare function createPackageI18n<const T extends Translations>(packageName: string, translations: {
+    en: T;
+} & Partial<Record<Locale, TranslationSchema<T>>>, options?: CreatePackageI18nOptions): PackageI18n<T>;
+/**
+ * Creates a package-translations descriptor (data only — does NOT register).
+ *
+ * @deprecated Superseded by {@link createPackageI18n}, which registers and
+ * returns a typed `t` in one step. Retained for back-compat; the `types` field
+ * is a non-functional placeholder (`CreatePackageTypes<Translations>` degenerates
+ * to `string` keys, predating the generic factory).
+ */
+export declare function createPackageTranslations(packageName: string, translations: Partial<Record<Locale, Translations>>): {
+    packageName: string;
+    translations: Partial<Record<"en" | "de" | "fr" | "es" | "it" | "nl", Translations>>;
+    types: CreatePackageTypes<Translations>;
+};
+/**
+ * Creates a typed translation package with auto-registration.
+ *
+ * @deprecated Use {@link createPackageI18n} directly. Since that factory became
+ * generic (`<const T>`) it already infers literal keys and returns a fully typed
+ * `t`; this wrapper adds only a redundant `tt` alias and a `packageName`/
+ * `translations` passthrough. Kept as a thin, typed shim for back-compat — it
+ * will be removed in a future major.
+ */
+export declare function createTypedPackage<const T extends Translations>(packageName: string, translations: {
+    en: T;
+} & Partial<Record<Locale, TranslationSchema<T>>>): {
+    packageName: string;
+    translations: {
+        en: T;
+    } & Partial<Record<"en" | "de" | "fr" | "es" | "it" | "nl", TranslationSchema<T>>>;
+    tt: TypedTranslationFunction<T>;
+    useTranslate: () => TypedTranslationFunction<T>;
+    t: TypedTranslationFunction<T>;
+    exists: (key: string) => boolean;
+    getLocales: () => Locale[];
+    register: () => void;
+    types: CreatePackageTypes<T>;
+};
+/**
+ * Register translation loaders for lazy loading
+ * Useful for larger packages with many translations
+ */
+export declare function registerTranslationLoaders(loaders: Record<Locale, () => Promise<Translations>>): void;
+/**
+ * Smart component integration helper
+ * Provides common patterns for component i18n integration
+ */
+export declare function createComponentI18n<const T extends Translations>(packageName: string, translations: {
+    en: T;
+} & Partial<Record<Locale, TranslationSchema<T>>>, defaultOptions?: {
+    useI18n?: boolean;
+    fallbackToGlobal?: boolean;
+}): {
+    getText: (key: string, customText?: string, params?: TranslationParams, options?: {
+        useI18n?: boolean;
+    }) => string;
+    maybeT: (key: string, params?: TranslationParams, options?: {
+        useI18n?: boolean;
+        fallback?: string;
+    }) => string;
+    useTranslate: () => TypedTranslationFunction<T>;
+    t: TypedTranslationFunction<T>;
+    exists: (key: string) => boolean;
+    getLocales: () => Locale[];
+    register: () => void;
+    types: CreatePackageTypes<T>;
+};
+/**
+ * Batch register multiple packages
+ * Useful for apps that use many packages
+ */
+export declare function registerPackages(packages: Array<{
+    name: string;
+    translations: PackageTranslations;
+}>): void;
+/**
+ * Validates deep-key parity across a package's locale bundles.
+ *
+ * Compares the full recursive leaf-key set (not just top-level keys) of every
+ * locale against the base locale (`en` first by convention). A missing nested
+ * key is an error; an extra nested key is a warning. Pair with a per-package
+ * vitest assertion (`expect(errors).toEqual([])`) to fail CI on drift —
+ * complementing the compile-time parity `satisfies`/generic factory enforce for
+ * statically-typed bundles, and covering dynamically/lazily loaded ones.
+ */
+export declare function validatePackageTranslations(packageName: string, translations: Partial<Record<Locale, Translations>>): {
+    isValid: boolean;
+    errors: string[];
+    warnings: string[];
+};

package/dist/i18n/package-integration.js

@@ -0,0 +1,211 @@
+import { collectDeepKeys } from '../utils/deep-keys';
+import { BASE_LOCALE, useI18nState } from './context.svelte';
+import { getRegistry } from './registry.svelte';
+/**
+ * Creates a standardized i18n integration for a package.
+ *
+ * Generic over the `en` bundle: with `<const T>` the literal key/param types of
+ * `en` flow through `PackageI18n<T>` into a fully typed `t` — real `DeepKeys<T>`
+ * plus `ExtractParams`, so `t('dialog.close')` autocompletes and
+ * `t('dialog.nope')` is a compile error. Other locales are checked against
+ * `TranslationSchema<T>` (T's structure with its string values widened), which
+ * enforces key parity at compile time while allowing locale-specific strings.
+ *
+ * Opt-in code-splitting (WP4): pass `options.loaders` to keep non-base locales
+ * out of the initial bundle as dynamic-import chunks, loaded only when activated.
+ */
+export function createPackageI18n(packageName, translations, options) {
+    // Eager registration at module-init time. The previous lazy variant
+    // (queueMicrotask inside t()) returned the raw key on first call and
+    // never re-triggered the reactive expression that read it, so consumers
+    // saw `filter.button.add` instead of the translated string.
+    //
+    // Running synchronously here is safe: `createPackageI18n` is invoked at
+    // module top-level (`export const tableI18n = createPackageI18n(...)`),
+    // which is outside any $derived/$effect — so the SvelteMap mutation in
+    // `registerPackage` cannot trip the `state_unsafe_mutation` rule.
+    //
+    // Goes through `getRegistry()` (a hoisted function), NOT a module-const binding:
+    // this call fires at consumer module-eval time, and under Vite 8 / Rolldown a
+    // reordered chunk can run it before the registry module's body ran. A hoisted
+    // function binding survives that; the lazy getter then builds the registry on
+    // first touch, in whatever order the chunks happen to fire.
+    getRegistry().registerPackage(packageName, translations);
+    // Opt-in lazy locales (WP4): register dynamic-import loaders. The eager bundle
+    // above is the base; these cover the rest, loaded on demand by the provider /
+    // setLocale. Parity for lazy bundles is a runtime concern (validatePackageTranslations).
+    if (options?.loaders) {
+        const registry = getRegistry();
+        for (const [locale, loader] of Object.entries(options.loaders)) {
+            if (loader)
+                registry.registerPackageLoader(packageName, locale, loader);
+        }
+    }
+    // Context-scoped hook — the SSR-correct, reactive accessor. Captures the
+    // request-scoped locale state at component init (or `undefined` without a
+    // provider → base locale), then resolves against the static registry. Reading
+    // `state.locale` inside the returned closure (called from a `$derived`) makes
+    // call-sites re-render on locale change; reading the registry's SvelteMap makes
+    // them re-render when a package registers more translations.
+    const useTranslate = () => {
+        const state = useI18nState();
+        const registry = getRegistry();
+        return ((key, params, options) => registry.translate(key, state?.locale ?? BASE_LOCALE, state?.fallbackLocale ?? BASE_LOCALE, params, { packageName, ...options }));
+    };
+    // Non-hook `t` for non-component use (tests, server utilities). Resolves
+    // against the base locale — there is no request-scoped state outside a
+    // component. Components use `useTranslate` for the reactive, provider-scoped
+    // locale.
+    const t = ((key, params, options) => getRegistry().translate(key, BASE_LOCALE, BASE_LOCALE, params, {
+        packageName,
+        ...options
+    }));
+    const exists = (key) => getRegistry().exists(key, BASE_LOCALE, packageName);
+    const getLocales = () => getRegistry().getPackageLocales(packageName);
+    // No-op kept for API back-compat with callers that used to invoke `register()`
+    // before reading translations. Registration now happens eagerly above.
+    const register = () => { };
+    return {
+        useTranslate,
+        t,
+        exists,
+        getLocales,
+        register,
+        types: {}
+    };
+}
+/**
+ * Creates a package-translations descriptor (data only — does NOT register).
+ *
+ * @deprecated Superseded by {@link createPackageI18n}, which registers and
+ * returns a typed `t` in one step. Retained for back-compat; the `types` field
+ * is a non-functional placeholder (`CreatePackageTypes<Translations>` degenerates
+ * to `string` keys, predating the generic factory).
+ */
+export function createPackageTranslations(packageName, translations) {
+    return {
+        packageName,
+        translations,
+        types: {}
+    };
+}
+/**
+ * Creates a typed translation package with auto-registration.
+ *
+ * @deprecated Use {@link createPackageI18n} directly. Since that factory became
+ * generic (`<const T>`) it already infers literal keys and returns a fully typed
+ * `t`; this wrapper adds only a redundant `tt` alias and a `packageName`/
+ * `translations` passthrough. Kept as a thin, typed shim for back-compat — it
+ * will be removed in a future major.
+ */
+export function createTypedPackage(packageName, translations) {
+    const packageI18n = createPackageI18n(packageName, translations);
+    return {
+        ...packageI18n,
+        packageName,
+        translations,
+        // Convenient alias
+        tt: packageI18n.t
+    };
+}
+/**
+ * Register translation loaders for lazy loading
+ * Useful for larger packages with many translations
+ */
+export function registerTranslationLoaders(loaders) {
+    Object.entries(loaders).forEach(([locale, loader]) => {
+        getRegistry().registerTranslationLoader(locale, loader);
+    });
+}
+/**
+ * Smart component integration helper
+ * Provides common patterns for component i18n integration
+ */
+export function createComponentI18n(packageName, translations, defaultOptions) {
+    const packageI18n = createPackageI18n(packageName, translations);
+    return {
+        ...packageI18n,
+        // Smart text resolution for components
+        getText: (key, customText, params, options) => {
+            // If custom text provided and i18n disabled, use custom text
+            if (customText && options?.useI18n === false) {
+                return customText;
+            }
+            const loose = packageI18n.t;
+            return loose(key, params, {
+                fallbackToGlobal: defaultOptions?.fallbackToGlobal ?? true
+            });
+        },
+        // Conditional translation (useful for optional i18n)
+        maybeT: (key, params, options) => {
+            if (options?.useI18n === false) {
+                return options.fallback || key;
+            }
+            const loose = packageI18n.t;
+            return loose(key, params);
+        }
+    };
+}
+/**
+ * Batch register multiple packages
+ * Useful for apps that use many packages
+ */
+export function registerPackages(packages) {
+    packages.forEach(({ name, translations }) => {
+        getRegistry().registerPackage(name, translations);
+    });
+}
+/**
+ * Validates deep-key parity across a package's locale bundles.
+ *
+ * Compares the full recursive leaf-key set (not just top-level keys) of every
+ * locale against the base locale (`en` first by convention). A missing nested
+ * key is an error; an extra nested key is a warning. Pair with a per-package
+ * vitest assertion (`expect(errors).toEqual([])`) to fail CI on drift —
+ * complementing the compile-time parity `satisfies`/generic factory enforce for
+ * statically-typed bundles, and covering dynamically/lazily loaded ones.
+ */
+// Non-generic on purpose: this is a runtime structural check. A generic
+// `<T>(…: Partial<Record<Locale, T>>)` would bind every locale to the SAME `T`
+// inferred from `en`, so a `de` bundle with different string literals (the
+// normal case under `as const`) fails to assign. `Translations` widens the
+// values, decoupling the locales — parity is verified at runtime via keys.
+export function validatePackageTranslations(packageName, translations) {
+    const errors = [];
+    const warnings = [];
+    const locales = Object.keys(translations);
+    if (locales.length === 0) {
+        errors.push(`[${packageName}] No translations provided`);
+        return { isValid: false, errors, warnings };
+    }
+    // Prefer `en` as the base: the error (missing) vs warning (extra) asymmetry
+    // is only meaningful against the canonical source locale, not whichever key
+    // Object.keys happens to return first.
+    const baseLocale = locales.includes('en') ? 'en' : locales[0];
+    const baseBundle = translations[baseLocale];
+    if (!baseBundle) {
+        errors.push(`[${packageName}] Base locale ${baseLocale} has no translations`);
+        return { isValid: false, errors, warnings };
+    }
+    const baseKeys = collectDeepKeys(baseBundle);
+    const baseKeySet = new Set(baseKeys);
+    locales.slice(1).forEach((locale) => {
+        const bundle = translations[locale];
+        if (!bundle)
+            return;
+        const localeKeySet = new Set(collectDeepKeys(bundle));
+        const missingKeys = baseKeys.filter((key) => !localeKeySet.has(key));
+        const extraKeys = [...localeKeySet].filter((key) => !baseKeySet.has(key));
+        if (missingKeys.length > 0) {
+            errors.push(`[${packageName}] Locale ${locale} missing keys: ${missingKeys.join(', ')}`);
+        }
+        if (extraKeys.length > 0) {
+            warnings.push(`[${packageName}] Locale ${locale} has extra keys: ${extraKeys.join(', ')}`);
+        }
+    });
+    return {
+        isValid: errors.length === 0,
+        errors,
+        warnings
+    };
+}