?
u
/
p
1-9
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 2024 Internationalization API Specification (ECMA-402 11th Edition), provides key language sensitive functionality as a complement to the ECMAScript 2024 Language Specification (ECMA-262 15th 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 (https://unicode-org.github.io/icu-docs/), 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
Leo Balter, Richard Gibson
ECMA-402, 8th Edition Project Editors
Leo Balter, Richard Gibson, Ujjwal Sharma
ECMA-402, 9th Edition Project Editors
Richard Gibson, Ujjwal Sharma
ECMA-402, 10th Edition Project Editors
Richard Gibson, Ujjwal Sharma
ECMA-402, 11th 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 this specification must conform to the ECMAScript 2024 Language Specification (ECMA-262 15th Edition, or successor), and must provide and support all the objects, properties, functions, and program semantics described in this specification. Nothing in this specification is intended to allow behaviour that is otherwise prohibited by ECMA-262, and any such conflict should be considered an editorial error rather than an override of constraints from ECMA-262.
A conforming implementation is permitted to provide additional objects, properties, and functions beyond those described in this specification. In particular, a conforming implementation is permitted to provide properties not described in this specification, and values for those properties, for objects that are described herein. 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
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 2024 Language Specification (ECMA-262 15th Edition, or successor).
https://www.ecma-international.org/publications/standards/Ecma-262.htm
This section contains a non-normative overview of the ECMAScript 2024 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 2024 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. This specification builds on that foundation 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.
This specification is designed to complement the ECMAScript 2024 Language Specification by providing key language-sensitive functionality. The API can be added to an implementation of the ECMAScript 2024 Language Specification (ECMA-262 15th Edition, or successor) in whole or in part. This specification introduces new language values observable to ECMAScript code (such as the value of a [[FallbackSymbol]] internal slot and the set of values transitively reachable from
This specification provides several key pieces of language-sensitive functionality that are required in most applications: String comparison (collation), number formatting, date and time formatting, relative time formatting, display names, list formatting, locale selection and operation, pluralization rules, case conversion, and text segmentation. While the ECMAScript 2024 Language Specification provides functions for this basic functionality (on toLocaleString
; on localeCompare
, toLocaleLowerCase
, toLocaleUpperCase
; on toLocaleString
; on toLocaleString
, toLocaleDateString
, and toLocaleTimeString
), their actual behaviour is left largely implemenation-defined. This 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:
compare
, select
, format
, etc.), which can be called repeatedly. It also provides a resolvedOptions
function, which the application can use to find out the exact configuration of the object.
The Intl object is used to package all functionality defined in this specification in order to avoid name collisions.
Every
Due to the nature of internationalization, this 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 2024 Language Specification (ECMA-262 15th Edition), as es2024:
As an extension to the
This specification uses blocks demarcated as
The following table extends the Well-Known Intrinsic Objects table defined in es2024,
Intrinsic Name | Global Name | ECMAScript Language Association |
---|---|---|
Intl |
The Intl object ( |
|
Intl.Collator |
The Intl.Collator |
|
Intl.DateTimeFormat |
The Intl.DateTimeFormat |
|
Intl.DisplayNames |
The Intl.DisplayNames |
|
Intl.ListFormat |
The Intl.ListFormat |
|
Intl.Locale |
The Intl.Locale |
|
Intl.NumberFormat |
The Intl.NumberFormat |
|
Intl.PluralRules |
The Intl.PluralRules |
|
Intl.RelativeTimeFormat |
The Intl.RelativeTimeFormat |
|
Intl.Segmenter |
The Intl.Segmenter |
|
The prototype of |
||
The prototype of Segments objects ( |
This clause describes the String values used in this specification to identify locales, currencies, time zones, measurement units, numbering systems, collations, calendars, and pattern strings.
The String values used to identify locales, currencies, scripts, and time zones are interpreted in an ASCII-case-insensitive manner, treating the code units 0x0041 through 0x005A (corresponding to Unicode characters LATIN CAPITAL LETTER A through LATIN CAPITAL LETTER Z) as equivalent to the corresponding code units 0x0061 through 0x007A (corresponding to Unicode characters LATIN SMALL LETTER A through LATIN SMALL LETTER Z), both inclusive. No other case folding equivalences are applied.
The ASCII-uppercase of a String value S is the String value derived from S by replacing each occurrence of an ASCII lowercase letter code unit (0x0061 through 0x007A, inclusive) with the corresponding ASCII uppercase letter code unit (0x0041 through 0x005A, inclusive) while preserving all other code units.
The ASCII-lowercase of a String value S is the String value derived from S by replacing each occurrence of an ASCII uppercase letter code unit (0x0041 through 0x005A, inclusive) with the corresponding ASCII lowercase letter code unit (0x0061 through 0x007A, inclusive) while preserving all other code units.
A String value A is an ASCII-case-insensitive match for String value B if the ASCII-uppercase of A is exactly the same sequence of code units as the ASCII-uppercase of B. A sequence of Unicode code points A is an ASCII-case-insensitive match for B if B is an ASCII-case-insensitive match for
This specification identifies locales using Unicode BCP 47 locale identifiers as defined by Unicode Technical Standard #35 Part 1 Core, Section 3.3 BCP 47 Conformance, and its algorithms refer to Unicode locale nonterminals defined in the grammars of Section 3 Unicode Language and Locale Identifiers. Each such identifier can also be referred to as a language tag, and is in fact a valid language tag as that term is used in BCP 47. A locale identifier in canonical form as specified in Unicode Technical Standard #35 Part 1 Core, Section 3.2.1 Canonical Unicode Locale Identifiers is referred to as a "Unicode canonicalized locale identifier".
Locale identifiers consist of case-insensitive Unicode Basic Latin alphanumeric subtags separated by unicode_locale_extensions
Unicode locale nonterminal and is not part of a
All
The abstract operation IsStructurallyValidLanguageTag takes argument locale (a String) and returns a Boolean. It determines whether locale is a syntactically well-formed
unicode_locale_id
unicode_language_id
pu_extensions
transformed_extensions
tlang
unicode_language_subtag
unicode_variant_subtag
The abstract operation CanonicalizeUnicodeLocaleId takes argument locale (a
The
This specification identifies currencies using 3-letter currency codes as defined by ISO 4217. Their canonical form is uppercase.
All well-formed 3-letter ISO 4217 currency codes are allowed. However, the set of combinations of currency code and
The abstract operation IsWellFormedCurrencyCode takes argument currency (a String) and returns a Boolean. It verifies that the currency argument represents a well-formed 3-letter ISO currency code. It performs the following steps when called:
The
Implementations that adopt this specification must be
Each Zone in the IANA Time Zone Database must be a
zone.tab
must be a zone.tab
and that represents a geographical area entirely contained within the territory of a single ISO 3166-1 Alpha-2 country code must resolve to a primary identifier that also represents a geographical area entirely contained within the territory of the same country code.
For example,
The IANA Time Zone Database offers build options that affect which
The Unicode Common Locale Data Repository (CLDR) implements most of the exceptions above when determining which timezone.xml
.
Implementations may also build the IANA Time Zone Database directly, for example by using build options such as PACKRATDATA=backzone PACKRATLIST=zone.tab
and performing any post-processing needed to ensure compliance with the requirements above.
The IANA Time Zone Database is typically updated between five and ten times per year.
These updates may add new Zone or Link names, may change Zones to Links, and may change the UTC offsets and transitions associated with any Zone.
Implementations are recommended to include updates to the IANA Time Zone Database as soon as possible.
Such prompt action ensures that ECMAScript programs can accurately perform time-zone-sensitive calculations and can use newly-added
Although the IANA Time Zone Database maintainers strive for stability, in rare cases (averaging less than once per year) a Zone may be replaced by a new Zone.
For example, in 2022 "
To reduce disruption from these infrequent changes, implementations should initially add each replacement time zone identifier as a
A waiting period should only apply when a new Zone is added to replace an existing Zone. If an existing Zone and Link are swapped, then no renaming has happened and no waiting period is necessary.
If implementations revise time zone information during the lifetime of an
This section complements but does not supersede
The
This definition supersedes the definition provided in
zone.tab
of the IANA Time Zone Database, thenzone.tab
of the IANA Time Zone Database where the “country-code” column is identifierCountryCode.zone.tab
of the IANA Time Zone Database where the “country-code” column is identifierCountryCode.backzone
of the IANA Time Zone Database that start with either
The algorithm above for resolving Links to icu::TimeZone::getIanaID()
in the International Components for Unicode (ICU) and the processes for maintaining
This algorithm resolves Links to zone.tab
and backzone
of the IANA Time Zone Database.
If the country code of a Link has only one line in zone.tab
, then that line will determine the zone.tab
, then historical mappings in backzone
must be used to identify the correct
For example, to resolve "Pacific/Truk" (in country code "FM") if the default build options of the IANA Time Zone Database identify it as a Link to "Pacific/Port_Moresby" (in country code "PG"), then the “country-code” column of zone.tab
must be checked for lines corresponding with "FM".
If there were only one such line, then the “TZ” column of that line would determine the zone.tab
, then backzone
must be inspected and a line such as "Link Pacific/Chuuk Pacific/Truk" would result in using "Pacific/Chuuk" as the
Note that zone.tab
is the preferred source of mapping data because backzone
mappings may, in rare cases, cross the boundaries of ISO 3166-1 Alpha-2 country codes.
For example, "Atlantic/Jan_Mayen" (in country code "SJ") is mapped in backzone
to "Europe/Oslo" (in country code "NO").
As of the 2024a release of the IANA Time Zone Database, "Atlantic/Jan_Mayen" is the only case where this happens.
The abstract operation GetAvailableNamedTimeZoneIdentifier takes argument timeZoneIdentifier (a String) and returns either a
The abstract operation AvailablePrimaryTimeZoneIdentifiers takes no arguments and returns a
The abstract operation StringSplitToList takes arguments S (a String) and separator (a String) and returns a
This specification identifies measurement units using a core unit identifier (or equivalently core unit ID) as defined by Unicode Technical Standard #35 Part 2 General, Section 6.2 Unit Identifiers. Their canonical form is a string containing only Unicode Basic Latin lowercase letters (U+0061 LATIN SMALL LETTER A through U+007A LATIN SMALL LETTER Z) with zero or more medial hyphens (U+002D HYPHEN-MINUS).
Only a limited set of core unit identifiers are sanctioned.
Attempting to use an unsanctioned core unit identifier results in a
The abstract operation IsWellFormedUnitIdentifier takes argument unitIdentifier (a String) and returns a Boolean. It verifies that the unitIdentifier argument represents a well-formed
The abstract operation IsSanctionedSingleUnitIdentifier takes argument unitIdentifier (a String) and returns a Boolean. It verifies that the unitIdentifier argument is among the single unit identifiers sanctioned in the current version of this specification, which are a subset of the Common Locale Data Repository release 38 unit validity data; the list may grow over time. As discussed in Unicode Technical Standard #35 Part 2 General, Section 6.2 Unit Identifiers, a single unit identifier is a
Single Unit Identifier |
---|
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 |
microsecond |
mile |
mile-scandinavian |
milliliter |
millimeter |
millisecond |
minute |
month |
nanosecond |
ounce |
percent |
petabyte |
pound |
second |
stone |
terabit |
terabyte |
week |
yard |
year |
The abstract operation AvailableCanonicalUnits takes no arguments and returns a
This specification identifies numbering systems using a numbering system identifier corresponding with the name referenced by Unicode Technical Standard #35 Part 3 Numbers, Section 1 Numbering Systems. Their canonical form is a string containing only Unicode Basic Latin lowercase letters (U+0061 LATIN SMALL LETTER A through U+007A LATIN SMALL LETTER Z).
The
This specification identifies collations using a collation type as defined by Unicode Technical Standard #35 Part 5 Collation, Section 3.1 Collation Types. Their canonical form is a string containing only Unicode Basic Latin lowercase letters (U+0061 LATIN SMALL LETTER A through U+007A LATIN SMALL LETTER Z) with zero or more medial hyphens (U+002D HYPHEN-MINUS).
The
This specification identifies calendars using a calendar type as defined by Unicode Technical Standard #35 Part 4 Dates, Section 2 Calendar Elements. Their canonical form is a string containing only Unicode Basic Latin lowercase letters (U+0061 LATIN SMALL LETTER A through U+007A LATIN SMALL LETTER Z) with zero or more medial hyphens (U+002D HYPHEN-MINUS).
The
Pattern String
Unless specified otherwise in this document, the objects, functions, and
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 new
operator. The Intl object does not have a [[Call]] internal method; it is not possible to invoke the Intl object as a function.
The Intl object has an internal slot, [[FallbackSymbol]], which is a new
The initial value of the
This property has the attributes { [[Writable]]:
With the exception of Intl.Locale, each of the following
See
See
See
See
See
See
See
See
See
When the getCanonicalLocales
method is called with argument locales, the following steps are taken:
When the supportedValuesOf
method is called with argument key , the following steps are taken:
An Available Locales List is an arbitrarily-ordered duplicate-free
A Language Priority List is a
Each
The abstract operation CanonicalizeLocaleList takes argument locales (an
The abstract operation CanonicalizeUValue takes arguments ukey (a
common/bcp47
provided by the Common Locale Data Repository (available at https://cldr.unicode.org/).The abstract operation LookupMatchingLocaleByPrefix takes arguments availableLocales (an
The
The abstract operation UnicodeExtensionComponents takes argument extension (a
The abstract operation InsertUnicodeExtensionAndCanonicalize takes arguments locale (a
The abstract operation ResolveLocale takes arguments availableLocales (an keyword
key
value is not contained within relevantExtensionKeys or type
value is superseded by a different value from options. It performs the following steps when called:
The abstract operation FilterLocales takes arguments availableLocales (an
The abstract operation GetOptionsObject takes argument options (an
The abstract operation CoerceOptionsToObject takes argument options (an
The abstract operation GetOption takes arguments options (an Object), property (a
The abstract operation GetBooleanOrStringNumberFormatOption takes arguments options (an Object), property (a
The abstract operation DefaultNumberOption takes arguments value (an
The abstract operation GetNumberOption takes arguments options (an Object), property (a String), minimum (an
The abstract operation PartitionPattern takes argument pattern (a
The Intl.Collator
When the Intl.Collator
function is called with optional arguments locales and options, the following steps are taken:
type
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 [[AvailableLocales]] internal slot is
The values of the [[SortLocaleData]] and [[SearchLocaleData]] internal slots are
The Intl.Collator prototype object is itself an
The initial value of Intl.Collator.prototype.constructor
is
The initial value of the
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
The
Behaviour as described below depends upon locale-sensitive identification of the sequence of collation elements for a string, in particular "base letters", and different base letters always compare as unequal (causing the strings containing them to also compare as unequal). Results of comparing variations of the same base letter with different case, diacritic marks, or potentially other aspects further depends upon collator.[[Sensitivity]] as follows:
[[Sensitivity]] | Description | ||
---|---|---|---|
Characters with the same base letter do not compare as unequal, regardless of differences in case and/or diacritic marks. | equal | equal | |
Characters with the same base letter compare as unequal only if they differ in accents and/or other diacritic marks, regardless of differences in case. | not equal | equal | |
Characters with the same base letter compare as unequal only if they differ in case, regardless of differences in accents and/or other diacritic marks. | equal | not equal | |
Characters with the same base letter compare as unequal if they differ in case, diacritic marks, and/or potentially other differences. | not equal | not equal |
If collator.[[IgnorePunctuation]] is
For the interpretation of options settable through locale extension keys, see Unicode Technical Standard #35 Part 1 Core, Section 3.6.1 Key and Type Definitions.
The actual return values are
This function provides access to the locale and options computed during initialization of the object.
Internal Slot | Property | Extension Key |
---|---|---|
[[Locale]] | ||
[[Usage]] | ||
[[Sensitivity]] | ||
[[IgnorePunctuation]] | ||
[[Collation]] | ||
[[Numeric]] | ||
[[CaseFirst]] |
Intl.Collator instances are
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 Intl.DateTimeFormat
When the Intl.DateTimeFormat
function is called with optional arguments locales and options, the following steps are taken:
The abstract operation ChainDateTimeFormat takes arguments dateTimeFormat (an Intl.DateTimeFormat), newTarget (an
The abstract operation CreateDateTimeFormat takes arguments newTarget (a
type
type
The abstract operation FormatOffsetTimeZoneIdentifier takes argument offsetMinutes (an
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 [[AvailableLocales]] internal slot is
The value of the [[RelevantExtensionKeys]] internal slot is «
The value of the [[LocaleData]] internal slot is
Each DateTime Format Record has the fields defined in
Field Name | Value Type | Description |
---|---|---|
[[weekday]] | [[Weekday]] values in the Values column of |
Optional field. Present if [[pattern]] contains the |
[[era]] | [[Era]] values in the Values column of |
Optional field. Present if [[pattern]] contains the |
[[year]] | [[Year]] values in the Values column of |
Optional field. Present if [[pattern]] contains at least one of the substrings |
[[month]] | [[Month]] values in the Values column of |
Optional field. Present if [[pattern]] contains the |
[[day]] | [[Day]] values in the Values column of |
Optional field. Present if [[pattern]] contains the |
[[dayPeriod]] | [[DayPeriod]] values in the Values column of |
Optional field. Present if [[pattern]] contains the |
[[hour]] | [[Hour]] values in the Values column of |
Optional field. Present if [[pattern]] contains the |
[[minute]] | [[Minute]] values in the Values column of |
Optional field. Present if [[pattern]] contains the |
[[second]] | [[Second]] values in the Values column of |
Optional field. Present if [[pattern]] contains the |
[[fractionalSecondDigits]] | [[FractionalSecondDigits]] values in the Values column of |
Optional field. Present if [[pattern]] contains the |
[[timeZoneName]] | [[TimeZoneName]] values in the Values column of |
Optional field. Present if [[pattern]] contains the |
[[pattern]] | a |
|
[[pattern12]] | a |
Optional field. Present if the [[hour]] field is present. In addition to the substrings of the [[pattern]] field, contains at least one of the substrings |
[[rangePatterns]] | a |
Pattern strings in this field are similar to [[pattern]]. |
[[rangePatterns12]] | a |
Optional field. Present if the [[hour]] field is present. Pattern strings in this field are similar to [[pattern12]]. |
Each DateTime Range Pattern Record has the fields defined in
Field Name | Value Type | Description |
---|---|---|
[[Default]] | a |
It contains the default range pattern used when a more specific range pattern is not available. |
[[Era]] | a |
Optional field. Used when era is the largest calendar element that is different between the start and end dates. |
[[Year]] | a |
Optional field. Used when year is the largest calendar element that is different between the start and end dates. |
[[Month]] | a |
Optional field. Used when month is the largest calendar element that is different between the start and end dates. |
[[Day]] | a |
Optional field. Used when day is the largest calendar element that is different between the start and end dates. |
[[AmPm]] | a |
Optional field. Used when ante or post meridiem is the largest calendar element that is different between the start and end dates. |
[[DayPeriod]] | a |
Optional field. Used when day period is the largest calendar element that is different between the start and end dates. |
[[Hour]] | a |
Optional field. Used when hour is the largest calendar element that is different between the start and end dates. |
[[Minute]] | a |
Optional field. Used when minute is the largest calendar element that is different between the start and end dates. |
[[Second]] | a |
Optional field. Used when second is the largest calendar element that is different between the start and end dates. |
[[FractionalSecondDigits]] | a |
Optional field. Used when fractional seconds are the largest calendar element that is different between the start and end dates. |
Each DateTime Range Pattern Format Record has the fields defined in
Field Name | Value Type | Description |
---|---|---|
[[weekday]] | [[Weekday]] values in the Values column of |
Optional field. Present if a |
[[era]] | [[Era]] values in the Values column of |
Optional field. Present if a |
[[year]] | [[Year]] values in the Values column of |
Optional field. Present if a |
[[month]] | [[Month]] values in the Values column of |
Optional field. Present if a |
[[day]] | [[Day]] values in the Values column of |
Optional field. Present if a |
[[dayPeriod]] | [[DayPeriod]] values in the Values column of |
Optional field. Present if a |
[[hour]] | [[Hour]] values in the Values column of |
Optional field. Present if a |
[[minute]] | [[Minute]] values in the Values column of |
Optional field. Present if a |
[[second]] | [[Second]] values in the Values column of |
Optional field. Present if a |
[[fractionalSecondDigits]] | [[FractionalSecondDigits]] values in the Values column of |
Optional field. Present if a |
[[timeZoneName]] | [[TimeZoneName]] values in the Values column of |
Optional field. Present if a |
[[PatternParts]] | a |
Each record represents a part of the range pattern. |
Each DateTime Range Pattern Part Record has the fields defined in
Field Name | Value Type | Description |
---|---|---|
[[Source]] | It indicates which of the range's dates should be formatted using the value of the [[Pattern]] field. | |
[[Pattern]] | a |
A String of the same format as the regular date pattern String. |
Each DateTime Styles Record has the fields defined in
Field Name | Value Type |
---|---|
[[Date]] | a |
[[Time]] | a |
[[Connector]] | a |
[[DateTimeRangeFormat]] | a |
Each DateTime Style Record has the fields defined in
Field Name | Value Type | Description |
---|---|---|
[[full]] | a |
Format record for the |
[[long]] | a |
Format record for the |
[[medium]] | a |
Format record for the |
[[short]] | a |
Format record for the |
Each DateTime Connector Record has the fields defined in
Field Name | Value Type | Description |
---|---|---|
[[full]] | a |
Connector pattern when the date style is |
[[long]] | a |
Connector pattern when the date style is |
[[medium]] | a |
Connector pattern when the date style is |
[[short]] | a |
Connector pattern when the date style is |
Each DateTime Date Range Record has the fields defined in
Field Name | Value Type | Description |
---|---|---|
[[full]] | a |
Used when date style is |
[[long]] | a |
Used when date style is |
[[medium]] | a |
Used when date style is |
[[short]] | a |
Used when date style is |
Each DateTime Time Range Record has the fields defined in
Field Name | Value Type | Description |
---|---|---|
[[full]] | a |
Used when time style is |
[[long]] | a |
Used when time style is |
[[medium]] | a |
Used when time style is |
[[short]] | a |
Used when time style is |
Each DateTime Style Range Record has the fields defined in
Field Name | Value Type | Description |
---|---|---|
[[rangePatterns]] | a |
Range patterns to combine date and time styles. |
[[rangePatterns12]] | a |
Optional Field. Range patterns to combine date and time styles for 12-hour formats. |
The Intl.DateTimeFormat prototype object is itself an
The initial value of Intl.DateTimeFormat.prototype.constructor
is
The initial value of the
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:
When the formatRange
method is called with arguments startDate and endDate, the following steps are taken:
When the formatRangeToParts
method is called with arguments startDate and endDate, the following steps are taken:
This function provides access to the locale and options computed during initialization of the object.
Internal Slot | Property | Conversion |
---|---|---|
[[Locale]] | ||
[[Calendar]] | ||
[[NumberingSystem]] | ||
[[TimeZone]] | ||
[[HourCycle]] | ||
[[HourCycle]] | ||
[[DateStyle]] | ||
[[TimeStyle]] |
For web compatibility reasons, if the property
Intl.DateTimeFormat instances are
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 (
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:
Field Name | Property | Values |
---|---|---|
[[Weekday]] | ||
[[Era]] | ||
[[Year]] | ||
[[Month]] | ||
[[Day]] | ||
[[DayPeriod]] | ||
[[Hour]] | ||
[[Minute]] | ||
[[Second]] | ||
[[FractionalSecondDigits]] | 1, 2, 3 | |
[[TimeZoneName]] |
The abstract operation DateTimeStyleFormat takes arguments dateStyle (
The abstract operation BasicFormatMatcher takes arguments options (a
The
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 abstract operation FormatDateTimePattern takes arguments dateTimeFormat (an Intl.DateTimeFormat), format (a
The abstract operation PartitionDateTimePattern takes arguments dateTimeFormat (an Intl.DateTimeFormat) and x (a Number) and returns either a
The abstract operation FormatDateTime takes arguments dateTimeFormat (an Intl.DateTimeFormat) and x (a Number) and returns either a
The abstract operation FormatDateTimeToParts takes arguments dateTimeFormat (an Intl.DateTimeFormat) and x (a Number) and returns either a
The abstract operation PartitionDateTimeRangePattern takes arguments dateTimeFormat (an Intl.DateTimeFormat), x (a Number), and y (a Number) and returns either a
The abstract operation FormatDateTimeRange takes arguments dateTimeFormat (an Intl.DateTimeFormat), x (a Number), and y (a Number) and returns either a
The abstract operation FormatDateTimeRangeToParts takes arguments dateTimeFormat (an Intl.DateTimeFormat), x (a Number), and y (a Number) and returns either a
The
Each ToLocalTime Record has the fields defined in
Field Name | Value Type | Value Calculation for Gregorian Calendar |
---|---|---|
[[Weekday]] | an |
|
[[Era]] | a String | Let year be |
[[Year]] | an |
|
[[RelatedYear]] | an |
|
[[YearName]] | a String or |
|
[[Month]] | an |
|
[[Day]] | an |
|
[[Hour]] | an |
|
[[Minute]] | an |
|
[[Second]] | an |
|
[[Millisecond]] | an |
|
[[InDST]] | a Boolean | Calculate |
The abstract operation UnwrapDateTimeFormat takes argument dtf (an
The DisplayNames
When the Intl.DisplayNames
function is called with arguments locales and options, the following steps are taken:
The Intl.DisplayNames
The value of Intl.DisplayNames.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 [[AvailableLocales]] internal slot is
The value of the [[RelevantExtensionKeys]] internal slot is « ».
The value of the [[LocaleData]] internal slot is
unicode_language_id
type
The Intl.DisplayNames prototype object is itself an
The initial value of Intl.DisplayNames.prototype.constructor
is
The initial value of the
This property has the attributes { [[Writable]]:
When the Intl.DisplayNames.prototype.of
is called with an argument code, 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]] | |
[[Type]] | |
[[Fallback]] | |
[[LanguageDisplay]] |
Intl.DisplayNames instances are
Intl.DisplayNames instances have an [[InitializedDisplayNames]] internal slot.
Intl.DisplayNames instances also have several internal slots that are computed by the
The abstract operation CanonicalCodeForDisplayNames takes arguments type (a String) and code (a String) and returns either a
unicode_language_id
unicode_region_subtag
unicode_script_subtag
type
The abstract operation IsValidDateTimeFieldCode takes argument field (a String) and returns a Boolean. It verifies that the field argument represents a valid date time field code. It performs the following steps when called:
Code | Description |
---|---|
The field indicating the era, e.g. AD or BC in the Gregorian or Julian calendar. | |
The field indicating the year (within an era). | |
The field indicating the quarter, e.g. Q2, 2nd quarter, etc. | |
The field indicating the month, e.g. Sep, September, etc. | |
The field indicating the week number within a year. | |
The field indicating the day of week, e.g. Tue, Tuesday, etc. | |
The field indicating the day in month. | |
The field indicating the day period, either am, pm, etc. or noon, evening, etc.. | |
The field indicating the hour. | |
The field indicating the minute. | |
The field indicating the second. | |
The field indicating the time zone name, e.g. PDT, Pacific Daylight Time, etc. |
The ListFormat
When the Intl.ListFormat
function is called with optional arguments locales and options, the following steps are taken:
The Intl.ListFormat
The value of Intl.ListFormat.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 [[AvailableLocales]] internal slot is
The value of the [[RelevantExtensionKeys]] internal slot is « ».
The value of the [[LocaleData]] internal slot is
conjunction
corresponds to "standard", disjunction
corresponds to "or", and unit
corresponds to "unit".
conjunction
stands for "and"-based lists (e.g., "A, B, and C"), disjunction
stands for "or"-based lists (e.g., "A, B, or C"), and unit
stands for lists of values with units (e.g., "5 pounds, 12 ounces").
The Intl.ListFormat prototype object is itself an
The initial value of Intl.ListFormat.prototype.constructor
is
The initial value of the
This property has the attributes { [[Writable]]:
When the format
method is called with an argument list, the following steps are taken:
When the formatToParts
method is called with an argument list, 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]] | |
[[Style]] |
Intl.ListFormat instances inherit properties from
Intl.ListFormat instances have an [[InitializedListFormat]] internal slot.
Intl.ListFormat instances also have several internal slots that are computed by the
The abstract operation DeconstructPattern takes arguments pattern (a
It deconstructs the pattern string into a
placeables is a
Input: DeconstructPattern("AA{xx}BB{yy}CC", { [[xx]]: {[[Type]]: "hour", [[Value]]: "15"}, [[yy]]: {[[Type]]: "minute", [[Value]]: "06"} }) Output (List of parts Records): « {[[Type]]: "literal", [[Value]]: "AA"}, {[[Type]]: "hour", [[Value]]: "15"}, {[[Type]]: "literal", [[Value]]: "BB"}, {[[Type]]: "minute", [[Value]]: "06"}, {[[Type]]: "literal", [[Value]]: "CC"} »
It performs the following steps when called:
The abstract operation CreatePartsFromList takes arguments listFormat (an Intl.ListFormat) and list (a
The abstract operation FormatList takes arguments listFormat (an Intl.ListFormat) and list (a
The abstract operation FormatListToParts takes arguments listFormat (an Intl.ListFormat) and list (a
The abstract operation StringListFromIterable takes argument iterable (an
This algorithm raises exceptions when it encounters values that are not Strings, because there is no obvious locale-aware coercion for arbitrary values.
The Locale
When the Intl.Locale
function is called with an argument tag and an optional argument options, the following steps are taken:
type
type
type
The abstract operation UpdateLanguageId takes arguments tag (a unicode_language_id
unicode_language_id
unicode_language_subtag
unicode_script_subtag
unicode_region_subtag
unicode_language_id
The abstract operation MakeLocaleRecord takes arguments tag (a
The Intl.Locale
The value of Intl.Locale.prototype
is
This property has the attributes { [[Writable]]:
The value of the [[LocaleExtensionKeys]] internal slot is «
The Intl.Locale prototype object is itself an
The initial value of Intl.Locale.prototype.constructor
is
The initial value of the
This property has the attributes { [[Writable]]:
Intl.Locale.prototype.baseName
is an
unicode_language_id
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
Intl.Locale.prototype.script
is an
Intl.Locale.prototype.region
is an
Intl.Locale instances are
Intl.Locale instances have an [[InitializedLocale]] internal slot.
Intl.Locale instances also have several internal slots that are computed by the
The abstract operation GetLocaleLanguage takes argument locale (a String) and returns a String. It performs the following steps when called:
unicode_locale_id
unicode_language_id
unicode_language_subtag
The abstract operation GetLocaleScript takes argument locale (a String) and returns a String or
unicode_locale_id
unicode_language_id
unicode_script_subtag
unicode_script_subtag
The abstract operation GetLocaleRegion takes argument locale (a String) and returns a String or
unicode_locale_id
unicode_language_id
unicode_region_subtag
unicode_language_subtag
unicode_script_subtag
unicode_region_subtag
cannot be confused with any other valid unicode_language_subtag
unicode_region_subtag
unicode_region_subtag
The abstract operation GetLocaleVariants takes argument locale (a String) and returns a String or
unicode_locale_id
unicode_language_id
unicode_variant_subtag
The NumberFormat
When the Intl.NumberFormat
function is called with optional arguments locales and options, the following steps are taken:
type
The abstract operation ChainNumberFormat takes arguments numberFormat (an Intl.NumberFormat), newTarget (an
The abstract operation SetNumberFormatDigitOptions takes arguments intlObj (an Object), options (an Object), mnfdDefault (an
The abstract operation SetNumberFormatUnitOptions takes arguments intlObj (an Intl.NumberFormat) and options (an Object) and returns either a
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 [[AvailableLocales]] internal slot is
The value of the [[RelevantExtensionKeys]] internal slot is «
The value of the [[LocaleData]] internal slot is
The Intl.NumberFormat prototype object is itself an
The initial value of Intl.NumberFormat.prototype.constructor
is
The initial value of the
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:
When the formatRange
method is called with arguments start and end, the following steps are taken:
When the formatRangeToParts
method is called with arguments start and end, the following steps are taken:
This function provides access to the locale and options computed during initialization of the object.
Internal Slot | Property | Conversion |
---|---|---|
[[Locale]] | ||
[[NumberingSystem]] | ||
[[Style]] | ||
[[Currency]] | ||
[[CurrencyDisplay]] | ||
[[CurrencySign]] | ||
[[Unit]] | ||
[[UnitDisplay]] | ||
[[MinimumIntegerDigits]] | ||
[[MinimumFractionDigits]] | ||
[[MaximumFractionDigits]] | ||
[[MinimumSignificantDigits]] | ||
[[MaximumSignificantDigits]] | ||
[[UseGrouping]] | ||
[[Notation]] | ||
[[CompactDisplay]] | ||
[[SignDisplay]] | ||
[[RoundingIncrement]] | ||
[[RoundingMode]] | ||
[[ComputedRoundingPriority]] | ||
[[TrailingZeroDisplay]] |
Intl.NumberFormat instances are
Intl.NumberFormat instances have an [[InitializedNumberFormat]] internal slot.
Intl.NumberFormat instances also have several internal slots that are computed by the
Identifier | Description | Examples: Round to 0 fraction digits | ||||
---|---|---|---|---|---|---|
-1.5 | 0.4 | 0.5 | 0.6 | 1.5 | ||
Toward positive infinity | ⬆️ [-1] | ⬆️ [1] | ⬆️ [1] | ⬆️ [1] | ⬆️ [2] | |
Toward negative infinity | ⬇️ [-2] | ⬇️ [0] | ⬇️ [0] | ⬇️ [0] | ⬇️ [1] | |
Away from zero | ⬇️ [-2] | ⬆️ [1] | ⬆️ [1] | ⬆️ [1] | ⬆️ [2] | |
Toward zero | ⬆️ [-1] | ⬇️ [0] | ⬇️ [0] | ⬇️ [0] | ⬇️ [1] | |
Ties toward positive infinity | ⬆️ [-1] | ⬇️ [0] | ⬆️ [1] | ⬆️ [1] | ⬆️ [2] | |
Ties toward negative infinity | ⬇️ [-2] | ⬇️ [0] | ⬇️ [0] | ⬆️ [1] | ⬇️ [1] | |
Ties away from zero | ⬇️ [-2] | ⬇️ [0] | ⬆️ [1] | ⬆️ [1] | ⬆️ [2] | |
Ties toward zero | ⬆️ [-1] | ⬇️ [0] | ⬇️ [0] | ⬆️ [1] | ⬇️ [1] | |
Ties toward an even rounding increment multiple | ⬇️ [-2] | ⬇️ [0] | ⬇️ [0] | ⬆️ [1] | ⬆️ [2] |
Finally, Intl.NumberFormat instances have a [[BoundFormat]] internal slot that caches the function returned by the format accessor (
The abstract operation CurrencyDigits takes argument currency (a String) and returns a non-negative
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 abstract operation FormatNumericToString takes arguments intlObject (an Object) and x (a
The abstract operation PartitionNumberPattern takes arguments numberFormat (an object initialized as a NumberFormat) and x (an
The abstract operation PartitionNotationSubPattern takes arguments numberFormat (an Intl.NumberFormat), x (an
Numbering System | Digits |
---|---|
adlm | U+1E950 to U+1E959 |
ahom | U+11730 to U+11739 |
arab | U+0660 to U+0669 |
arabext | U+06F0 to U+06F9 |
bali | U+1B50 to U+1B59 |
beng | U+09E6 to U+09EF |
bhks | U+11C50 to U+11C59 |
brah | U+11066 to U+1106F |
cakm | U+11136 to U+1113F |
cham | U+AA50 to U+AA59 |
deva | U+0966 to U+096F |
diak | U+11950 to U+11959 |
fullwide | U+FF10 to U+FF19 |
gong | U+11DA0 to U+11DA9 |
gonm | U+11D50 to U+11D59 |
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 |
hmng | U+16B50 to U+16B59 |
hmnp | U+1E140 to U+1E149 |
java | U+A9D0 to U+A9D9 |
kali | U+A900 to U+A909 |
kawi | U+11F50 to U+11F59 |
khmr | U+17E0 to U+17E9 |
knda | U+0CE6 to U+0CEF |
lana | U+1A80 to U+1A89 |
lanatham | U+1A90 to U+1A99 |
laoo | U+0ED0 to U+0ED9 |
latn | U+0030 to U+0039 |
lepc | U+1C40 to U+1C49 |
limb | U+1946 to U+194F |
mathbold | U+1D7CE to U+1D7D7 |
mathdbl | U+1D7D8 to U+1D7E1 |
mathmono | U+1D7F6 to U+1D7FF |
mathsanb | U+1D7EC to U+1D7F5 |
mathsans | U+1D7E2 to U+1D7EB |
mlym | U+0D66 to U+0D6F |
modi | U+11650 to U+11659 |
mong | U+1810 to U+1819 |
mroo | U+16A60 to U+16A69 |
mtei | U+ABF0 to U+ABF9 |
mymr | U+1040 to U+1049 |
mymrshan | U+1090 to U+1099 |
mymrtlng | U+A9F0 to U+A9F9 |
nagm | U+1E4F0 to U+1E4F9 |
newa | U+11450 to U+11459 |
nkoo | U+07C0 to U+07C9 |
olck | U+1C50 to U+1C59 |
orya | U+0B66 to U+0B6F |
osma | U+104A0 to U+104A9 |
rohg | U+10D30 to U+10D39 |
saur | U+A8D0 to U+A8D9 |
segment | U+1FBF0 to U+1FBF9 |
shrd | U+111D0 to U+111D9 |
sind | U+112F0 to U+112F9 |
sinh | U+0DE6 to U+0DEF |
sora | U+110F0 to U+110F9 |
sund | U+1BB0 to U+1BB9 |
takr | U+116C0 to U+116C9 |
talu | U+19D0 to U+19D9 |
tamldec | U+0BE6 to U+0BEF |
telu | U+0C66 to U+0C6F |
thai | U+0E50 to U+0E59 |
tibt | U+0F20 to U+0F29 |
tirh | U+114D0 to U+114D9 |
tnsa | U+16AC0 to U+16AC9 |
vaii | U+A620 to U+A629 |
wara | U+118E0 to U+118E9 |
wcho | U+1E2F0 to U+1E2F9 |
The abstract operation FormatNumeric takes arguments numberFormat (an Intl.NumberFormat) and x (an
The abstract operation FormatNumericToParts takes arguments numberFormat (an Intl.NumberFormat) and x (an
The abstract operation ToRawPrecision takes arguments x (non-negative
It involves solving the following equation, which returns a valid
It performs the following steps when called:
The abstract operation ToRawFixed takes arguments x (non-negative
It involves solving the following equation, which returns a valid
It performs the following steps when called:
The abstract operation UnwrapNumberFormat takes argument nf (an
The abstract operation GetNumberFormatPattern takes arguments numberFormat (an Intl.NumberFormat) and x (an
The abstract operation GetNotationSubPattern takes arguments numberFormat (an Intl.NumberFormat) and exponent (an
The abstract operation ComputeExponent takes arguments numberFormat (an Intl.NumberFormat) and x (a
The abstract operation ComputeExponentForMagnitude takes arguments numberFormat (an Intl.NumberFormat) and magnitude (an
The
The conversion of a
It is defined piecewise over the following productions:
The abstract operation ToIntlMathematicalValue takes argument value (an
The abstract operation GetUnsignedRoundingMode takes arguments roundingMode (a String) and sign (
Identifier | Sign | Unsigned Rounding Mode |
---|---|---|
The abstract operation ApplyUnsignedRoundingMode takes arguments x (a
The abstract operation PartitionNumberRangePattern takes arguments numberFormat (an Intl.NumberFormat), x (an
The abstract operation FormatApproximately takes arguments numberFormat (an Intl.NumberFormat) and result (a
The
For example, an implementation may remove the
An implementation may also modify
Returning result unmodified is guaranteed to be a correct implementation of CollapseNumberRange.
The abstract operation FormatNumericRange takes arguments numberFormat (an Intl.NumberFormat), x (an
The abstract operation FormatNumericRangeToParts takes arguments numberFormat (an Intl.NumberFormat), x (an
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 [[AvailableLocales]] internal slot is
The value of the [[RelevantExtensionKeys]] internal slot is « ».
The value of the [[LocaleData]] internal slot is
The Intl.PluralRules prototype object is itself an
The initial value of Intl.PluralRules.prototype.constructor
is
The initial value of the
This property has the attributes { [[Writable]]:
When the select
method is called with an argument value, the following steps are taken:
When the selectRange
method is called with arguments start and end, the following steps are taken:
This function provides access to the locale and options computed during initialization of the object.
Internal Slot | Property | Conversion |
---|---|---|
[[Locale]] | ||
[[Type]] | ||
[[MinimumIntegerDigits]] | ||
[[MinimumFractionDigits]] | ||
[[MaximumFractionDigits]] | ||
[[MinimumSignificantDigits]] | ||
[[MaximumSignificantDigits]] | ||
[[RoundingIncrement]] | ||
[[RoundingMode]] | ||
[[ComputedRoundingPriority]] | ||
[[TrailingZeroDisplay]] |
Intl.PluralRules instances are
Intl.PluralRules instances have an [[InitializedPluralRules]] internal slot.
Intl.PluralRules instances also have several internal slots that are computed by the
The abstract operation GetOperands takes argument s (a decimal String) and returns a
Each Plural Rules Operands Record has the fields defined in
Field Name | Value Type | UTS #35 Operand | Description |
---|---|---|---|
[[Number]] | Number | n | Absolute value of the source number |
[[IntegerDigits]] | Number | i | |
[[FractionDigits]] | Number | f | Visible fraction digits in [[Number]], with trailing zeroes, as an |
[[NumberOfFractionDigits]] | Number | v | Number of visible fraction digits in [[Number]], with trailing zeroes. |
[[FractionDigitsWithoutTrailing]] | Number | t | Visible fraction digits in [[Number]], without trailing zeroes, as an |
[[NumberOfFractionDigitsWithoutTrailing]] | Number | w | Number of visible fraction digits in [[Number]], without trailing zeroes. |
The
The abstract operation ResolvePlural takes arguments pluralRules (an Intl.PluralRules) and n (a Number) and returns a
The
The abstract operation ResolvePluralRange takes arguments pluralRules (an Intl.PluralRules), x (a Number), and y (a Number) and returns either a
The RelativeTimeFormat
When the Intl.RelativeTimeFormat
function is called with optional arguments locales and options, the following steps are taken:
type
The Intl.RelativeTimeFormat
The value of Intl.RelativeTimeFormat.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 [[AvailableLocales]] internal slot is
The value of the [[RelevantExtensionKeys]] internal slot is «
The value of the [[LocaleData]] internal slot is
The Intl.RelativeTimeFormat prototype object is itself an
The initial value of Intl.RelativeTimeFormat.prototype.constructor
is
The initial value of the
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
Intl.RelativeTimeFormat instances have an [[InitializedRelativeTimeFormat]] internal slot.
Intl.RelativeTimeFormat instances also have several internal slots that are computed by the
The abstract operation SingularRelativeTimeUnit takes argument unit (a String) and returns either a
The abstract operation PartitionRelativeTimePattern takes arguments relativeTimeFormat (an Intl.RelativeTimeFormat), value (a Number), and unit (a String) and returns either a
The abstract operation MakePartsList takes arguments pattern (a
The abstract operation FormatRelativeTime takes arguments relativeTimeFormat (an Intl.RelativeTimeFormat), value (a Number), and unit (a String) and returns either a
The abstract operation FormatRelativeTimeToParts takes arguments relativeTimeFormat (an Intl.RelativeTimeFormat), value (a Number), and unit (a String) and returns either a
The Segmenter
When the Intl.Segmenter
function is called with optional arguments locales and options, the following steps are taken:
The Intl.Segmenter
The value of Intl.Segmenter.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 [[AvailableLocales]] internal slot is
The value of the [[RelevantExtensionKeys]] internal slot is « ».
The value of the [[LocaleData]] internal slot is
The Intl.Segmenter prototype object is itself an
The initial value of Intl.Segmenter.prototype.constructor
is
The initial value of the
This property has the attributes { [[Writable]]:
The Intl.Segmenter.prototype.segment
method is called on an Intl.Segmenter instance with argument string to create a
This function provides access to the locale and options computed during initialization of the object.
Internal Slot | Property |
---|---|
[[Locale]] | |
[[SegmenterGranularity]] |
Intl.Segmenter instances are
Intl.Segmenter instances have an [[InitializedSegmenter]] internal slot.
Intl.Segmenter instances also have internal slots that are computed by the
A Segments instance is an object that represents the segments of a specific string, subject to the locale and options of its constructing Intl.Segmenter instance.
The abstract operation CreateSegmentsObject takes arguments segmenter (an Intl.Segmenter) and string (a String) and returns a
The %IntlSegmentsPrototype% object:
The containing
method is called on a
The %Symbol.iterator%
method is called on a
Segments instances are
Segments instances have a [[SegmentsSegmenter]] internal slot that references the constructing Intl.Segmenter instance.
Segments instances have a [[SegmentsString]] internal slot that references the String value whose segments they expose.
A Segment Iterator is an object that represents a particular iteration over the segments of a specific string.
The abstract operation CreateSegmentIterator takes arguments segmenter (an Intl.Segmenter) and string (a String) and returns a
The %IntlSegmentIteratorPrototype% object:
The next
method is called on a
The initial value of the
This property has the attributes { [[Writable]]:
Internal Slot | Description |
---|---|
[[IteratingSegmenter]] | The Intl.Segmenter instance used for iteration. |
[[IteratedString]] | The String value being iterated upon. |
[[IteratedStringNextSegmentCodeUnitIndex]] | The code unit index in the String value being iterated upon at the start of the next segment. |
A Segment Data object is an object that represents a particular segment from a string.
The abstract operation CreateSegmentDataObject takes arguments segmenter (an Intl.Segmenter), string (a String), startIndex (a non-negative
"word"
, thenThe abstract operation FindBoundary takes arguments segmenter (an Intl.Segmenter), string (a String), startIndex (a non-negative
The ECMAScript Language Specification, edition 10 or successor, describes several locale-sensitive functions. An ECMAScript implementation that implements this specification shall implement these functions as described here.
This definition supersedes the definition provided in es2024,
When the localeCompare
method is called with argument that and optional arguments locales, and options, the following steps are taken:
The
localeCompare
method itself is not directly suitable as an argument to Array.prototype.sort
because the latter requires a function of two arguments.
localeCompare
function is intentionally generic; it does not require that its
This definition supersedes the definition provided in es2024,
This function interprets a String value as a sequence of code points, as described in es2024,
toLocaleLowerCase
function is intentionally generic; it does not require that its The abstract operation TransformCase takes arguments S (a String), locales (an
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-sensitive tailoring defined in the file SpecialCasing.txt
of the Unicode Character Database and/or CLDR and/or any other custom tailoring. Regardless of tailoring, a conforming implementation's case transformation algorithm must always yield the same result given the same input code points, locale, and target case.
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()
and s.toLocaleLowerCase().toLocaleUpperCase()
is not necessarily equal to s.toLocaleUpperCase()
.
This definition supersedes the definition provided in es2024,
This function interprets a String value as a sequence of code points, as described in es2024,
toLocaleUpperCase
function is intentionally generic; it does not require that its
The following definition(s) refer to the abstract operation thisNumberValue as defined in es2024,
This definition supersedes the definition provided in es2024,
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 thisBigIntValue as defined in es2024,
This definition supersedes the definition provided in es2024,
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 thisTimeValue as defined in es2024,
This definition supersedes the definition provided in es2024,
When the toLocaleString
method is called with optional arguments locales and options, the following steps are taken:
This definition supersedes the definition provided in es2024,
When the toLocaleDateString
method is called with optional arguments locales and options, the following steps are taken:
This definition supersedes the definition provided in es2024,
When the toLocaleTimeString
method is called with optional arguments locales and options, the following steps are taken:
This definition supersedes the definition provided in es2024,
When the toLocaleString
method is called with optional arguments locales and options, the following steps are taken:
toLocaleString
methods, and these Strings are then concatenated, separated by occurrences of an toString
except that it is intended to yield a locale-sensitive result corresponding with conventions of the toLocaleString
function is intentionally generic; it does not require that its The following aspects of this specification are implementation dependent:
Intl.Collator.prototype
was set to Intl.DateTimeFormat.prototype
was set to Intl.NumberFormat.prototype
was set to Intl.PluralRules.prototype
was set to Intl
was not defined. In 8th Edition, 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.
Ecma International
Rue du Rhone 114
CH-1204 Geneva
Tel: +41 22 849 6000
Fax: +41 22 849 6001
Web: https://ecma-international.org/
© 2024 Ecma International
This draft document may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to Ecma International, except as needed for the purpose of developing any document or deliverable produced by Ecma International.
This disclaimer is valid only prior to final version of this document. After approval all rights on the standard are reserved by Ecma International.
The limited permissions are granted through the standardization phase and will not be revoked by Ecma International or its successors or assigns during this time.
This document and the information contained herein is provided on an "AS IS" basis and ECMA INTERNATIONAL DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.