User Locale Preference Resolver

A service that resolves user locale preferences with support for Unicode extensions, integrating with available application locales to determine the best locale configuration for internationalization.

Capabilities

Resolves basic locale preferences

• Given user preferences ['en-US'] and available locales ['en', 'es', 'fr'], it returns a result with locale 'en' and dataLocale 'en' @test
• Given user preferences ['fr-CA', 'en-US'] and available locales ['en', 'fr', 'de'], it returns a result with locale 'fr' and dataLocale 'fr' @test

Handles Unicode calendar extensions

• Given user preferences ['en-US-u-ca-buddhist'] and available locales ['en'] with locale data supporting buddhist calendar, it returns a result with calendar property set to 'buddhist' @test
• Given user preferences ['en-US-u-ca-gregory'] and available locales ['en'], when user options specify {calendar: 'islamic'}, it returns a result with calendar property set to 'islamic' (options override extensions) @test

Handles Unicode numbering system extensions

• Given user preferences ['ar-EG-u-nu-arab'] and available locales ['ar'] with locale data supporting arab numbering system, it returns a result with numberingSystem property set to 'arab' @test
• Given user preferences ['zh-CN-u-nu-hanidec'] and available locales ['zh'], when locale data does not support hanidec, it falls back to the default numbering system from locale data @test

Handles multiple Unicode extensions

• Given user preferences ['en-US-u-ca-gregory-nu-latn-hc-h23'] and available locales ['en'] with appropriate locale data, it returns a result with all extension properties resolved: calendar 'gregory', numberingSystem 'latn', and hourCycle 'h23' @test

Implementation

@generates

API

/**
 * Resolves user locale preferences against available locales with Unicode extension support.
 *
 * @param {string[]} availableLocales - Array of locale strings supported by the application
 * @param {string[]} requestedLocales - Array of locale strings requested by the user (in preference order)
 * @param {Object} options - User options that can override extension values
 * @param {Object} localeData - Locale-specific data containing supported values for extensions
 * @param {string[]} relevantExtensionKeys - Array of Unicode extension keys to process (e.g., ['ca', 'nu', 'hc'])
 * @returns {Object} Result object containing:
 *   - locale: The resolved locale string (with extensions)
 *   - dataLocale: The locale to use for data lookups (without extensions)
 *   - extension properties: Values for each relevant extension key
 */
function resolveUserLocale(availableLocales, requestedLocales, options, localeData, relevantExtensionKeys) {
  // IMPLEMENTATION HERE
}

module.exports = {
  resolveUserLocale
};

Dependencies { .dependencies }

@formatjs/intl-localematcher { .dependency }

Provides locale resolution and Unicode extension processing capabilities.

@satisfied-by