JavaScript Intl.getCanonicalLocales() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
Static method

Definition

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.

JavaScript
console.log(Intl.getCanonicalLocales("EN-us").join(", "));
console.log(Intl.getCanonicalLocales(["fr-FR", "JA-jp"]).join(", "));
CallWhat it does
Intl.getCanonicalLocales("EN-us")Normalize one tag. Result: ["en-US"].
Intl.getCanonicalLocales(["en-US", "en-us"])Duplicates collapse to one canonical tag.
Intl.getCanonicalLocales(["fr-FR", "ja-JP"])Several tags become a list of canonical forms.
Intl.getCanonicalLocales("not!!!")Throws a RangeError for a bad structure.

A standard JavaScript static method on the Intl object: call it as Intl.getCanonicalLocales(). No import required. Siblings: Intl.supportedValuesOf(), Intl.Collator(), Intl.DateTimeFormat(), Intl.DisplayNames(), Intl.DurationFormat(), Intl.ListFormat(), Intl.Locale(), Intl.NumberFormat(), Intl.PluralRules(), Intl.RelativeTimeFormat(), Intl.Segmenter().

Library declarations
JavaScript
// ECMAScript 2015 (ES6) — Intl
Intl.getCanonicalLocales(locales)

// locales : string | string[]
// returns : string[]  (canonical BCP 47 tags)
// throws  : RangeError if a tag is structurally invalid

Parameters

ParameterDescription
localesRequired. A locale string, or an array of locale strings, such as "en-US" or ["de-DE", "fr-FR"].

Return Value

Return ValueDescription
string[]An array of canonical BCP 47 locale tags.
RangeError (thrown)At least one tag is not a valid locale structure.

JavaScript Examples

Example 1 — Normalize a List of Locale Tags

Pass several tags with mixed case. The method returns the canonical forms.

JavaScript
const tags = ["EN-us", "fr-FR", "JA-jp"];
const clean = Intl.getCanonicalLocales(tags);

console.log("Canonical: " + clean.join(", "));
console.log("Count: " + clean.length);
Try It Yourself

How It Works

  1. Mixed case is fine. "EN-us" and "JA-jp" are rewritten to the usual language-region form.
  2. Order is kept. The three tags stay in the same order in the result array.
  3. Ready to use. You can pass these strings to other Intl constructors such as Intl.NumberFormat.

Example 2 — Duplicates and Different Case Collapse

The same locale written twice, or with different case, becomes one canonical tag.

JavaScript
const tags = ["en-US", "en-us", "EN-US"];
const clean = Intl.getCanonicalLocales(tags);

console.log("Result: " + clean.join(", "));
console.log("Length: " + clean.length);
Try It Yourself

How It Works

  1. Same meaning. All three strings name the same locale.
  2. One answer. The method keeps a single canonical "en-US".
  3. Handy for forms. Users may type tags in any case; you still get one clean value.

Example 3 — Catch an Invalid Locale Tag

A tag that is not structurally valid throws a RangeError. Catch it and print the error name.

JavaScript
console.log("Good: " + Intl.getCanonicalLocales("de-DE").join(", "));

try {
  Intl.getCanonicalLocales("not!!!");
} catch (err) {
  console.log("Bad tag: " + err.name);
}
Try It Yourself

How It Works

  1. Valid tag. "de-DE" is fine and comes back as itself in canonical form.
  2. Invalid structure. "not!!!" is not a BCP 47 tag, so the call throws.
  3. Catch the name. Printing err.name keeps the output stable across engines.

Browser & Runtime Support

Intl.getCanonicalLocales() is part of the original ES2015 Intl 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.

ES2015 Standard since
Google Chrome 24+ · Desktop & Mobile
Full support
Microsoft Edge 12+ · Chromium based
Full support
Mozilla Firefox 29+ · Desktop & Mobile
Full support
Apple Safari 10+ · macOS & iOS
Full support
Opera 15+ · Chromium based
Full support
Samsung Internet Recent versions · Android
Supported
Android WebView 24+ · Chromium based
Supported
Node.js 0.12+ · Server runtime
Supported
Deno Supported · JavaScript runtime
Supported
Bun Supported · JavaScript runtime
Supported
Internet Explorer No 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.

Next: Intl.supportedValuesOf()

Learn how to list the calendars, currencies, time zones and other values your engine supports.

Intl.supportedValuesOf() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

12 people found this page helpful