Stage 2 Draft / October 7, 2020

Intl Enumeration API Specification

Introduction

This proposal adds several function properties to the Intl Object to list supported values of options. See the README for more context.

1Identification of Locales, Currencies, Time Zones, and Measurement Units, Numbering Systems, Collations, and Calendars

This clause describes the String values used in the ECMAScript 2021 Internationalization API Specification to identify locales, currencies, time zones, and measurement units, numbering systems, collations and calendars .

1.1Case Sensitivity and Case Mapping

The String values used to identify locales, currencies, and time zones are interpreted in a case-insensitive manner, treating the Unicode Basic Latin characters "A" to "Z" (U+0041 to U+005A) as equivalent to the corresponding Basic Latin characters "a" to "z" (U+0061 to U+007A). No other case folding equivalences are applied. When mapping to upper case, a mapping shall be used that maps characters in the range "a" to "z" (U+0061 to U+007A) to the corresponding characters in the range "A" to "Z" (U+0041 to U+005A) and maps no other characters to the latter range.

EXAMPLES "ß" (U+00DF) must not match or be mapped to "SS" (U+0053, U+0053). "ı" (U+0131) must not match or be mapped to "I" (U+0049).

1.2Language Tags

The ECMAScript 2021 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.

1.2.1Unicode Locale Extension Sequences

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 "-" and the singleton "u", and includes the maximum sequence of following non-singleton subtags and their preceding "-" separators.

1.2.2IsStructurallyValidLanguageTag ( locale )

The IsStructurallyValidLanguageTag abstract operation verifies that the locale argument (which must be a String value)

  • represents a well-formed "Unicode BCP 47 locale identifier" as specified in Unicode Technical Standard 35 section 3.2,
  • does not include duplicate variant subtags, and
  • does not include duplicate singleton subtags.

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.

1.2.3CanonicalizeUnicodeLocaleId ( locale )

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 IsStructurallyValidLanguageTag abstract operation). The following steps are taken:

  1. Let localeId be the string locale after performing the algorithm to transform it to canonical syntax per Unicode Technical Standard #35 LDML § 3.2.1 Canonical Unicode Locale Identifiers. (The result is a Unicode BCP 47 locale identifier, in canonical syntax but not necessarily in canonical form.)
  2. Let localeId be the string localeId after performing the algorithm to transform it to canonical form. (The result is a Unicode BCP 47 locale identifier, in both canonical syntax and canonical form.)
  3. If localeId contains a substring extension that is a Unicode locale extension sequence, then
    1. Let components be ! UnicodeExtensionComponents(extension).
    2. Let attributes be components.[[Attributes]].
    3. Let keywords be components.[[Keywords]].
    4. Let newExtension be "u".
    5. For each element attr of attributes in List order, do
      1. Append "-" to newExtension.
      2. Append attr to newExtension.
    6. For each element keyword of keywords in List order, do
      1. Append "-" to newExtension.
      2. Append keyword.[[Key]] to newExtension.
      3. If keyword.[[Value]] is not the empty String, then
        1. Append "-" to newExtension.
        2. Append keyword.[[Value]] to newExtension.
    7. Assert: newExtension is not equal to "u".
    8. Let localeId be localeId with the substring corresponding to extension replaced by the string newExtension.
  4. Return localeId.
Note
The third step of this algorithm ensures that a Unicode locale extension sequence in the returned language tag contains:
  • only the first instance of any attribute duplicated in the input, and
  • only the first keyword for a given key in the input.

1.2.4DefaultLocale ()

The DefaultLocale abstract operation returns a String value representing the structurally valid (1.2.2) and canonicalized (1.2.3) Unicode BCP 47 locale identifier for the host environment's current locale.

1.3Currency Codes

The ECMAScript 2021 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.

1.3.1IsWellFormedCurrencyCode ( currency )

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:

  1. Let normalized be the result of mapping currency to upper case as described in 1.1.
  2. If the number of elements in normalized is not 3, return false.
  3. If normalized contains any character that is not in the range "A" to "Z" (U+0041 to U+005A), return false.
  4. Return true.

1.3.2AvailableCurrencies ( )

The AvailableCurrencies abstract operation return a List that contains well-formed 3-letter ISO 4217 currency codes identifying the currency for which the implementation provides the functionality of the constructed objects.

1.4Time Zone Names

The ECMAScript 2021 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.

1.4.1IsValidTimeZoneName ( timeZone )

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 1.1, is equal to one of the Zone or Link names of the IANA Time Zone Database, converted to upper case as described in 1.1. It returns false otherwise.

1.4.2CanonicalizeTimeZoneName

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 IsValidTimeZoneName abstract operation). The following steps are taken:

  1. Let ianaTimeZone be the Zone or Link name of the IANA Time Zone Database such that timeZone, converted to upper case as described in 1.1, is equal to ianaTimeZone, converted to upper case as described in 1.1.
  2. If ianaTimeZone is a Link name, let ianaTimeZone be the corresponding Zone name as specified in the "backward" file of the IANA Time Zone Database.
  3. If ianaTimeZone is "Etc/UTC" or "Etc/GMT", return "UTC".
  4. Return ianaTimeZone.

The Intl.DateTimeFormat constructor allows this time zone name; if the time zone is not specified, the host environment's current time zone is used. Implementations shall support UTC and the host environment's current time zone (if different from UTC) in formatting.

1.4.3DefaultTimeZone ()

The DefaultTimeZone abstract operation returns a String value representing the valid (1.4.1) and canonicalized (1.4.2) time zone name for the host environment's current time zone.

1.4.4AvailableTimeZones ( region )

The AvailableTimeZones abstract operation return a List that contains the canonical and case-regularized form of all registered Zone and Link names in the IANA Time Zone Database which are used in the region. If the region is undefined, then it return all the names.

1.5Measurement Unit Identifiers

The ECMAScript 2021 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.

1.5.1IsWellFormedUnitIdentifier ( unitIdentifier )

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:

  1. If the result of IsSanctionedSimpleUnitIdentifier(unitIdentifier) is true, then
    1. Return true.
  2. If the substring "-per-" does not occur exactly once in unitIdentifier, then
    1. Return false.
  3. Let numerator be the substring of unitIdentifier from the beginning to just before "-per-".
  4. If the result of IsSanctionedSimpleUnitIdentifier(numerator) is false, then
    1. Return false.
  5. Let denominator be the substring of unitIdentifier from just after "-per-" to the end.
  6. If the result of IsSanctionedSimpleUnitIdentifier(denominator) is false, then
    1. Return false.
  7. Return true.

1.5.2IsSanctionedSimpleUnitIdentifier ( unitIdentifier )

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:

  1. If unitIdentifier is listed in Table 1 below, return true.
  2. Else, Return false.
Table 1: Simple units sanctioned for use in ECMAScript
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

1.5.3AvailableUnits ( )

The AvailableUnits abstract operation return a List that contains the values of simple unit identifiers listed in every rows of Table 1, except the header row.

1.6Numbering System Identifiers

The ECMAScript 2021 Internationalization API Specification identifies numbering system using a numbering system identifier as defined by Unicode Technical Standard #35, Part 3, Section 1. Their canonical form is a string containing all lowercase letters.

1.6.1AvailableNumberingSystems ( )

The AvailableNumberingSystems abstract operation return a List that contains numbering system identifiers identifying the numbering system for which the implementation provides the functionality of the constructed objects. The list must includes the Numbering System value of every rows of Table 4, except the header row.

1.7Collation Types

The ECMAScript 2021 Internationalization API Specification identifies collation using a collation type as defined by Unicode Technical Standard #35, Part 5, Section 3.1. Their canonical form is a string containing all lowercase letters with zero or more hyphens.

1.7.1AvailableCalendars ( )

The AvailableCollations abstract operation return a List that contains collation types identifying the collation for which the implementation provides the functionality of the constructed objects.

1.8Calendar Types

The ECMAScript 2021 Internationalization API Specification identifies calendar using a calendar type as defined by Unicode Technical Standard #35, Part 4, Section 2. Their canonical form is a string containing all lowercase letters with zero or more hyphens.

1.8.1AvailableCalendars ( )

The AvailableCalendars abstract operation return a List that contains calendar types identifying the calendar for which the implementation provides the functionality of the constructed objects. The list must includes "gregory".

2The Intl Object

The Intl object is the %Intl% intrinsic object and the initial value of the "Intl" property of the global object. The Intl object is a single ordinary object.

The value of the [[Prototype]] internal slot of the Intl object is the intrinsic object %ObjectPrototype%.

The Intl object is not a function object. It does not have a [[Construct]] internal method; it is not possible to use the Intl object as a constructor with the 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 %Symbol% in the current realm with the [[Description]] "IntlLegacyConstructedSymbol".

2.1Constructor Properties of the Intl Object

2.1.1Intl.Locale (...)

See 10.

2.1.2Intl.Collator (...)

See 11.

2.1.3Intl.NumberFormat (...)

See 12.

2.1.4Intl.DateTimeFormat (...)

See 13.

2.1.5Intl.RelativeTimeFormat (...)

See 14.

2.1.6Intl.PluralRules (...)

See 15.

Note
In ECMA 402 v1, Intl constructors supported a mode of operation where calling them with an existing object as a receiver would transform the receiver into the relevant Intl instance with all internal slots. In ECMA 402 v2, this capability was removed, to avoid adding internal slots on existing objects. In ECMA 402 v3, the capability was re-added as "normative optional" in a mode which chains the underlying Intl instance on any object, when the constructor is called. See Issue 57 for details.

2.2Function Properties of the Intl Object

2.2.1Intl.getCanonicalLocales ( locales )

When the getCanonicalLocales method is called with argument locales, the following steps are taken:

  1. Let ll be ? CanonicalizeLocaleList(locales).
  2. Return CreateArrayFromList(ll).

2.2.2Intl.supportedValuesOf ( key [ , options ])

When the supportedValuesOf method is called with argument key and optional argument options , the following steps are taken:

  1. Let key be ? ToString(key).
  2. If options is undefined, then
    1. Let options be ! OrdinaryObjectCreate(null).
  3. Else
    1. Let options be ? ToObject(options).
  4. If key is "calendar", then
    1. Let list be ! AvailableCalendars( ).
  5. Else if key is "collation", then
    1. Let list be ! AvailableCollations( ).
  6. Else if key is "currency", then
    1. Let list be ! AvailableCurrencies( ).
  7. Else if key is "numberingSystem", then
    1. Let list be ! AvailableNumberingSystems( ).
  8. Else if key is "timeZone", then
    1. Let region be ? GetOption(options, "region", "string", undefined, undefined).
    2. Let list be ! AvailableTimeZones( region ).
  9. Else if key is "unit", then
    1. Let list be ! AvailableUnits( ).
  10. Else,
    1. Throw a RangeError exception.
  11. Return ! CreateSupportedValuesObject( list )

2.3Supported Values Objects

A Supported Values instance is an object that represents the results of the supported values of a given key.

2.3.1CreateSupportedValuesObject ( list )

The CreateSupportedValuesObject abstract operation is called with argument List instance list to create a Supported Values instance. The following steps are taken:

  1. Let internalSlotsList be « [[List]] ».
  2. Let values be ! OrdinaryObjectCreate(%SupportedValues.prototype%, internalSlotsList).
  3. Set values.[[List]] to list.
  4. Return values.

2.3.2The %SupportedValues.prototype% Object

The %SupportedValues.prototype% object:

  • is the prototype of all Supported Values objects.
  • is an ordinary object.
  • has the following properties:

2.3.2.1%SupportedValues.prototype% [ @@iterator ] ()

The @@iterator method is called on a Supported Values instance to create a Iterator over its values. The following steps are taken:

  1. Let values be the this value.
  2. Perform ? RequireInternalSlot(values, [[List]]).
  3. Let list be values.[[List]].
  4. Return ! CreateListIteratorRecord(list).

2.3.2.2Properties of Supported Values Instances

Supported Values instances are ordinary objects that inherit properties from %SupportedValues.prototype%.

Supported Values instances have a [[List]] internal slot that references a list of String.

ACopyright & Software License

Copyright Notice

© 2020 Google, Ecma International

Software License

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:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission.

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.