/** * Locale negotiation and detection — 1.14.0 additions. * * Pure helpers that complement {@link createI18n}; they can be used at * application bootstrap to pick a starting locale before constructing * the i18n instance. * * @module bquery/i18n * @since 1.14.0 */ /** * Options for {@link negotiateLocale}. * * @since 1.14.0 */ export type NegotiateLocaleOptions = { /** * Fallback locale returned when no requested tag matches an available one. * Defaults to the first entry of `available`. */ fallback?: string; /** * When `true` (default), a language match without an exact region match * is allowed (e.g. `'de-CH'` matches available `'de'`). */ matchLanguage?: boolean; }; /** * Pure locale negotiation — matches a list of requested locale tags * (in priority order) against the available set, returning the best match. * * Matching strategy: * 1. Exact match (case-insensitive). * 2. Language-only match when `matchLanguage` is `true`. * 3. Fallback (either the provided `fallback` option or the first available). * * @since 1.14.0 * * @example * ```ts * import { negotiateLocale } from '@bquery/bquery/i18n'; * * negotiateLocale(['de-CH', 'en'], ['en', 'de', 'fr']); // 'de' * negotiateLocale(['fr-CA'], ['en', 'fr']); // 'fr' * negotiateLocale(['ja'], ['en', 'de'], { fallback: 'en' }); // 'en' * ``` */ export declare const negotiateLocale: (requested: readonly string[], available: readonly string[], options?: NegotiateLocaleOptions) => string; /** * Options for {@link detectLocale}. * * @since 1.14.0 */ export type DetectLocaleOptions = { /** * The full set of available locale tags. When provided, the detected * locale is run through {@link negotiateLocale}. */ available?: readonly string[]; /** Fallback locale returned when detection finds nothing usable. */ fallback?: string; /** * Whether to read `document.documentElement.lang` first. Default `true`. */ readHtmlLang?: boolean; /** * Whether to read `navigator.languages` / `navigator.language`. Default `true`. */ readNavigator?: boolean; /** * Optional cookie name to read. When a value is found, it is used as the * highest-priority hint. */ cookieName?: string; /** * Optional `localStorage` key to read. When present, takes priority over * navigator/html sources but yields to `cookieName`. */ storageKey?: string; }; /** * Detects the user's preferred locale from a chain of common sources: * `cookieName` → `storageKey` → `` → `navigator.languages`. * * When `available` is provided, the candidate list is funneled through * {@link negotiateLocale} so that the returned tag is guaranteed to be one * of the available locales (or `fallback`). * * @since 1.14.0 * * @example * ```ts * import { detectLocale } from '@bquery/bquery/i18n'; * * const locale = detectLocale({ * available: ['en', 'de', 'fr'], * cookieName: 'lang', * storageKey: 'locale', * fallback: 'en', * }); * ``` */ export declare const detectLocale: (options?: DetectLocaleOptions) => string; /** * Returns `true` when the given locale or language tag uses a right-to-left * script. Detection uses {@link Intl.Locale} when available and falls back * to a hard-coded list of well-known RTL languages. * * @since 1.14.0 * * @example * ```ts * import { isRTL } from '@bquery/bquery/i18n'; * * isRTL('en'); // false * isRTL('ar-EG'); // true * isRTL('fa'); // true * ``` */ export declare const isRTL: (locale: string) => boolean; //# sourceMappingURL=locale.d.ts.map