For AI agents: the complete documentation index is available at /tc39-atlas/en/llms.txt, the full documentation bundle is available at /tc39-atlas/en/llms-full.txt, and this page is available as Markdown at /tc39-atlas/en/proposals/proposal-intl-localematcher.md.
TC39 Atlas
  • English

      • Intl LocaleMatcher ?

      Proposal details
      Proposal overview

      The proposal adds Intl.LocaleMatcher to prepare available translation locales once and match user preferences. The constructor snapshots and canonicalizes available locales, reads options once, and exposes a match method that returns a canonical available tag or undefined. Matching can use RFC 4647 prefix lookup or the default best fit behavior based on ECMA-402's implementation-defined matching, without requiring CLDR/ICU data or scores.

      Note

      The README below comes from the upstream repository and may contain outdated stage or status metadata. Use the proposal details above as the current source of truth.

      Intl.LocaleMatcher

      Prepare available translation locales once, then match user preferences.

      Stage 1. Champion: Long Ho.

      Specification · Source · Research and open issues · FormatJS ponyfill

      Proposed API

      const available = ['fr', 'en'];
const matcher = new Intl.LocaleMatcher(available, {algorithm: 'lookup'});

matcher.match(['fr-CA', 'en']); // 'fr'
matcher.match(['ja']);         // undefined
const locale = matcher.match(navigator.languages) ?? 'en';
      • Constructor snapshots and canonicalizes available locales; later mutations don't affect it. Options are read once and require an object or undefined.
      • lookup uses RFC 4647 prefix lookup. best fit (default) reuses ECMA-402's implementation-defined matching, without requiring CLDR/ICU data or scores.
      • match returns one canonical available tag or undefined. No implicit default or requested Unicode u extensions are added to the result.
      • Inputs follow CanonicalizeLocaleList: strings, Intl.Locale objects, and array-like lists. Generic iterables are not consumed. Available u extensions remain rejected; private-use tone matching remains unspecified.

      Draft API change: instance method replaces static Intl.LocaleMatcher.match. The FormatJS ponyfill currently implements the older stateless API.

      HTTP parsing, message fallback, multiple results, and resource indices stay outside this draft. Open decisions and foundational precedents are in design notes.

      Build

      npm ci
npm run build

      Strict ecmarkup build checks syntax, references, and algorithm lint rules. Runtime conformance tests are planned, not implemented here.

      References