User Locale Preference Resolver

Build a utility that determines the best locale to use for a user based on their browser preferences and the locales available in your application.

Requirements

Your implementation should provide a function resolveUserLocale(requestedLocales, availableLocales, options) that:

1. Takes an array of requested locales (from user browser settings or preferences)
2. Takes an array of locales that your application supports
3. Takes an options object with:
   • defaultLocale: The fallback locale to use when no match is found (default: 'en-US')
   • algorithm: The matching strategy to use - either 'lookup' or 'best fit' (default: 'best fit')
4. Returns the best matching locale string from the available locales

The function should handle edge cases appropriately:

• Empty requested locales should return the default locale
• Empty available locales should return the default locale
• Invalid locale strings should be handled gracefully

Test Cases

• Given requested locales ['fr-CA', 'fr', 'en'], available locales ['en-US', 'fr-FR', 'es-ES'], and default 'en-US' using 'best fit' algorithm, it returns 'fr-FR' @test
• Given requested locales ['de-CH'], available locales ['de-DE', 'en-US'], and default 'en-US' using 'lookup' algorithm, it returns 'en-US' (no match found with strict lookup) @test
• Given requested locales ['zh-TW'], available locales ['zh-CN', 'zh-Hant', 'en'], and default 'en' using 'best fit' algorithm, it returns 'zh-Hant' (matches traditional Chinese variant) @test
• Given requested locales [] (empty), available locales ['en-US', 'fr-FR'], and default 'fr-FR', it returns 'fr-FR' (default locale) @test

Implementation

@generates

API

/**
 * Resolves the best locale for a user based on their preferences and available locales.
 *
 * @param {string[]} requestedLocales - Array of locale strings requested by the user (e.g., from browser settings)
 * @param {string[]} availableLocales - Array of locale strings that the application supports
 * @param {Object} options - Configuration options
 * @param {string} options.defaultLocale - The fallback locale to use when no match is found (default: 'en-US')
 * @param {string} options.algorithm - The matching algorithm: 'lookup' or 'best fit' (default: 'best fit')
 * @returns {string} The best matching locale string
 */
function resolveUserLocale(requestedLocales, availableLocales, options = {}) {
  // IMPLEMENTATION HERE
}

module.exports = { resolveUserLocale };

Dependencies { .dependencies }

@formatjs/intl-localematcher { .dependency }

Provides locale matching functionality with support for different matching algorithms.

@satisfied-by