{"id":18137842,"url":"https://github.com/tc39/proposal-intl-localematcher","last_synced_at":"2025-04-19T17:45:21.508Z","repository":{"id":53015571,"uuid":"313485452","full_name":"tc39/proposal-intl-localematcher","owner":"tc39","description":"Proposal for Intl.LocaleMatcher","archived":false,"fork":false,"pushed_at":"2021-04-09T09:08:50.000Z","size":58,"stargazers_count":36,"open_issues_count":5,"forks_count":4,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-04-18T10:26:49.615Z","etag":null,"topics":["ecma402","intl","proposal"],"latest_commit_sha":null,"homepage":"https://longlho.github.io/proposal-intl-localematcher/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tc39.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-11-17T02:32:08.000Z","updated_at":"2024-12-20T07:11:04.000Z","dependencies_parsed_at":"2022-09-08T08:23:43.989Z","dependency_job_id":null,"html_url":"https://github.com/tc39/proposal-intl-localematcher","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tc39%2Fproposal-intl-localematcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tc39%2Fproposal-intl-localematcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tc39%2Fproposal-intl-localematcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tc39%2Fproposal-intl-localematcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tc39","download_url":"https://codeload.github.com/tc39/proposal-intl-localematcher/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249751965,"owners_count":21320404,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ecma402","intl","proposal"],"created_at":"2024-11-01T15:07:10.224Z","updated_at":"2025-04-19T17:45:21.489Z","avatar_url":"https://github.com/tc39.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `Intl.LocaleMatcher`\n\n## Motivation\n\ni18n-supported websites often get a list of preferred locales via `Accept-Language` header or `navigator.languages`. They then try to determine the best available locale based on the set of locales that they support (and have translations for).\n\nThis operation currently exists within ECMA-402 but is only available as an abstract operation. Surfacing this functionality as a top level API would improve locale negotiation correctness and developer productivity as sites will be able to reliably handle not only matching, but also aliases, fallbacks and such.\n\n### Use cases\n\n1. Given a set of locales an application has translations for and the set of locales a user requests, [find the best matching locales](https://github.com/vercel/next.js/issues/18676).\n2. JS runtimes (\u0026 polyfills) are not required to guarantee supporting all locales. Given a set of locales it supports and what the user requests, [find the best matching locales](https://github.com/formatjs/formatjs/discussions/2669). \n3. An application can also provide [different \"tones\"](https://github.com/formatjs/formatjs/discussions/2642) of the same locales (e.g casual, formal), utilizing `-x-` private tag. Given a set of locales with extensions and what the user preference might be, find the best matching locales.\n\n## Status\n\n**Stage 1**\n\nPonyfill: https://formatjs.io/docs/polyfills/intl-localematcher\n\n## Champion\n\n- [Long Ho (@longlho)](https://github.com/longlho)\n\n## API\n\n```ts\ninterface Options {\n    algorithm: 'lookup' | 'best fit'\n}\n\nIntl.LocaleMatcher.match(\n    requestedLocales: string[],\n    availableLocales: string[],\n    defaultLocale: string,\n    options?: Options\n): string\n```\n\n### Options\n\n1. `lookup` would continue to be the existing `LookupMatcher` implementation within ECMA-402.\n1. `best fit` would be implementation-dependent.\n\n## Examples\n\n```ts\nIntl.LocaleMatcher.match([\"fr-XX\", \"en\"], [\"fr\", \"en\"], \"en\"); // 'fr'\n```\n\n## Prior Arts\n\n### [@hapi/accept](https://github.com/hapijs/accept)\n\nThis is the core of hapijs header parsing with quality preferences. This however does a naive hierarchy with exact matches only. For example:\n\n```js\nAccept.language(\"en;q=0.7, fr-XX;q=0.8\", [\"fr\", \"en\"]); // language === \"en\"\n```\n\nwhich would not be accurate.\n\n### [koa](https://koajs.com/#request)\n\nSimilarly, Koa's `request.acceptsLanguages` follow similar exact match algorithm.\n\n### [UTS35 LanguageMatching](https://www.unicode.org/reports/tr35/tr35.html#LanguageMatching)\n\nThis details a more sophisticated locale negotiation algorithm that is more accurate than `hapi`/`koa`\n\n### [RFC4647 Section 3.4](https://tools.ietf.org/html/rfc4647#section-3.4)\n\nThis is the `lookup` algorithm in ECMA-402.\n\n### [cldrjs's lookup implementation](https://github.com/rxaviers/cldrjs/blob/master/doc/bundle_lookup_matcher.md#implementation-details)\n\nSimilar to UTS35 LanguageMatching.\n\n## References\n\n- https://github.com/tc39/ecma402/issues/513\n- https://github.com/tc39/ecma402/issues/46\n- https://github.com/vercel/next.js/issues/18676\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftc39%2Fproposal-intl-localematcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftc39%2Fproposal-intl-localematcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftc39%2Fproposal-intl-localematcher/lists"}