/**
 * Generic i18n factory for ContractSpec packages.
 *
 * Eliminates the boilerplate duplicated across package-level
 * i18n/messages.ts files by extracting the common interpolation,
 * registry management, locale resolution, and t() wiring.
 *
 * @module translations/i18n-factory
 */
import type { TranslationSpec } from './spec';
/** Default locale when none is specified. */
export declare const DEFAULT_LOCALE = "en";
/** Supported locales shipped with ContractSpec packages. */
export declare const SUPPORTED_LOCALES: readonly ["en", "fr", "es"];
/** A locale included in the default set. */
export type SupportedLocale = (typeof SUPPORTED_LOCALES)[number];
/**
 * Resolve the effective locale from two optional overrides.
 *
 * Priority: `runtimeLocale > optionsLocale > DEFAULT_LOCALE`.
 * Falls back to base language (e.g., `"fr-CA"` -> `"fr"`) when needed.
 */
export declare function resolveLocale(optionsLocale?: string, runtimeLocale?: string): string;
/** Check whether a string is a supported locale. */
export declare function isSupportedLocale(locale: string): locale is SupportedLocale;
/**
 * Simple placeholder interpolation.
 *
 * Replaces `{key}` tokens with values from the params map.
 * Does NOT handle full ICU (plurals, selects) — only simple
 * string/number substitution.
 */
export declare function interpolate(template: string, params?: Record<string, string | number>): string;
/**
 * A package-scoped i18n instance.
 *
 * @typeParam K - Union type of valid message keys for the package
 */
export interface I18nInstance<K extends string = string> {
    /** Translate a message key with optional placeholder interpolation. */
    t(key: K | string, params?: Record<string, string | number>): string;
    /** The effective locale being used. */
    readonly locale: string;
}
/** Configuration for `createI18nFactory`. */
export interface I18nFactoryConfig {
    /** The spec key used to register translations (e.g., `"ai-agent.messages"`). */
    specKey: string;
    /** Translation catalogs to register (typically `[en, fr, es]`). */
    catalogs: TranslationSpec[];
}
/** The object returned by `createI18nFactory`. */
export interface I18nFactory<K extends string = string> {
    /** Create an i18n instance for a given locale. */
    create(optionsLocale?: string, runtimeLocale?: string): I18nInstance<K>;
    /** Create a default (English) i18n instance. */
    getDefault(): I18nInstance<K>;
    /** Reset the shared registry (useful for testing). */
    resetRegistry(): void;
}
/**
 * Create a package-scoped i18n factory.
 *
 * Replaces the ~100 lines of boilerplate previously duplicated
 * in every package's `i18n/messages.ts`.
 *
 * @typeParam K - The package's message key union type
 * @param config - Spec key and translation catalogs
 * @returns An I18nFactory with `create()`, `getDefault()`, and `resetRegistry()`
 *
 * @example
 * ```ts
 * import { createI18nFactory } from '@contractspec/lib.contracts-spec/translations';
 * import type { AgentMessageKey } from './keys';
 * import { enMessages } from './catalogs/en';
 * import { frMessages } from './catalogs/fr';
 * import { esMessages } from './catalogs/es';
 *
 * const factory = createI18nFactory<AgentMessageKey>({
 *   specKey: 'ai-agent.messages',
 *   catalogs: [enMessages, frMessages, esMessages],
 * });
 *
 * export type AgentI18n = I18nInstance<AgentMessageKey>;
 * export const createAgentI18n = factory.create;
 * export const getDefaultI18n = factory.getDefault;
 * export const resetI18nRegistry = factory.resetRegistry;
 * ```
 */
export declare function createI18nFactory<K extends string = string>(config: I18nFactoryConfig): I18nFactory<K>;
