Locale Preference Manager

A utility that manages locale preferences for a multi-language web application, providing both strict hierarchical locale matching and flexible linguistically-aware matching based on different use cases.

Capabilities

Strict Locale Matching

Implements strict hierarchical locale matching that follows exact fallback chains without cross-locale matching.

• Given requested locales ['en-US', 'fr-CA'], available locales ['en', 'en-GB', 'fr', 'de'], and default locale 'en', the strict matcher returns 'en' (falls back hierarchically from en-US to en, ignoring en-GB). @test
• Given requested locales ['zh-CN'], available locales ['zh-TW', 'en'], and default locale 'en', the strict matcher returns 'en' (does not match zh-TW even though both are Chinese variants). @test

Flexible Locale Matching

Implements linguistically-aware locale matching that can match across related locale variants using language distance calculations.

• Given requested locales ['en-US', 'fr-CA'], available locales ['en-GB', 'fr', 'de'], and default locale 'de', the flexible matcher returns 'en-GB' (matches en-US to en-GB as linguistically similar). @test
• Given requested locales ['zh-TW'], available locales ['zh-Hant', 'en'], and default locale 'en', the flexible matcher returns 'zh-Hant' (matches Traditional Chinese variants). @test

Locale Preference Resolution

Resolves the best locale based on user preferences and application requirements, selecting the appropriate matching strategy.

• When requireExactFallback is true, uses strict matching algorithm. @test
• When requireExactFallback is false, uses flexible matching algorithm. @test

Implementation

@generates

API

/**
 * Resolves the best locale match based on user preferences and available locales.
 *
 * @param requestedLocales - Array of locale strings requested by the user (in priority order)
 * @param availableLocales - Array of locale strings available in the application
 * @param defaultLocale - The fallback locale to use if no match is found
 * @param requireExactFallback - If true, uses strict hierarchical matching; if false, uses flexible linguistic matching
 * @returns The best matched locale string
 */
export function resolveLocale(
  requestedLocales: string[],
  availableLocales: string[],
  defaultLocale: string,
  requireExactFallback: boolean
): string;

Dependencies { .dependencies }

@formatjs/intl-localematcher { .dependency }

Provides locale matching algorithms with support for both 'lookup' and 'best fit' strategies.

@satisfied-by