You’re reading the English version of this content since no translation exists yet for this locale. Help us translate this article!
The Intl
object is the namespace for the ECMAScript Internationalization API, which provides language sensitive string comparison, number formatting, and date and time formatting. The Intl
object provides access to several constructors as well as functionality common to the internationalization constructors and other language sensitive functions.
Properties
Intl.Collator
- Constructor for collators, which are objects that enable language-sensitive string comparison.
Intl.DateTimeFormat
- Constructor for objects that enable language-sensitive date and time formatting.
Intl.ListFormat
- Constructor for objects that enable language-sensitive list formatting.
Intl.Locale
- Constructor for objects that represents a Unicode locale identifier.
Intl.NumberFormat
- Constructor for objects that enable language-sensitive number formatting.
Intl.PluralRules
- Constructor for objects that enable plural-sensitive formatting and language-specific rules for plurals.
Intl.RelativeTimeFormat
- Constructor for objects that enable language-sensitive relative time formatting.
Methods
Intl.getCanonicalLocales()
- Returns canonical locale names.
Locale identification and negotiation
The internationalization constructors as well as several language sensitive methods of other constructors (listed under See also) use a common pattern for identifying locales and determining the one they will actually use: they all accept locales
and options
arguments, and negotiate the requested locale(s) against the locales they support using an algorithm specified in the options.localeMatcher
property.
locales argument
The locales
argument must be either a string holding a BCP 47 language tag, or an array of such language tags. If the locales
argument is not provided or is undefined, the runtime's default locale is used.
A BCP 47 language tag defines a language and minimally contains a primary language code. In its most common form it can contain, in order: a language code, a script code, and a country or region code, all separated by hyphens. While the tag is not case sensitive, it is recommended to use title case for script code, upper case for country and region codes and lower case for everything else.
Examples:
"hi"
: Hindi (primary language)."de-AT"
: German as used in Austria (primary language with country code)."zh-Hans-CN"
: Chinese written in simplified characters as used in China (primary language with script and country codes).
The subtags identifying languages, scripts, countries (regions), and (rarely used) variants in BCP 47 language tags can be found in the IANA Language Subtag Registry.
BCP 47 also allows for extensions. JavaScript internationalization functions use the "u"
(Unicode) extension, which can be used to request additional customization of Collator
, NumberFormat
, or DateTimeFormat
objects. Examples:
"de-DE-u-co-phonebk"
: Use the phonebook variant of the German sort order, which expands umlauted vowels to character pairs: ä → ae, ö → oe, ü → ue."th-TH-u-nu-thai"
: Use Thai digits (๐, ๑, ๒, ๓, ๔, ๕, ๖, ๗, ๘, ๙) in number formatting."ja-JP-u-ca-japanese"
: Use the Japanese calendar in date and time formatting, so that 2013 is expressed as the year 25 of the Heisei period, or 平成25."en-GB-u-ca-islamic"
: use British English with the Islamic (Hijri) calendar, where the Gregorian date 14 October, 2017 is the Hijri date 24 Muharram, 1439.
Locale negotiation
The locales
argument, after stripping off all Unicode extensions, is interpreted as a prioritized request from the application. The runtime compares it against the locales it has available and picks the best one available. Two matching algorithms exist: the "lookup"
matcher follows the Lookup algorithm specified in BCP 47; the "best fit"
matcher lets the runtime provide a locale that's at least, but possibly more, suited for the request than the result of the Lookup algorithm. If the application doesn't provide a locales
argument, or the runtime doesn't have a locale that matches the request, then the runtime's default locale is used. The matcher can be selected using a property of the options
argument (see below).
If the selected language tag had a Unicode extension substring, that extension is now used to customize the constructed object or the behavior of the function. Each constructor or function supports only a subset of the keys defined for the Unicode extension, and the supported values often depend on the language tag. For example, the "co"
key (collation) is only supported by Collator
, and its "phonebk"
value is only supported for German.
options argument
The options
argument must be an object with properties that vary between constructors and functions. If the options
argument is not provided or is undefined, default values are used for all properties.
One property is supported by all language sensitive constructors and functions: The localeMatcher
property, whose value must be a string "lookup"
or "best fit"
and which selects one of the locale matching algorithms described above.
Specifications
Specification | Status | Comment |
---|---|---|
ECMAScript Internationalization API 1.0 (ECMA-402) The definition of 'Intl' in that specification. |
Standard | Initial definition. |
ECMAScript Internationalization API 2.0 (ECMA-402) The definition of 'Intl' in that specification. |
Standard | |
ECMAScript Internationalization API 4.0 (ECMA-402) The definition of 'Intl' in that specification. |
Draft | Added Intl.getCanonicalLocales in the 4th edition. |
Browser compatibility
Desktop | Mobile | Server | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Intl | Chrome Full support 24 | Edge Full support 12 | Firefox Full support 29 | IE Full support 11 | Opera Full support 15 | Safari Full support 10 | WebView Android Full support 4.4 | Chrome Android Full support 25 | Firefox Android Full support 56 | Opera Android Full support Yes | Safari iOS Full support 10 | Samsung Internet Android Full support 1.5 | nodejs Full support Yes |
Collator | Chrome Full support 24 | Edge Full support 12 | Firefox Full support 29 | IE Full support 11 | Opera Full support 15 | Safari Full support 10 | WebView Android Full support ≤37 | Chrome Android Full support 25 | Firefox Android Full support 56 | Opera Android Full support Yes | Safari iOS Full support 10 | Samsung Internet Android Full support 1.5 | nodejs ? |
DateTimeFormat | Chrome Full support 24 | Edge Full support 12 | Firefox Full support 29 | IE Full support 11 | Opera Full support 15 | Safari Full support 10 | WebView Android Full support 4.4 | Chrome Android Full support 26 | Firefox Android Full support 56 | Opera Android Full support 14 | Safari iOS Full support 10 | Samsung Internet Android Full support 1.5 | nodejs Full support Yes |
ListFormat | Chrome Full support 72 | Edge No support No | Firefox No support No | IE No support No | Opera Full support 60 | Safari No support No | WebView Android Full support 72 | Chrome Android Full support 72 | Firefox Android No support No | Opera Android ? | Safari iOS No support No | Samsung Internet Android No support No | nodejs No support No |
Locale | Chrome Full support 74 | Edge No support No | Firefox No support No | IE No support No | Opera No support No | Safari No support No | WebView Android Full support 74 | Chrome Android Full support 74 | Firefox Android No support No | Opera Android No support No | Safari iOS No support No | Samsung Internet Android No support No | nodejs No support No |
NumberFormat | Chrome Full support 24 | Edge Full support 12 | Firefox Full support 29 | IE Full support 11 | Opera Full support 15 | Safari Full support 10 | WebView Android Full support Yes | Chrome Android Full support 26 | Firefox Android Full support 56 | Opera Android Full support 14 | Safari iOS Full support 10 | Samsung Internet Android Full support 1.5 | nodejs ? |
PluralRules | Chrome Full support 63 | Edge Full support 18 | Firefox Full support 58 | IE No support No | Opera Full support 50 | Safari No support No | WebView Android Full support 63 | Chrome Android Full support 63 | Firefox Android Full support 58 | Opera Android Full support 46 | Safari iOS No support No | Samsung Internet Android Full support 8.0 | nodejs Full support 10.0.0 |
RelativeTimeFormat | Chrome Full support 71 | Edge No support No | Firefox Full support 65 | IE No support No | Opera Full support 58 | Safari No support No | WebView Android Full support 71 | Chrome Android Full support 71 | Firefox Android Full support 65 | Opera Android Full support 50 | Safari iOS No support No | Samsung Internet Android Full support 10.0 | nodejs Full support 12.0.0 |
getCanonicalLocales | Chrome Full support 54 | Edge Full support 16 | Firefox Full support 48 | IE No support No | Opera No support No | Safari Full support 11 | WebView Android No support No | Chrome Android No support No | Firefox Android Full support 56 | Opera Android No support No | Safari iOS Full support 11 | Samsung Internet Android No support No | nodejs No support No |
Legend
- Full support
- Full support
- No support
- No support
- Compatibility unknown
- Compatibility unknown
- Experimental. Expect behavior to change in the future.
- Experimental. Expect behavior to change in the future.
See also
- Introduction: The ECMAScript Internationalization API
- Constructors
- Methods