/** * Locale Resolution Utilities * * Provides a cascade system for resolving locale/language preferences: * 1. Component's explicit `locale` attribute (highest priority) * 2. Closest ancestor's `lang` attribute * 3. Document root's `lang` attribute * 4. Browser's language preference * 5. 'en-US' fallback (lowest priority) * * This allows developers to set locale at any level: * - Per-component: * - Per-section:
* - Per-page: * - Browser default: Uses navigator.language * * @example * ```typescript * // In a component * class TyInput extends HTMLElement { * get locale(): string { * return getEffectiveLocale(this, this.getAttribute('locale')); * } * } * ``` */ /** * Get the effective locale for an element using the resolution cascade. * * Resolution order: * 1. Explicit locale attribute on the element * 2. Closest ancestor element with a `lang` attribute * 3. Document root element's `lang` attribute * 4. Browser's navigator.language * 5. Fallback to 'en-US' * * @param element - The element to get locale for * @param explicitLocale - Optional explicit locale value (from component's locale attribute) * @returns The resolved locale string (e.g., 'en-US', 'fr-FR') * * @example * ```html * *
* * *
* * * ``` */ export declare function getEffectiveLocale(element: HTMLElement, explicitLocale?: string | null): string; /** * Normalize a locale string to BCP 47 format. * Handles common variations and ensures consistency. * * @param locale - The locale string to normalize * @returns Normalized locale string * * @example * ```typescript * normalizeLocale('en') // 'en' * normalizeLocale('en_US') // 'en-US' * normalizeLocale('EN-us') // 'en-US' * ``` */ export declare function normalizeLocale(locale: string): string; /** * Check if a locale string is valid BCP 47 format. * * @param locale - The locale string to validate * @returns true if valid, false otherwise * * @example * ```typescript * isValidLocale('en-US') // true * isValidLocale('fr') // true * isValidLocale('invalid!') // false * ``` */ export declare function isValidLocale(locale: string): boolean; /** * Get the language code from a locale (e.g., 'en' from 'en-US'). * * @param locale - The locale string * @returns The language code * * @example * ```typescript * getLanguageCode('en-US') // 'en' * getLanguageCode('fr-FR') // 'fr' * getLanguageCode('de') // 'de' * ``` */ export declare function getLanguageCode(locale: string): string; /** * Get the region/country code from a locale (e.g., 'US' from 'en-US'). * * @param locale - The locale string * @returns The region code, or undefined if not present * * @example * ```typescript * getRegionCode('en-US') // 'US' * getRegionCode('fr-FR') // 'FR' * getRegionCode('de') // undefined * ``` */ export declare function getRegionCode(locale: string): string | undefined; /** * Create a MutationObserver to watch for lang attribute changes. * Useful for components that need to react to dynamic locale changes. * * @param element - The element to observe * @param callback - Function to call when lang changes * @returns Cleanup function to disconnect the observer * * @example * ```typescript * class TyInput extends HTMLElement { * private _localeObserver?: () => void; * * connectedCallback() { * this._localeObserver = observeLocaleChanges(this, () => { * this.render(); // Re-render when locale changes * }); * } * * disconnectedCallback() { * this._localeObserver?.(); * } * } * ``` */ export declare function observeLocaleChanges(element: HTMLElement, callback: (newLocale: string) => void): () => void; //# sourceMappingURL=locale.d.ts.map