/**
 * A translator bound to a single locale, as returned by `make_translator`.
 */
export type Translator = {
    /**
     * The resolved BCP-47 locale code actually in use
     * (English when the request could not be resolved).
     */
    code: string;
    /**
     * The originally requested code when it
     * was unsupported and fell back to English; otherwise
     * `null`.
     */
    unsupported: string | null;
    /**
     *                          Look up a localized string by namespace and key,
     *                          interpolating `{name}` placeholders from `params`.
     *                          Returns `"ns.key"` when the key is unknown.
     */
    t: (ns: string, key: string, params?: object) => string;
    /**
     * Format a date in the locale's medium
     * date style.
     */
    date: (d: Date) => string;
    /**
     * Format a time in the locale's medium
     * time style.
     */
    time: (d: Date) => string;
    /**
     * Format a number for the locale.
     */
    number: (n: number) => string;
};
export const SUPPORTED: string[];
export const FALLBACK: "en";
/**
 * A translator bound to a single locale, as returned by `make_translator`.
 *
 * @typedef {object} Translator
 * @property {string} code  The resolved BCP-47 locale code actually in use
 *                          (English when the request could not be resolved).
 * @property {string | null} unsupported  The originally requested code when it
 *                          was unsupported and fell back to English; otherwise
 *                          `null`.
 * @property {(ns: string, key: string, params?: object) => string} t
 *                          Look up a localized string by namespace and key,
 *                          interpolating `{name}` placeholders from `params`.
 *                          Returns `"ns.key"` when the key is unknown.
 * @property {(d: Date) => string} date  Format a date in the locale's medium
 *                          date style.
 * @property {(d: Date) => string} time  Format a time in the locale's medium
 *                          time style.
 * @property {(n: number) => string} number  Format a number for the locale.
 */
/**
 * Load and parse a locale's JSON string table from disk.
 *
 * @param {string} code  A locale code naming a file in the locales directory.
 * @returns {object | null}  The parsed locale object, or `null` when the file
 *                           is missing or cannot be parsed.
 *
 * @example
 *   load_locale('fr');   // { changelog: { ... }, ui: { ... } }
 *   load_locale('xx');   // null
 *
 * @see make_translator
 */
export function load_locale(code: string): object | null;
/**
 * Resolve a requested language code to a supported locale code.
 *
 * Matches case-insensitively, treats `_` and `-` as equivalent, and falls
 * back to a base-language match (so `pt-BR` resolves to `pt`).
 *
 * @param {string | null | undefined} requested  The requested language code.
 * @returns {string | null}  A supported locale code, or `null` when nothing
 *                            matches (or no code was requested).
 *
 * @example
 *   resolve_code('pt_BR');   // 'pt'
 *   resolve_code('xx');      // null
 *
 * @see make_translator
 */
export function resolve_code(requested: string | null | undefined): string | null;
/**
 * Substitute `{name}` placeholders in a string with values from a params bag.
 *
 * A placeholder whose name is absent from `params` is left untouched.
 *
 * @param {string} str  The template string containing `{name}` placeholders.
 * @param {object} params  Map of placeholder name to substitution value.
 * @returns {string}  The string with every known placeholder replaced.
 *
 * @example
 *   interpolate('Hello {who}', { who: 'world' });   // 'Hello world'
 *   interpolate('Hello {who}', {});                 // 'Hello {who}'
 */
export function interpolate(str: string, params: object): string;
/**
 * Build a translator bound to a single locale.
 *
 * @param {string | null | undefined} requested  A language code such as 'fr'
 *                   or 'pt-BR'. An unknown code resolves to English and is
 *                   reported back via `unsupported`.
 * @param {object} [localeData]  Optional pre-loaded locale object used instead
 *                   of reading the locale file from disk. Intended for tests;
 *                   production callers omit it.
 * @returns {Translator}  A translator object whose members are: `code` (the
 *                   resolved locale code), `unsupported` (the originally
 *                   requested code when it fell back to English, else `null`),
 *                   `t` (the `t(ns, key, params?)` string-lookup function),
 *                   `date` and `time` (locale-aware `Date` formatters), and
 *                   `number` (a locale-aware number formatter).
 *
 * @example
 *   const tr = make_translator('fr');
 *   tr.t('changelog', 'untagged');   // the French string, or English if absent
 *
 * @see Translator
 * @see resolve_code
 */
export function make_translator(requested: string | null | undefined, localeData?: object): Translator;
/**
 * Determine which locale to use for the CLI's own user-interface strings.
 *
 * An explicit `argLang` wins outright.  Otherwise the `LC_ALL`, `LC_MESSAGES`,
 * and `LANG` environment variables are consulted (ignoring the `C`/`POSIX`
 * locales), then the host's resolved `Intl` locale, then English.
 *
 * @param {string | null | undefined} argLang  An explicit language code (e.g.
 *                   from a `--lang` flag), or a falsy value to auto-detect.
 * @param {Record<string, string>} [env]  Environment variables to read;
 *                   defaults to `process.env`. Intended for tests.
 * @returns {string}  The detected locale code (never empty; falls back to 'en').
 *
 * @example
 *   detect_ui_locale('fr');                              // 'fr'
 *   detect_ui_locale(null, { LANG: 'de_DE.UTF-8' });     // 'de-DE'
 *
 * @see make_translator
 */
export function detect_ui_locale(argLang: string | null | undefined, env?: Record<string, string>): string;