Intl.Locale() constructor
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2020.
The Intl.Locale()
constructor creates Intl.Locale
objects.
Try it
Syntax
Parameters
tag
-
The Unicode locale identifier string. For the syntax of locale identifier strings, see the Intl main page. Note that the
Intl.Locale
constructor, unlike most otherIntl
constructors, does not accept an array of locales orundefined
. options
-
An object that contains configuration for the Locale. Option values here take priority over extension keys in the locale identifier. Possible properties are:
language
-
The language. Any syntactically valid string following the
unicode_language_subtag
grammar (2–3 or 5–8 letters) is accepted, but the implementation only recognizes certain kinds. script
-
The script. Any syntactically valid string following the
unicode_script_subtag
grammar (4 letters) is accepted, but the implementation only recognizes certain kinds. region
-
The region. Any syntactically valid string following the
unicode_region_subtag
grammar (either 2 letters or 3 digits) is accepted, but the implementation only recognizes certain kinds. calendar
-
The calendar. Any syntactically valid string following the
type
grammar (one or more segments of 3–8 alphanumerals, joined by hyphens) is accepted, but the implementation only recognizes certain kinds, which are listed inIntl.Locale.prototype.getCalendars
. collation
-
The collation. Any syntactically valid string following the
type
grammar is accepted, but the implementation only recognizes certain kinds, which are listed inIntl.Locale.prototype.getCollations
. numberingSystem
-
The numbering system. Any syntactically valid string following the
type
grammar is accepted, but the implementation only recognizes certain kinds, which are listed inIntl.Locale.prototype.getNumberingSystems
. caseFirst
-
The case-first sort option. Possible values are
"upper"
,"lower"
, or"false"
. hourCycle
-
The hour cycle. Possible values are
"h23"
,"h12"
,"h11"
, or the practically unused"h24"
, which are explained inIntl.Locale.prototype.getHourCycles
numeric
-
The numeric sort option. A boolean.
Examples
Basic usage
At its very simplest, the Intl.Locale()
constructor takes
a locale identifier string as its argument:
const us = new Intl.Locale("en-US");
Using the Locale constructor with an options object
The constructor also takes an optional configuration object argument, which can contain
any of several extension types. For example, set the
hourCycle
property of the configuration object to your desired hour cycle type, and then pass it
into the constructor:
const locale = new Intl.Locale("en-US", { hourCycle: "h12" });
console.log(locale.hourCycle); // "h12"
Specifications
Specification |
---|
ECMAScript Internationalization API Specification # sec-intl-locale-constructor |
Browser compatibility
BCD tables only load in the browser
See also
- Polyfill of
Intl.Locale
in FormatJS Intl.Collator
- Canonical Unicode Locale Identifiers in the Unicode locale data markup language spec