localeMatcher

localeMatcher is an option in the ECMAScript Internationalization API that controls how user-preferred locales are matched against the set of locales an application can use. It is part of the locale negotiation process used by Intl constructors and related methods to determine which locale should be applied for formatting, sorting, and other locale-sensitive operations.

The option accepts two values: lookup and best fit. The lookup algorithm is a straightforward, step-by-step matching that considers the user’s preferred locales in order and returns the first acceptable match, using exact matches first and language-only matches if needed. The best fit algorithm uses a more flexible approach that can account for script and region variants and other subtags to maximize a sensible match when an exact or simple language match is not available.

Defaults and usage: The default value for localeMatcher can vary by implementation, but many environments treat best fit as the default. The choice of localeMatcher affects how Intl.DateTimeFormat, Intl.NumberFormat, and Intl.Collator select a locale when multiple candidates are present. This can influence formatting, collation, and other locale-specific behavior, especially for languages with multiple regional or script variants.

Examples: new Intl.DateTimeFormat(['en-GB', 'fr-FR'], { localeMatcher: 'lookup' }) applies the lookup strategy, returning the first acceptable locale from the user’s list that is supported. Using best fit may yield a different, sometimes more culturally aligned locale.

See also: ECMAScript Internationalization API (ECMA-402), Intl.DateTimeFormat, Intl.NumberFormat, Intl.Collator, BCP 47 language tags, and locale negotiation concepts.