Smart Locale Matcher

Build a smart locale matching tool that finds the linguistically best matching locale from a set of available options.

Requirements

Implement a tool that:

1. Takes a requested locale and a list of available locales
2. Finds the linguistically closest matching locale using sophisticated matching algorithms
3. Returns the best matching locale from the available options
4. Uses intelligent matching that considers linguistic similarity (e.g., en-US is linguistically closer to en-GB than to fr-FR)
5. Falls back to a default locale when no suitable match is found

Expected Behavior

• Use sophisticated matching that accounts for language, script, and region differences
• Handle locale variants intelligently (e.g., Traditional Chinese can match Simplified Chinese with appropriate linguistic distance)
• Prefer linguistically closer matches over distant ones
• Support cross-regional matching (e.g., en-US can match en-GB)
• Default to a fallback locale when no close match exists

Test Cases

• When given requested locale en-US, available locales ['en-GB', 'fr-FR', 'de-DE'], and default en-GB, returns en-GB (closest linguistic match) @test
• When given requested locale zh-TW, available locales ['zh-CN', 'zh-HK', 'ja-JP'], and default zh-CN, returns zh-CN or zh-HK (linguistically related Chinese variants) @test
• When given requested locale en, available locales ['en-US', 'en-GB', 'en-AU'], and default en-US, returns one of the English variants @test
• When given requested locale fr-CA, available locales ['zh-CN', 'ja-JP', 'ko-KR'], and default en-US, returns en-US (no linguistically close match found) @test

Implementation

@generates

API

/**
 * Finds the best matching locale from available options
 *
 * @param requestedLocale - The requested locale to match
 * @param availableLocales - Array of available locale strings
 * @param defaultLocale - Fallback locale when no suitable match is found
 * @returns The best matching locale string
 */
export function matchLocale(
  requestedLocale: string,
  availableLocales: string[],
  defaultLocale: string
): string;

Dependencies { .dependencies }

@formatjs/intl-localematcher { .dependency }

Provides locale matching with CLDR-based language distance calculation.