Intl.getCanonicalLocales(locales)normalizes locale tags. You pass one tag or a list of tags. It returns an array of canonical BCP 47 tags (for example "EN-us" becomes "en-US").
Duplicate tags that mean the same locale are reduced to one. If a tag is structurally invalid, the method throws a RangeError.
Remember
Intl.getCanonicalLocales(locales)
locales → a string, or an array of strings
returns an array of canonical BCP 47 tags
throws RangeError for structurally invalid tags
duplicates that match are removed
Syntax
Call it on the Intl object. Pass a locale string or an array of strings.
Valid tag."de-DE" is fine and comes back as itself in canonical form.
Invalid structure."not!!!" is not a BCP 47 tag, so the call throws.
Catch the name. Printing err.name keeps the output stable across engines.
Compatibility
Browser & Runtime Support
Intl.getCanonicalLocales() is part of the original ES2015Intl API (or arrived soon after and is now everywhere). Every current browser and Node.js has it.
✓ ES2015 · Widely supported
Intl.getCanonicalLocales()
Supported in Chrome 24+, Edge 12+, Firefox 29+, Safari 10+, Opera 15+ and Node.js 0.12+. Internet Explorer had partial Intl support only.
ES2015Standard since
Google Chrome24+ · Desktop & Mobile
Full support
Microsoft Edge12+ · Chromium based
Full support
Mozilla Firefox29+ · Desktop & Mobile
Full support
Apple Safari10+ · macOS & iOS
Full support
Opera15+ · Chromium based
Full support
Samsung InternetRecent versions · Android
Supported
Android WebView24+ · Chromium based
Supported
Node.js0.12+ · Server runtime
Supported
DenoSupported · JavaScript runtime
Supported
BunSupported · JavaScript runtime
Supported
Internet ExplorerNo native support
Not supported
Intl.getCanonicalLocales()Excellent
Bottom line: Safe to use in every current browser and in Node.js. No feature-detect needed for modern code.
Frequently Asked Questions
It takes one or more locale tags, normalizes them to canonical BCP 47 form, removes duplicates that mean the same thing, and returns an array of strings.
It throws a RangeError when a tag is structurally invalid, for example a string with illegal characters. It does not throw only because a locale has little data on the device.
No. It only normalizes the tag text. Use it to clean user input before you pass tags to formatters.
Yes. A single string is treated like a one-item list. The return value is still an array.
getCanonicalLocales() returns plain strings. Intl.Locale gives you an object with language, region, script and helper methods.