Multipage preference

Stage 1 Draft / November 1, 2026

Intl.LocaleMatcher

Introduction

This working draft prepares application-supplied locales once and matches requests without implicit defaulting. Best-fit policy and data remain implementation-defined.

In Constructor Properties of the Intl Object, add Intl.LocaleMatcher and exclude it, alongside Intl.Locale, from the service constructors. It matches application resources rather than negotiating an implementation's supported services.

1 LocaleMatcher Objects

The objects and functions defined here follow ECMA-402's requirements for standard built-in ECMAScript objects.

1.1 The Intl.LocaleMatcher Constructor

The Intl.LocaleMatcher constructor is %Intl.LocaleMatcher%, the initial value of the "LocaleMatcher" property of the Intl object.

1.1.1 Intl.LocaleMatcher ( availableLocales [ , options ] )

  1. If NewTarget is undefined, throw a TypeError exception.
  2. Let slots be « [[InitializedLocaleMatcher]], [[AvailableLocales]], [[LocaleMatcher]] ».
  3. Let matcher be ? OrdinaryCreateFromConstructor(NewTarget, "%Intl.LocaleMatcher.prototype%", slots).
  4. Let available be ? CanonicalizeLocaleList(availableLocales).
  5. For each element locale of available, do
    1. If locale contains a Unicode locale extension sequence, throw a RangeError exception.
  6. Set options to ? GetOptionsObject(options).
  7. Let algorithm be ? GetOption(options, "algorithm", string, « "lookup", "best fit" », "best fit").
  8. Set matcher.[[AvailableLocales]] to available.
  9. Set matcher.[[LocaleMatcher]] to algorithm.
  10. Set matcher.[[InitializedLocaleMatcher]] to true.
  11. Return matcher.

The "length" property of Intl.LocaleMatcher is 1𝔽.

Note
Available locales describe app resources. No host default, parent tags, or Intl service support is required. CanonicalizeLocaleList copies and deduplicates them; later input or option mutations do not change the matcher. Implementations may prepare reusable indices, without a required technique or timing guarantee.

1.2 Properties of the Intl.LocaleMatcher Constructor

The constructor has a [[Prototype]] internal slot whose value is %Function.prototype%.

1.2.1 Intl.LocaleMatcher.prototype

The value of this property is %Intl.LocaleMatcher.prototype%.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

1.3 Properties of the Intl.LocaleMatcher Prototype Object

The prototype object is %Intl.LocaleMatcher.prototype%, an ordinary object with [[Prototype]] %Object.prototype%. It is not a LocaleMatcher instance and has none of the instance internal slots.

1.3.1 Intl.LocaleMatcher.prototype.constructor

The initial value is %Intl.LocaleMatcher%.

1.3.2 Intl.LocaleMatcher.prototype.match ( requestedLocales )

  1. Let matcher be the this value.
  2. Perform ? RequireInternalSlot(matcher, [[InitializedLocaleMatcher]]).
  3. Let requested be ? CanonicalizeLocaleList(requestedLocales).
  4. Let available be matcher.[[AvailableLocales]].
  5. If requested is empty or available is empty, return undefined.
  6. If matcher.[[LocaleMatcher]] is "lookup", then
    1. Let match be LookupMatchingLocaleByPrefix(available, requested).
  7. Else,
    1. Let match be LookupMatchingLocaleByBestFit(available, requested).
  8. If match is undefined, return undefined.
  9. Return match.[[locale]].

The "length" property of this method is 1𝔽.

Note 1
Each call validates the complete request list, even with no available locales. No match returns undefined; callers can apply their own fallback. This method does not call DefaultLocale or copy requested Unicode locale extensions into the result.
Note 2
Best fit uses the existing ECMA-402 operation, with no required CLDR/ICU data, scoring, expansion, penalty, or tie policy. Other extensions and private-use subtags retain that operation's treatment; no application-specific meaning is assigned.

1.3.3 Intl.LocaleMatcher.prototype [ %Symbol.toStringTag% ]

The initial value is "Intl.LocaleMatcher".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

1.4 Properties of Intl.LocaleMatcher Instances

Instances are ordinary objects with these internal slots:

  • [[InitializedLocaleMatcher]]: true.
  • [[AvailableLocales]]: the private Available Locales List copied during construction.
  • [[LocaleMatcher]]: "lookup" or "best fit".

Copyright & Software License

Software License

All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.