This specification is developed on GitHub with the help of the ECMAScript community. There are a number of ways to contribute to the development of this specification:
Refer to the
This specification's source can be found at https://github.com/tc39/ecma402.
The ECMAScript 2020 Internationalization API Specification (ECMA-402 7th Edition), provides key language sensitive functionality as a complement to the ECMAScript 2020 Language Specification (ECMA-262 11th Edition or successor). Its functionality has been selected from that of well-established internationalization APIs such as those of the Internationalization Components for Unicode (ICU) library, of the .NET framework, or of the Java platform.
The 1st Edition API was developed by an ad-hoc group established by Ecma TC39 in September 2010 based on a proposal by Nebojša Ćirić and Jungshik Shin.
The 2nd Edition API was adopted by the General Assembly of June 2015, as a complement to the ECMAScript 6th Edition.
The 3rd Edition API was the first edition released under Ecma TC39's new yearly release cadence and open development process. A plain-text source document was built from the ECMA-402 source document to serve as the base for further development entirely on GitHub. Over the year of this standard's development, dozens of pull requests and issues were filed representing several of bug fixes, editorial fixes and other improvements. Additionally, numerous software tools were developed to aid in this effort including Ecmarkup, Ecmarkdown, and Grammarkdown.
Dozens of individuals representing many organizations have made very significant contributions within Ecma TC39 to the development of this edition and to the prior editions. In addition, a vibrant community has emerged supporting TC39's ECMAScript efforts. This community has reviewed numerous drafts, filed dozens of bug reports, performed implementation experiments, contributed test suites, and educated the world-wide developer community about ECMAScript Internationalization. Unfortunately, it is impossible to identify and acknowledge every person and organization who has contributed to this effort.
Norbert Lindenberg
ECMA-402, 1st Edition Project Editor
Rick Waldron
ECMA-402, 2nd Edition Project Editor
Caridy Patiño
ECMA-402, 3rd, 4th and 5th Editions Project Editor
Caridy Patiño, Daniel Ehrenberg, Leo Balter
ECMA-402, 6th Edition Project Editors
Leo Balter, Valerie Young, Isaac Durazo
ECMA-402, 7th Edition Project Editors
This Standard defines the application programming interface for ECMAScript objects that support programs that need to adapt to the linguistic and cultural conventions used by different human languages and countries.
A conforming implementation of the ECMAScript 2020 Internationalization API Specification must conform to the ECMAScript 2020 Language Specification (ECMA-262 11th Edition, or successor), and must provide and support all the objects, properties, functions, and program semantics described in this specification.
A conforming implementation of the ECMAScript 2020 Internationalization API Specification is permitted to provide additional objects, properties, and functions beyond those described in this specification. In particular, a conforming implementation of the ECMAScript 2020 Internationalization API Specification is permitted to provide properties not described in this specification, and values for those properties, for objects that are described in this specification. A conforming implementation is not permitted to add optional arguments to the functions defined in this specification.
A conforming implementation is permitted to accept additional
values, and then have implementation-defined behaviour instead of
throwing a
supportedLocalesOf
methods.The following referenced documents are required for the application of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.
ECMAScript 2020 Language Specification (ECMA-262 11th Edition, or successor).
https://www.ecma-international.org/publications/standards/Ecma-262.htm
This section contains a non-normative overview of the ECMAScript 2020 Internationalization API Specification.
Internationalization of software means designing it such that it supports or can be easily adapted to support the needs of users speaking different languages and having different cultural expectations, and enables worldwide communication between them. Localization then is the actual adaptation to a specific language and culture. Globalization of software is commonly understood to be the combination of internationalization and localization. Globalization starts at the lowest level by using a text representation that supports all languages in the world, and using standard identifiers to identify languages, countries, time zones, and other relevant parameters. It continues with using a user interface language and data presentation that the user understands, and finally often requires product-specific adaptations to the user's language, culture, and environment.
The ECMAScript 2020 Language Specification lays the foundation by using Unicode for text representation and by providing a few language-sensitive functions, but gives applications little control over the behaviour of these functions. The ECMAScript 2020 Internationalization API Specification builds on this by providing a set of customizable language-sensitive functionality. The API is useful even for applications that themselves are not internationalized, as even applications targeting only one language and one region need to properly support that one language and region. However, the API also enables applications that support multiple languages and regions, even concurrently, as may be needed in server environments.
The ECMAScript 2020 Internationalization API Specification is designed to complement the ECMAScript 2020 Language Specification by providing key language-sensitive functionality. The API can be added to an implementation of the ECMAScript 2020 Language Specification (ECMA-262 11th Edition, or successor).
The ECMAScript 2020 Internationalization API Specification provides several key pieces of language-sensitive functionality that are required in most applications: String comparison (collation), number formatting, date and time formatting, pluralization rules, and case conversion. While the ECMAScript 2020 Language Specification provides functions for this basic functionality (on Array.prototype: toLocaleString; on String.prototype: localeCompare, toLocaleLowerCase, toLocaleUpperCase; on Number.prototype: toLocaleString; on Date.prototype: toLocaleString, toLocaleDateString, and toLocaleTimeString), it leaves the actual behaviour of these functions largely up to implementations to define. The ECMAScript 2020 Internationalization API Specification provides additional functionality, control over the language and over details of the behaviour to be used, and a more complete specification of required functionality.
Applications can use the API in two ways:
The Intl object is used to package all functionality defined in the ECMAScript 2020 Internationalization API Specification to avoid name collisions.
Due to the nature of internationalization, the API specification has to leave several details implementation dependent:
ECMA 402 describes the schema of the data used by its functions. The data contained inside is implementation-dependent, and expected to change over time and vary between implementations. The variation is visible by programmers, and it is possible to construct programs which will depend on a particular output. However, this specification attempts to describe reasonable constraints which will allow well-written programs to function across implementations. Implementations are encouraged to continue their efforts to harmonize linguistic data.
This standard uses a subset of the notational conventions of the ECMAScript 2020 Language Specification (ECMA-262 11th Edition), as ES2020:
As an extension to the
This specification uses blocks demarcated as Normative Optional to denote the sense of Annex B in ECMA 262. That is, normative optional sections are required when the ECMAScript host is a web browser. The content of the section is normative but optional if the ECMAScript host is not a web browser.
The following table extends the Well-Known Intrinsic Objects table defined in ES2020,
Intrinsic Name | Global Name | ECMAScript Language Association |
---|---|---|
Intl.Collator |
The Intl.Collator |
|
Intl.Collator.prototype |
The initial value of the |
|
%Date_now% | Date.now |
The initial value of the |
Intl.DateTimeFormat |
The Intl.DateTimeFormat |
|
Intl.DateTimeFormat.prototype |
The initial value of the |
|
Intl |
The Intl object ( |
|
Intl.Locale |
The Intl.Locale |
|
Intl.Locale.prototype |
The initial value of the prototype |
|
Intl.NumberFormat |
The Intl.NumberFormat |
|
Intl.NumberFormat.prototype |
The initial value of the |
|
Intl.PluralRules |
The Intl.PluralRules |
|
Intl.PluralRules.prototype |
The initial value of the |
|
Intl.RelativeTimeFormat |
The Intl.RelativeTimeFormat |
|
Intl.RelativeTimeFormat.prototype |
The initial value of the prototype |
|
%StringProto_indexOf% | String.prototype.indexOf |
The initial value of the |
This clause describes the String values used in the ECMAScript 2020 Internationalization API Specification to identify locales, currencies, time zones, and measurement units.
The String values used to identify locales, currencies, and time
zones are interpreted in a case-insensitive manner, treating the Unicode
Basic Latin characters
EXAMPLES
The ECMAScript 2020 Internationalization API Specification identifies locales using Unicode BCP 47 locale identifiers as defined by Unicode Technical Standard #35 LDML § 3 Unicode Language and Locale Identifiers, which may include extensions such as the Unicode BCP 47 U Extension. Their canonical form is specified in Unicode Technical Standard #35 LDML § 3.2.1 Canonical Unicode Locale Identifiers.
Unicode BCP 47 locale identifiers are structurally valid when they match those syntactical formatting criteria of Unicode Technical Standard 35, section 3.2, but it is not required to validate them according to the Unicode validation data. All structurally valid language tags are valid for use with the APIs defined by this standard. However, the set of locales and thus language tags that an implementation supports with adequate localizations is implementation dependent. The constructors Collator, NumberFormat, DateTimeFormat, and PluralRules map the language tags used in requests to locales supported by their respective implementations.
This standard uses the term "Unicode locale extension sequence" - as described in unicode_locale_extensions
in UTS 35 Unicode Locale Identifier, section 3.2 - for any substring of
a language tag that is not part of a private use subtag sequence,
starts with a separator
The IsStructurallyValidLanguageTag abstract operation verifies that the locale argument (which must be a String value)
The abstract operation returns true if locale can be generated from the EBNF grammar in section 3.2 of the Unicode Technical Standard 35, starting with unicode_locale_id
,
and does not contain duplicate variant or singleton subtags (other than
as a private use subtag). It returns false otherwise. Terminal value
characters in the grammar are interpreted as the Unicode equivalents of
the ASCII octet values given.
The CanonicalizeUnicodeLocaleId abstract operation returns the canonical and case-regularized form of the locale argument (which must be a String value that is a structurally valid Unicode BCP 47 locale identifier as verified by the
The DefaultLocale abstract operation returns a String value representing the structurally valid (
The ECMAScript 2020 Internationalization API Specification identifies currencies using 3-letter currency codes as defined by ISO 4217. Their canonical form is upper case.
All well-formed 3-letter ISO 4217 currency codes are allowed. However, the set of combinations of currency code and language tag for which localized currency symbols are available is implementation dependent. Where a localized currency symbol is not available, the ISO 4217 currency code is used for formatting.
The IsWellFormedCurrencyCode abstract operation verifies that the currency argument (which must be a String value) represents a well-formed 3-letter ISO currency code. The following steps are taken:
The ECMAScript 2020 Internationalization API Specification identifies time zones using the Zone and Link names of the IANA Time Zone Database. Their canonical form is the corresponding Zone name in the casing used in the IANA Time Zone Database.
All registered Zone and Link names are allowed. Implementations must recognize all such names, and use best available current and historical information about their offsets from UTC and their daylight saving time rules in calculations. However, the set of combinations of time zone name and language tag for which localized time zone names are available is implementation dependent.
The IsValidTimeZoneName abstract operation verifies that the timeZone argument (which must be a String value) represents a valid Zone or Link name of the IANA Time Zone Database.
The abstract operation returns true if timeZone, converted to upper case as described in
The CanonicalizeTimeZoneName abstract operation returns the canonical and case-regularized form of the timeZone argument (which must be a String value that is a valid time zone name as verified by the
The Intl.DateTimeFormat
The DefaultTimeZone abstract operation returns a String value representing the valid (
The ECMAScript 2020 Internationalization API Specification identifies measurement units using a core unit identifier as defined by Unicode Technical Standard #35, Part 2, Section 6. Their canonical form is a string containing all lowercase letters with zero or more hyphens.
Only a limited set of core unit identifiers are allowed. An illegal core unit identifier results in a RangeError.
The IsWellFormedUnitIdentifier abstract operation verifies that the unitIdentifier argument (which must be a String value) represents a well-formed core unit identifier as defined in UTS #35, Part 2, Section 6. In addition to obeying the UTS #35 core unit identifier syntax, unitIdentifier must be one of the identifiers sanctioned by UTS #35 or be a compound unit composed of two sanctioned simple units. The following steps are taken:
The IsSanctionedSimpleUnitIdentifier abstract operation verifies that the given core unit identifier is among the simple units sanctioned in the current version of the ECMAScript Internationalization API Specification, a subset of the Validity Data as described in UTS #35, Part 1, Section 3.11; the list may grow over time. As discussed in UTS #35, a simple unit is one that does not have a numerator and denominator. The following steps are taken:
Simple Unit |
---|
acre |
bit |
byte |
celsius |
centimeter |
day |
degree |
fahrenheit |
fluid-ounce |
foot |
gallon |
gigabit |
gigabyte |
gram |
hectare |
hour |
inch |
kilobit |
kilobyte |
kilogram |
kilometer |
liter |
megabit |
megabyte |
meter |
mile |
mile-scandinavian |
milliliter |
millimeter |
millisecond |
minute |
month |
ounce |
percent |
petabyte |
pound |
second |
stone |
terabit |
terabyte |
week |
yard |
year |
Unless specified otherwise in this document, the objects, functions,
and constructors described in this standard are subject to the generic
requirements and restrictions specified for standard built-in ECMAScript
objects in the ECMAScript 2020 Language Specification, 11th edition, clause
The Intl object is the %Intl% intrinsic object and the initial value of the
The value of the [[Prototype]] internal slot of the Intl object is the intrinsic object
The Intl object is not a
The Intl object has an internal slot, [[FallbackSymbol]], which is a new
See
See
See
See
See
See
When the getCanonicalLocales
method is called with argument locales, the following steps are taken:
The constructors for the objects providing locale sensitive
services, Collator, NumberFormat, DateTimeFormat, PluralRules, and
RelativeTimeFormat, use a common pattern to negotiate the requests
represented by the locales and options arguments against the actual
capabilities of their implementations. The common behaviour is described
here in terms of internal slots describing the capabilities and of
The constructors Intl.Collator, Intl.NumberFormat, Intl.DateTimeFormat, Intl.PluralRules, and Intl.RelativeTimeFormat have the following internal slots:
EXAMPLE An implementation of DateTimeFormat might include the language tag
Where the following
The abstract operation CanonicalizeLocaleList takes the following steps:
The BestAvailableLocale abstract operation compares the provided argument locale,
which must be a String value with a structurally valid and
canonicalized Unicode BCP 47 locale identifier, against the locales in availableLocales and returns either the longest non-empty prefix of locale that is an element of availableLocales, or
The LookupMatcher abstract operation compares requestedLocales, which must be a
The BestFitMatcher abstract operation compares requestedLocales, which must be a
The UnicodeExtensionComponents abstract operation returns the attributes and keywords from extension, which must be a
The InsertUnicodeExtensionAndCanonicalize abstract operation inserts extension, which must be a
The following algorithm refers to UTS 35's Unicode Language and Locale Identifiers grammar.
unicode_locale_id
production.
The ResolveLocale abstract operation compares a BCP 47 language priority list requestedLocales against the locales in availableLocales and determines the best available language to meet the request. availableLocales, requestedLocales, and relevantExtensionKeys must be provided as
The following steps are taken:
ukey
and optionsValue as uvalue
productions.ukey
and optionsValue as uvalue
productions.The LookupSupportedLocales abstract operation returns the subset of the provided BCP 47 language priority list requestedLocales for which availableLocales has a matching locale when using the BCP 47 Lookup algorithm. Locales appear in the same order in the returned list as in requestedLocales. The following steps are taken:
The BestFitSupportedLocales abstract operation returns the subset of the provided BCP 47 language priority list requestedLocales for which availableLocales has a matching locale when using the Best Fit Matcher algorithm. Locales appear in the same order in the returned list as in requestedLocales. The steps taken are implementation dependent.
The SupportedLocales abstract operation returns the subset of the provided BCP 47 language priority list requestedLocales for which availableLocales has a matching locale. Two algorithms are available to match the locales: the Lookup algorithm described in RFC 4647 section 3.4, and an implementation dependent best-fit algorithm. Locales appear in the same order in the returned list as in requestedLocales. The following steps are taken:
The abstract operation GetOption extracts the value of the property named property from the provided options object, converts it to the required type, checks whether it is one of a
The abstract operation DefaultNumberOption converts value to a
The abstract operation GetNumberOption extracts the value of the property named property from the provided options object, converts it to a
The PartitionPattern abstract operation is called with argument pattern.
This abstract operation parses an abstract pattern string into a
list of Records with two fields, [[Type]] and [[Value]].
The [[Value]] field will be a String value if [[Type]] is
The Locale
The following algorithm refers to UTS 35's Unicode Language and Locale Identifiers grammar.
unicode_language_subtag
production, throw a unicode_script_subtag
production, throw a unicode_region_subtag
production, throw a unicode_locale_id
production.unicode_language_id
production.unicode_language_subtag
production replaced by the string language.unicode_script_subtag
production, thenunicode_language_subtag
production of languageId, unicode_script_subtag
production replaced by the string script.unicode_region_subtag
production, thenunicode_language_subtag
production of languageId, the substring corresponding to "-"
and the unicode_script_subtag
production if present, "-"
, region, and the rest of languageId.unicode_region_subtag
production replaced by the string region.unicode_language_id
production replaced by the string languageId.The following algorithm refers to UTS 35's Unicode Language and Locale Identifiers grammar.
unicode_locale_id
production.
The following algorithm refers to UTS 35's Unicode Language and Locale Identifiers grammar. When the
type
sequence (from UTS 35 Unicode Locale Identifier, section 3.2), throw a type
sequence (from UTS 35 Unicode Locale Identifier, section 3.2), throw a type
sequence (from UTS 35 Unicode Locale Identifier, section 3.2), throw a
The Intl.Locale
The value of
This property has the attributes { [[Writable]]:
The value of the [[RelevantExtensionKeys]] internal slot is «
The Intl.Locale prototype object is itself an ordinary object. %LocalePrototype% is not an Intl.Locale instance and does not have an [[InitializedLocale]] internal slot or any of the other internal slots of Intl.Locale instance objects.
The initial value of
The initial value of the @@toStringTag property is the string value
This property has the attributes { [[Writable]]:
Intl.Locale.prototype.baseName
is an
unicode_language_id
production.
Intl.Locale.prototype.calendar
is an
This property only exists if
Intl.Locale.prototype.caseFirst
is an
Intl.Locale.prototype.collation
is an
Intl.Locale.prototype.hourCycle
is an
This property only exists if
Intl.Locale.prototype.numeric
is an
Intl.Locale.prototype.numberingSystem
is an
Intl.Locale.prototype.language
is an
unicode_locale_id
production.unicode_language_subtag
production of the unicode_language_id
.
Intl.Locale.prototype.script
is an
unicode_locale_id
production.unicode_language_id
production of locale does not contain the ["-" unicode_script_subtag]
sequence, return unicode_script_subtag
production of the unicode_language_id
.
Intl.Locale.prototype.region
is an
unicode_locale_id
production.unicode_language_id
production of locale does not contain the ["-" unicode_region_subtag]
sequence, return unicode_region_subtag
production of the unicode_language_id
.
The Intl.Collator
The abstract operation InitializeCollator accepts the arguments collator (which must be an object), locales, and options. It initializes collator as a
When the Intl.Collator
function is called with optional arguments locales and options, the following steps are taken:
The Intl.Collator
The value of Intl.Collator.prototype
is
This property has the attributes { [[Writable]]:
When the supportedLocalesOf
method is called with arguments locales and options, the following steps are taken:
The value of the
The value of the [[AvailableLocales]] internal slot is implementation defined within the constraints described in
The values of the [[SortLocaleData]] and [[SearchLocaleData]]
internal slots are implementation defined within the constraints
described in
The Intl.Collator prototype object is itself an ordinary object. %CollatorPrototype% is not an Intl.Collator instance and does not have an [[InitializedCollator]] internal slot or any of the other internal slots of Intl.Collator instance objects.
The initial value of Intl.Collator.prototype.constructor
is the intrinsic object
The initial value of the @@toStringTag property is the String value
This property has the attributes { [[Writable]]:
This named
Intl.Collator.prototype.compare is an
Array.prototype.sort
or other functions.
A Collator compare function is an anonymous built-in function that has a [[Collator]] internal slot.
When a Collator compare function F is called with arguments x and y, the following steps are taken:
The
When the CompareStrings abstract operation is called with arguments collator (which must be an object initialized as a Collator), x and y (which must be String values), it returns a Number other than
The sensitivity of collator is interpreted as follows:
If the collator is set to ignore punctuation, then strings that differ only in punctuation compare as equal.
For the interpretation of options settable through extension keys, see Unicode Technical Standard 35.
The CompareStrings abstract operation with any given collator argument, if considered as a function of the remaining two arguments x and y, must be a consistent comparison function (as defined in ES2020,
The actual return values are implementation-defined to permit
implementers to encode additional information in the value. The method
is required to return
This function provides access to the locale and collation options computed during initialization of the object.
Internal Slot | Property | Extension Key |
---|---|---|
[[Locale]] | ||
[[Usage]] | ||
[[Sensitivity]] | ||
[[IgnorePunctuation]] | ||
[[Collation]] | ||
[[Numeric]] | ||
[[CaseFirst]] |
Intl.Collator instances are ordinary objects that inherit properties from
Intl.Collator instances have an [[InitializedCollator]] internal slot.
Intl.Collator instances also have several internal slots that are computed by the
Intl.Collator instances also have the following internal slots if
the key corresponding to the name of the internal slot in
Finally, Intl.Collator instances have a [[BoundCompare]] internal
slot that caches the function returned by the compare accessor (
The abstract operation SetNumberFormatDigitOptions applies digit options used for number formatting onto the intl object.
The abstract operation InitializeNumberFormat accepts the arguments numberFormat (which must be an object), locales, and options. It initializes numberFormat as a NumberFormat object. The following steps are taken:
The following algorithm refers to the type
nonterminal from UTS 35's Unicode Locale Identifier grammar.
"numberingSystem"
, "string"
, type
nonterminal, throw a When the CurrencyDigits abstract operation is called with an argument currency (which must be an upper case String value), the following steps are taken:
A Number format function is an anonymous built-in function that has a [[NumberFormat]] internal slot.
When a Number format function F is called with optional argument value, the following steps are taken:
The
The FormatNumericToString abstract operation is called with arguments intlObject
(which must be an object with [[RoundingType]],
[[MinimumSignificantDigits]], [[MaximumSignificantDigits]],
[[MinimumIntegerDigits]], [[MinimumFractionDigits]], and
[[MaximumFractionDigits]] internal slots), and x (which must be a Number or BigInt value), and returns a
The PartitionNumberPattern abstract operation is called with arguments numberFormat (which must be an object initialized as a NumberFormat) and x (which must be a Number or BigInt value), interprets x as a numeric value, and creates the corresponding parts according to the effective locale and the formatting options of numberFormat. The following steps are taken:
The PartitionNotationSubPattern abstract operation is called with arguments numberFormat (which must be an object initialized as a NumberFormat), x (which is a numeric value after rounding is applied), n (which is an intermediate formatted string), and exponent (an
Numbering System | Digits |
---|---|
arab | U+0660 to U+0669 |
arabext | U+06F0 to U+06F9 |
bali | U+1B50 to U+1B59 |
beng | U+09E6 to U+09EF |
deva | U+0966 to U+096F |
fullwide | U+FF10 to U+FF19 |
gujr | U+0AE6 to U+0AEF |
guru | U+0A66 to U+0A6F |
hanidec | U+3007, U+4E00, U+4E8C, U+4E09, U+56DB, U+4E94, U+516D, U+4E03, U+516B, U+4E5D |
khmr | U+17E0 to U+17E9 |
knda | U+0CE6 to U+0CEF |
laoo | U+0ED0 to U+0ED9 |
latn | U+0030 to U+0039 |
limb | U+1946 to U+194F |
mlym | U+0D66 to U+0D6F |
mong | U+1810 to U+1819 |
mymr | U+1040 to U+1049 |
orya | U+0B66 to U+0B6F |
tamldec | U+0BE6 to U+0BEF |
telu | U+0C66 to U+0C6F |
thai | U+0E50 to U+0E59 |
tibt | U+0F20 to U+0F29 |
The FormatNumeric abstract operation is called with arguments numberFormat (which must be an object initialized as a NumberFormat) and x (which must be a Number or BigInt value), and performs the following steps:
The FormatNumericToParts abstract operation is called with arguments numberFormat (which must be an object initialized as a NumberFormat) and x (which must be a Number or BigInt value), and performs the following steps:
When the ToRawPrecision abstract operation is called with arguments x (which must be a finite non-negative Number or BigInt), minPrecision, and maxPrecision (both must be integers between 1 and 21), the following steps are taken:
When the ToRawFixed abstract operation is called with arguments x (which must be a finite non-negative Number or BigInt), minInteger (which must be an
The UnwrapNumberFormat abstract operation gets the underlying NumberFormat operation for various methods which implement ECMA-402 v1 semantics for supporting initializing existing Intl objects.
The abstract operation SetNumberFormatUnitOptions resolves the user-specified options relating to units onto the intl object.
The abstract operation GetNumberFormatPattern considers the
resolved unit-related options in the number format object along with the
final scaled and rounded number being formatted and returns a pattern, a
String value as described in
The abstract operation GetNotationSubPattern considers the resolved notation and exponent, and returns a String value for the notation sub pattern as described in
The abstract operation ComputeExponent computes an exponent (power of ten) by which to scale x according to the number formatting settings. It handles cases such as 999 rounding up to 1000, requiring a different exponent.
The abstract operation ComputeExponentHelper computes an exponent by which to scale a number of the given magnitude (power of ten of the most significant digit) according to the locale and the desired notation (scientific, engineering, or compact).
The NumberFormat
When the Intl.NumberFormat
function is called with optional arguments locales and options, the following steps are taken:
The Intl.NumberFormat
The value of Intl.NumberFormat.prototype
is
This property has the attributes { [[Writable]]:
When the supportedLocalesOf
method is called with arguments locales and options, the following steps are taken:
The value of the
The value of the [[AvailableLocales]] internal slot is implementation defined within the constraints described in
The value of the [[RelevantExtensionKeys]] internal slot is «
The value of the [[LocaleData]] internal slot is implementation defined within the constraints described in
The Intl.NumberFormat prototype object is itself an ordinary object. %NumberFormatPrototype% is not an Intl.NumberFormat instance and does not have an [[InitializedNumberFormat]] internal slot or any of the other internal slots of Intl.NumberFormat instance objects.
The initial value of Intl.NumberFormat.prototype.constructor
is the intrinsic object
The initial value of the @@toStringTag property is the String value
This property has the attributes { [[Writable]]:
Intl.NumberFormat.prototype.format is an
Array.prototype.map
or other functions.
This is considered a historical artefact, as part of a
convention which is no longer followed for new features, but is
preserved to maintain compatibility with existing programs.
When the formatToParts
method is called with an optional argument value, the following steps are taken:
This function provides access to the locale and formatting options computed during initialization of the object.
Internal Slot | Property |
---|---|
[[Locale]] | |
[[NumberingSystem]] | |
[[Style]] | |
[[Currency]] | |
[[CurrencyDisplay]] | |
[[CurrencySign]] | |
[[Unit]] | |
[[UnitDisplay]] | |
[[MinimumIntegerDigits]] | |
[[MinimumFractionDigits]] | |
[[MaximumFractionDigits]] | |
[[MinimumSignificantDigits]] | |
[[MaximumSignificantDigits]] | |
[[UseGrouping]] | |
[[Notation]] | |
[[CompactDisplay]] | |
[[SignDisplay]] |
Intl.NumberFormat instances are ordinary objects that inherit properties from
Intl.NumberFormat instances have an [[InitializedNumberFormat]] internal slot.
Intl.NumberFormat instances also have several internal slots that are computed by the
Finally, Intl.NumberFormat instances have a [[BoundFormat]]
internal slot that caches the function returned by the format accessor (
Several DateTimeFormat algorithms use values from the following table, which provides internal slots, property names and allowable values for the components of date and time formats:
Internal Slot | Property | Values |
---|---|---|
[[Weekday]] | ||
[[Era]] | ||
[[Year]] | ||
[[Month]] | ||
[[Day]] | ||
[[Hour]] | ||
[[Minute]] | ||
[[Second]] | ||
[[TimeZoneName]] |
The abstract operation InitializeDateTimeFormat accepts the arguments dateTimeFormat (which must be an object), locales, and options. It initializes dateTimeFormat as a DateTimeFormat object. This abstract operation functions as follows:
The following algorithm refers to the type
nonterminal from UTS 35's Unicode Locale Identifier grammar.
type
nonterminal, throw a type
nonterminal, throw a When the ToDateTimeOptions abstract operation is called with arguments options, required, and defaults, the following steps are taken:
When the BasicFormatMatcher abstract operation is called with two arguments options and formats, the following steps are taken:
When the BestFitFormatMatcher abstract operation is called with two arguments options and formats,
it performs implementation dependent steps, which should return a set
of component representations that a typical user of the selected locale
would perceive as at least as good as the one returned by
A DateTime format function is an anonymous built-in function that has a [[DateTimeFormat]] internal slot.
When a DateTime format function F is called with optional argument date, the following steps are taken:
The
The PartitionDateTimePattern abstract operation is called with arguments dateTimeFormat (which must be an object initialized as a DateTimeFormat) and x (which must be a
The FormatDateTime abstract operation is called with arguments dateTimeFormat (which must be an object initialized as a DateTimeFormat) and x (which must be a
The FormatDateTimeToParts abstract operation is called with arguments dateTimeFormat (which must be an object initialized as a DateTimeFormat) and x (which must be a
When the ToLocalTime abstract operation is called with arguments t, calendar, and timeZone, the following steps are taken:
Field | Value Calculation for Gregorian Calendar |
---|---|
[[Weekday]] | WeekDay(tz) specified in ES2020's |
[[Era]] | Let year be YearFromTime(tz) specified in ES2020's year is less than 0, return 'BC', else, return 'AD'. |
[[Year]] | YearFromTime(tz) specified in ES2020's |
[[RelatedYear]] | |
[[YearName]] | |
[[Month]] | MonthFromTime(tz) specified in ES2020's |
[[Day]] | DateFromTime(tz) specified in ES2020's |
[[Hour]] | HourFromTime(tz) specified in ES2020's |
[[Minute]] | MinuteFromTime(tz) specified in ES2020's |
[[Second]] | SecondFromTime(tz) specified in ES2020's |
[[InDST]] | Calculate |
The UnwrapDateTimeFormat abstract operation gets the underlying DateTimeFormat operation for various methods which implement ECMA-402 v1 semantics for supporting initializing existing Intl objects.
The Intl.DateTimeFormat
When the Intl.DateTimeFormat
function is called with optional arguments locales and options, the following steps are taken:
The Intl.DateTimeFormat
The value of Intl.DateTimeFormat.prototype
is
This property has the attributes { [[Writable]]:
When the supportedLocalesOf
method is called with arguments locales and options, the following steps are taken:
The value of the
The value of the [[AvailableLocales]] internal slot is implementation defined within the constraints described in
The value of the [[RelevantExtensionKeys]] internal slot is «
The value of the [[LocaleData]] internal slot is implementation defined within the constraints described in
EXAMPLE An implementation might include the following record as part of its English locale data: {[[hour]]:
The Intl.DateTimeFormat prototype object is itself an ordinary object. %DateTimeFormatPrototype% is not an Intl.DateTimeFormat instance and does not have an [[InitializedDateTimeFormat]] internal slot or any of the other internal slots of Intl.DateTimeFormat instance objects.
The initial value of Intl.DateTimeFormat.prototype.constructor
is the intrinsic object
The initial value of the @@toStringTag property is the String value
This property has the attributes { [[Writable]]:
Intl.DateTimeFormat.prototype.format is an
Array.prototype.map
or other functions.
This is considered a historical artefact, as part of a
convention which is no longer followed for new features, but is
preserved to maintain compatibility with existing programs.
When the formatToParts
method is called with an argument date, the following steps are taken:
This function provides access to the locale and formatting options computed during initialization of the object.
Internal Slot | Property |
---|---|
[[Locale]] | |
[[Calendar]] | |
[[NumberingSystem]] | |
[[TimeZone]] | |
[[HourCycle]] | |
[[Weekday]] | |
[[Era]] | |
[[Year]] | |
[[Month]] | |
[[Day]] | |
[[Hour]] | |
[[Minute]] | |
[[Second]] | |
[[TimeZoneName]] |
For web compatibility reasons, if the property
Intl.DateTimeFormat instances are ordinary objects that inherit properties from
Intl.DateTimeFormat instances have an [[InitializedDateTimeFormat]] internal slot.
Intl.DateTimeFormat instances also have several internal slots that are computed by the
Finally, Intl.DateTimeFormat instances have a [[BoundFormat]]
internal slot that caches the function returned by the format accessor (
The abstract operation InitializeRelativeTimeFormat accepts the arguments relativeTimeFormat (which must be an object), locales, and options. It initializes relativeTimeFormat as a RelativeTimeFormat object.
The following algorithm refers to UTS 35's Unicode Language and Locale Identifiers grammar. The following steps are taken:
type
sequence (from UTS 35 Unicode Locale Identifier, section 3.2), throw a
When the PartitionRelativeTimePattern abstract operation is called with arguments relativeTimeFormat, value, and unit it returns a String value representing value (which must be a
The MakePartsList abstract operation is called with arguments pattern, a pattern String, unit, a String, and parts, a
MakePartsList("AA{0}BB", "hour", « { [[Type]]: "integer", [[Value]]: "15" } » ) Output (List of Records): « { [[Type]]: "literal", [[Value]]: "AA"}, { [[Type]]: "integer", [[Value]]: "15", [[Unit]]: "hour"}, { [[Type]]: "literal", [[Value]]: "BB"} »
The FormatRelativeTime abstract operation is called with arguments relativeTimeFormat (which must be an object initialized as a RelativeTimeFormat), value (which must be a
The FormatRelativeTimeToParts abstract operation is called with arguments relativeTimeFormat (which must be an object initialized as a RelativeTimeFormat), value (which must be a
The RelativeTimeFormat
When the
The Intl.RelativeTimeFormat
The value of Intl.RelativeTimeFormat.prototype
is
This property has the attributes { [[Writable]]:
When the supportedLocalesOf
method of
The value of the [[AvailableLocales]] internal slot is implementation defined within the constraints described in
The value of the [[RelevantExtensionKeys]] internal slot is «
The value of the [[LocaleData]] internal slot is implementation defined within the constraints described in
The Intl.RelativeTimeFormat prototype object is itself an ordinary object. %RelativeTimeFormatPrototype% is not an Intl.RelativeTimeFormat instance and does not have an [[InitializedRelativeTimeFormat]] internal slot or any of the other internal slots of Intl.RelativeTimeFormat instance objects.
The initial value of Intl.RelativeTimeFormat.prototype.constructor
is
The initial value of the @@toStringTag property is the string value
This property has the attributes { [[Writable]]:
When the format
method is called with arguments value and unit, the following steps are taken:
When the formatToParts
method is called with arguments value and unit, the following steps are taken:
This function provides access to the locale and options computed during initialization of the object.
Internal Slot | Property |
---|---|
[[Locale]] | |
[[Style]] | |
[[Numeric]] | |
[[NumberingSystem]] |
Intl.RelativeTimeFormat instances are ordinary objects that inherit properties from
Intl.RelativeTimeFormat instances have an [[InitializedRelativeTimeFormat]] internal slot.
Intl.RelativeTimeFormat instances also have several internal slots that are computed by the
The abstract operation InitializePluralRules accepts the arguments pluralRules (which must be an object), locales, and options. It initializes pluralRules as a PluralRules object. The following steps are taken:
When the GetOperands abstract operation is called with argument s, it performs the following steps:
Internal Slot | Type | Description |
---|---|---|
[[Number]] | Number | Absolute value of the source number ( |
[[IntegerDigits]] | Number | Number of digits of [[Number]]. |
[[NumberOfFractionDigits]] | Number | Number of visible fraction digits in [[Number]], with trailing zeroes. |
[[NumberOfFractionDigitsWithoutTrailing]] | Number | Number of visible fraction digits in [[Number]], without trailing zeroes. |
[[FractionDigits]] | Number | Number of visible fractional digits in [[Number]], with trailing zeroes. |
[[FractionDigitsWithoutTrailing]] | Number | Number of visible fractional digits in [[Number]], without trailing zeroes. |
When the PluralRuleSelect abstract operation is called with four
arguments, it performs an implementation-dependent algorithm to map n to the appropriate plural representation of the Plural Rules Operands
When the ResolvePlural abstract operation is called with arguments pluralRules (which must be an object initialized as a PluralRules) and n (which must be a
The PluralRules
When the Intl.PluralRules
function is called with optional arguments locales and options, the following steps are taken:
The Intl.PluralRules
The value of Intl.PluralRules.prototype
is
This property has the attributes { [[Writable]]:
When the supportedLocalesOf
method is called with arguments locales and options, the following steps are taken:
The value of the supportedLocalesOf
method is 1.
The value of the [[AvailableLocales]] internal slot is implementation defined within the constraints described in
The value of the [[RelevantExtensionKeys]] internal slot is « ».
The value of the [[LocaleData]] internal slot is implementation defined within the constraints described in
The Intl.PluralRules prototype object is itself an ordinary object. %PluralRulesPrototype% is not an Intl.PluralRules instance and does not have an [[InitializedPluralRules]] internal slot or any of the other internal slots of Intl.PluralRules instance objects.
The initial value of Intl.PluralRules.prototype.constructor
is the intrinsic object
The initial value of the @@toStringTag property is the String value
This property has the attributes { [[Writable]]:
When the select
method is called with an argument value, the following steps are taken:
This function provides access to the locale and options computed during initialization of the object.
Internal Slot | Property |
---|---|
[[Locale]] | |
[[Type]] | |
[[MinimumIntegerDigits]] | |
[[MinimumFractionDigits]] | |
[[MaximumFractionDigits]] | |
[[MinimumSignificantDigits]] | |
[[MaximumSignificantDigits]] |
Intl.PluralRules instances are ordinary objects that inherit properties from
Intl.PluralRules instances have an [[InitializedPluralRules]] internal slot.
Intl.PluralRules instances also have several internal slots that are computed by the
The ECMAScript Language Specification, edition 10 or successor, describes several locale sensitive functions. An ECMAScript implementation that implements this Internationalization API Specification shall implement these functions as described here.
This definition supersedes the definition provided in ES2020,
When the localeCompare
method is called with argument that and optional arguments locales, and options, the following steps are taken:
The value of the
localeCompare
method itself is not directly suitable as an argument to localeCompare
function is intentionally generic; it does not require that its
This definition supersedes the definition provided in ES2020,
This function interprets a String value as a sequence of code points, as described in ES2020,
Lower case code point mappings may be derived according to a tailored version of the Default Case Conversion Algorithms of the Unicode Standard. Implementations may use locale specific tailoring defined in SpecialCasings.txt and/or CLDR and/or any other custom tailoring.
toLocaleUpperCase
and toLocaleLowerCase
have context-sensitive behaviour, the functions are not symmetrical. In other words, s.toLocaleUpperCase().toLocaleLowerCase()
is not necessarily equal to s.toLocaleLowerCase()
.
toLocaleLowerCase
function is intentionally generic; it does not require that its
This definition supersedes the definition provided in ES2020,
This function interprets a String value as a sequence of code points, as described in ES2020, String.prototype.toLocaleLowerCase
, except that characters are mapped to their uppercase
equivalents. A conforming implementation's upper case transformation
algorithm must always yield the same result given the same sequence of
code points and locale.
toLocaleUpperCase
function is intentionally generic; it does not require that its
The following definition(s) refer to the abstract operation
This definition supersedes the definition provided in ES2020,
When the toLocaleString
method is called with optional arguments locales and options, the following steps are taken:
The following definition(s) refer to the abstract operation
This definition supersedes the definition provided in ES2020,
When the toLocaleString
method is called with optional arguments locales and options, the following steps are taken:
The following definition(s) refer to the abstract operation
This definition supersedes the definition provided in ES2020,
When the toLocaleString
method is called with optional arguments locales and options, the following steps are taken:
This definition supersedes the definition provided in ES2020,
When the toLocaleDateString
method is called with optional arguments locales and options, the following steps are taken:
This definition supersedes the definition provided in ES2020,
When the toLocaleTimeString
method is called with optional arguments locales and options, the following steps are taken:
This definition supersedes the definition provided in ES2020,
When the toLocaleString
method is called with optional arguments locales and options, the following steps are taken:
toLocaleString
function is intentionally generic; it does not require that its The following aspects of the ECMAScript 2020 Internationalization API Specification are implementation dependent:
This specification is authored on GitHub in a plaintext source format called Ecmarkup. Ecmarkup is an HTML and Markdown dialect that provides a framework and toolset for authoring ECMAScript specifications in plaintext and processing the specification into a full-featured HTML rendering that follows the editorial conventions for this document. Ecmarkup builds on and integrates a number of other formats and technologies including Grammarkdown for defining syntax and Ecmarkdown for authoring algorithm steps. PDF renderings of this specification are produced by printing the HTML rendering to a PDF.
Prior editions of this specification were authored using Word—the Ecmarkup source text that formed the basis of this edition was produced by converting the ECMAScript 2015 Word document to Ecmarkup using an automated conversion tool.