import type { I18nError, I18nMissingKey, Locale, PluralParams, TranslationOptions, TranslationParams } from './types.js';
/**
 * 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;
    /**
     * Invoked when `t`/`translate` resolves a key *nowhere* — not the active
     * locale, not the fallback, in no package or the global bundle — and falls back
     * to rendering the key string itself. Off by default (read-tolerant: a
     * provider-less render legitimately misses keys), so this only fires when you
     * opt in — the loud signal for "this string ships as its raw key". Pair with
     * `createMissingKeyCollector` to assert "no misses" across a test/E2E run.
     */
    onMissingKey?: (info: I18nMissingKey) => 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;