High-Performance Locale Matcher

Build a high-performance locale matching system that can efficiently match user-requested locales against a large set of available locales (500+ locales). The system must handle exact matches, fallback scenarios, and cross-locale matching while maintaining sub-5ms performance.

Requirements

Your implementation should:

1. Accept a list of user-requested locales (in order of preference) and a list of available locales
2. Return the best matching locale from the available locales
3. Handle exact locale matches with optimal performance (O(1) lookup)
4. Support locale fallback with maximization (e.g., zh-TW should match zh-Hant-TW)
5. Implement position-based preference weighting (earlier requested locales should have higher priority)
6. Use caching mechanisms to avoid redundant computations across multiple matching calls
7. Scale efficiently to 500+ available locales with consistent sub-5ms performance

Performance Requirements

• Exact matches should complete in under 2ms
• Fallback matches should complete in under 3ms
• The system should handle at least 500 available locales efficiently
• Repeated calls with the same locale sets should benefit from caching

Test Cases

• When given requested locale ['en-US'] and available locales ['en-US', 'fr-FR', 'de-DE'], it returns 'en-US' @test
• When given requested locale ['zh-TW'] and available locales ['zh-Hant-TW', 'zh-Hans-CN', 'en-US'], it returns 'zh-Hant-TW' @test
• When given requested locales ['fr-CA', 'en-GB'] and available locales ['en-US', 'fr-FR', 'de-DE'], it returns 'fr-FR' with preference to the first requested locale @test
• When called twice with the same locale sets, the second call completes faster due to caching @test

Implementation

@generates

API

/**
 * Matches the best available locale based on user preferences.
 *
 * @param {string[]} requestedLocales - Array of user-requested locales in order of preference
 * @param {string[]} availableLocales - Array of locales available in the application
 * @param {Object} [options] - Optional configuration
 * @param {string} [options.defaultLocale='en'] - Default locale to return if no match found
 * @returns {string} The best matching locale from availableLocales
 */
function matchLocale(requestedLocales, availableLocales, options) {
  // IMPLEMENTATION HERE
}

module.exports = {
  matchLocale
};

Dependencies { .dependencies }

@formatjs/intl-localematcher { .dependency }

Provides sophisticated locale resolution and matching algorithms with three-tier optimization for high-performance matching.