Intl

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.

Constructor 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.DisplayNames()
Constructor for objects that enable the consistent translation of language, region and script display names.
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.

Static 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 requests that a particular locale (or a locale from a list of them) be considered for use in a given operation.  A single locale may be specified by either an Intl.Locale object or a string that is a Unicode BCP 47 locale identifier.  Multiple locales may be specified (and a best-supported locale determined by evaluating each of them in order and comparing against the locales supported by the implementation) by passing an array (or array-like object, with a length property and corresponding indexed elements) whose elements are either Intl.Locale objects or values that convert to Unicode BCP 47 locale identifier strings.  If the locales argument is not provided or is undefined, the runtime's default locale is used.

A Unicode BCP 47 locale identifier consists of

  1. a language code,
  2. (optionally) a script code,
  3. (optionally) a region (or country) code,
  4. (optionally) one or more variant codes, and
  5. (optionally) one or more extension sequences,

with all present components separated by hyphens.  Locale identifiers are case-insensitive ASCII.  However, it's conventional to use title case (first letter capitalized, successive letters lower case) for script code, upper case for region codes, and lower case for everything else.  For example:

  • "hi": Hindi (language)
  • "de-AT": German (language) as used in Austria (region)
  • "zh-Hans-CN": Chinese (language) written in simplified characters (script) as used in China (region)
  • "en-emodeng": English (language) in the "Early modern English" dialect (variant)

The subtags identifying languages, scripts, regions (including countries), and (rarely used) variants in Unicode BCP 47 locale identifiers are registered in the IANA Language Subtag Registry.  This registry is periodically updated over time, and implementations may not always be up to date, so be careful not to rely too much on tags being universally supported.

BCP 47 also allows for extensions, each consisting of a single digit or letter (other than "x") and one or more two- to eight-letter or digit tags, all separated by hyphens. 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 interprets umlauted vowels as corresponding 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.

Other BCP 47 extension tags can be found in the Unicode CLDR Project.

Finally, an extension using the letter "x" may appear, followed by one or one- to eight-letter or digit tags.  This extension allows applications to encode information for their own private use, that will be ignored by all Intl operations.

Locale negotiation

The list of locales specified by the locales argument, after Unicode extensions have been removed from them, 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
ECMAScript Internationalization API (ECMA-402)
The definition of 'Intl' in that specification.

Browser compatibility

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung InternetNode.js
IntlChrome Full support 24Edge Full support 12Firefox Full support 29IE Full support 11Opera Full support 15Safari Full support 10WebView Android Full support 4.4Chrome Android Full support 25Firefox Android Full support 56Opera Android Full support 14Safari iOS Full support 10Samsung Internet Android Full support 1.5nodejs Full support Yes
CollatorChrome Full support 24Edge Full support 12Firefox Full support 29IE Full support 11Opera Full support 15Safari Full support 10WebView Android Full support ≤37Chrome Android Full support 25Firefox Android Full support 56Opera Android Full support 14Safari iOS Full support 10Samsung Internet Android Full support 1.5nodejs ?
DateTimeFormatChrome Full support 24Edge Full support 12Firefox Full support 29IE Full support 11Opera Full support 15Safari Full support 10WebView Android Full support 4.4Chrome Android Full support 25Firefox Android Full support 56Opera Android Full support 14Safari iOS Full support 10Samsung Internet Android Full support 1.5nodejs Full support Yes
getCanonicalLocalesChrome Full support 54Edge Full support 16Firefox Full support 48IE No support NoOpera No support NoSafari Full support 11WebView Android No support NoChrome Android No support NoFirefox Android Full support 56Opera Android No support NoSafari iOS Full support 11Samsung Internet Android No support Nonodejs No support No
ListFormat
Experimental
Chrome Full support 72Edge No support NoFirefox No support NoIE No support NoOpera Full support 60Safari No support NoWebView Android Full support 72Chrome Android Full support 72Firefox Android No support NoOpera Android Full support 51Safari iOS No support NoSamsung Internet Android No support Nonodejs No support No
LocaleChrome Full support 74Edge Full support 79Firefox Full support 75IE No support NoOpera Full support 62Safari No support NoWebView Android Full support 74Chrome Android Full support 74Firefox Android No support NoOpera Android Full support 53Safari iOS No support NoSamsung Internet Android Full support 11.0nodejs No support No
NumberFormatChrome Full support 24Edge Full support 12Firefox Full support 29IE Full support 11Opera Full support 15Safari Full support 10WebView Android Full support ≤37Chrome Android Full support 26Firefox Android Full support 56Opera Android Full support 14Safari iOS Full support 10Samsung Internet Android Full support 1.5nodejs Full support Yes
PluralRulesChrome Full support 63Edge Full support 18Firefox Full support 58IE No support NoOpera Full support 50Safari No support NoWebView Android Full support 63Chrome Android Full support 63Firefox Android Full support 58Opera Android Full support 46Safari iOS No support NoSamsung Internet Android Full support 8.0nodejs Full support 10.0.0
RelativeTimeFormatChrome Full support 71Edge Full support 79Firefox Full support 65IE No support NoOpera Full support 58Safari No support NoWebView Android Full support 71Chrome Android Full support 71Firefox Android Full support 65Opera Android Full support 50Safari iOS No support NoSamsung Internet Android Full support 10.0nodejs Full support 12.0.0

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