Stage 3 Draft / December 2, 2021

Intl.DisplayNames v2 Proposal

Introduction

This proposal enhances the Intl.DisplayNames API and cover more display names for weekday, month, time zone, unit, calendar, numbering system, etc. See the README for more context.

1 DisplayNames Objects

1.1 Abstract Operations for DisplayNames Objects

1.1.1 CanonicalCodeForDisplayNames ( type, code)

The CanonicalCodeForDisplayNames abstract operation is called with arguments type, code. It verifies that the code argument represents a well-formed code according to the type argument and returns the case-regularized form of the code. The algorithm refers to UTS 35's Unicode Language and Locale Identifiers grammar. The following steps are taken:

  1. If type is "language", then
    1. If code does not matches the unicode_language_id production, throw a RangeError exceptipon.
    2. If IsStructurallyValidLanguageTag(code) is false, throw a RangeError exception.
    3. Set code to CanonicalizeUnicodeLocaleId(code).
    4. Return code.
  2. If type is "region", then
    1. If code does not matches the unicode_region_subtag production, throw a RangeError exceptipon.
    2. Let code be the result of mapping code to upper case as described in 6.1.
    3. Return code.
  3. If type is "script", then
    1. If code does not matches the unicode_script_subtag production, throw a RangeError exceptipon.
    2. Let code be the result of mapping the first character in code to upper case, and mapping the second, third and fourth character in code to lower case, as described in 6.1.
    3. Return code.
  4. If type is "calendar", then
    1. If code does not match the Unicode Locale Identifier type nonterminal, throw a RangeError exception.
    2. Let code be the result of mapping code to lower case as described in 6.1.
    3. Return code.
  5. If type is "dateTimeField", then
    1. If the result of IsValidDateTimeFieldCode(code) is false, throw a RangeError exception.
    2. Return code.
  6. Assert: type is "currency".
  7. If ! IsWellFormedCurrencyCode(code) is false, throw a RangeError exceptipon.
  8. Let code be the result of mapping code to upper case as described in 6.1.
  9. Return code.

1.2 IsValidDateTimeFieldCode ( field )

The IsValidDateTimeFieldCode abstract operation is called with argument field. It verifies that the field argument represents a valid date time field code. The following steps are taken:

  1. If field is listed in the Code column of Table 1, return true.
  2. Return false.
Table 1: Codes For Date Time Field of DisplayNames
Code Description
"era" The field indicating the era, e.g. AD or BC in the Gregorian (Julian) calendar.
"year" The field indicating the year.
"quarter" The field indicating the quarter, e.g. Q2, 2nd quarter, etc.
"month" The field indicating the month, e.g. Sep, September, etc.
"weekOfYear" The field indicating the week number within the current year.
"weekday" The field indicating the day of week, e.g. Tue, Tuesday, etc.
"day" The field indicating the day in month.
"dayPeriod" The field indicating the day period, either am/pm marker or others, e.g. noon, evening.
"hour" The field indicating the hour.
"minute" The field indicating the minute.
"second" The field indicating the second.
"timeZoneName" The field indicating the time zone name, e.g. PDT, Pacific Daylight Time, etc.

1.3 The Intl.DisplayNames Constructor

The DisplayNames constructor is a standard built-in property of the Intl object.

1.3.1 Intl.DisplayNames ( locales, options )

When the Intl.DisplayNames function is called with arguments locales and options, the following steps are taken:

  1. If NewTarget is undefined, throw a TypeError exception.
  2. Let displayNames be ? OrdinaryCreateFromConstructor(NewTarget, "%DisplayNamesPrototype%", « [[InitializedDisplayNames]], [[Locale]], [[Style]], [[Type]], [[Fallback]], [[LanguageDisplay]], [[Fields]] »).
  3. Let requestedLocales be ? CanonicalizeLocaleList(locales).
  4. Let options be ? ToObject(options).
  5. Let opt be a new Record.
  6. Let localeData be %DisplayNames%.[[LocaleData]].
  7. Let matcher be ? GetOption(options, "localeMatcher", "string", « "lookup", "best fit" », "best fit").
  8. Set opt.[[localeMatcher]] to matcher.
  9. Let r be ResolveLocale(%DisplayNames%.[[AvailableLocales]], requestedLocales, opt, %DisplayNames%.[[RelevantExtensionKeys]]).
  10. Let style be ? GetOption(options, "style", "string", « "narrow", "short", "long" », "long").
  11. Set displayNames.[[Style]] to style.
  12. Let type be ? GetOption(options, "type", "string", « "language", "region", "script", "currency" , "calendar", "dateTimeField"», undefined).
  13. If type is undefined, throw a TypeError exception.
  14. Set displayNames.[[Type]] to type.
  15. Let fallback be ? GetOption(options, "fallback", "string", « "code", "none" », "code").
  16. Set displayNames.[[Fallback]] to fallback.
  17. Set displayNames.[[Locale]] to the value of r.[[Locale]].
  18. Let dataLocale be r.[[dataLocale]].
  19. Let dataLocaleData be localeData.[[<dataLocale>]].
  20. Let types be dataLocaleData.[[types]].
  21. Assert: types is a Record (see 1.4.3).
  22. Let typeFields be types.[[<type>]].
  23. Assert: typeFields is a Record (see 1.4.3).
  24. Let languageDisplay be ? GetOption(options, "languageDisplay", "string", « "dialect", "standard" », "dialect").
  25. If type is "language", then
    1. Set displayNames.[[LanguageDisplay]] to languageDisplay.
    2. Let typeFields be typeFields.[[<languageDisplay>]].
    3. Assert: typeFields is a Record (see 1.4.3).
  26. Let styleFields be typeFields.[[<style>]].
  27. Assert: styleFields is a Record (see 1.4.3).
  28. Set displayNames.[[Fields]] to styleFields.
  29. Return displayNames.

1.4 Properties of the Intl.DisplayNames Constructor

The Intl.DisplayNames constructor has the following properties:

1.4.1 Intl.DisplayNames.prototype

The value of Intl.DisplayNames.prototype is %DisplayNamesPrototype%.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

1.4.2 Intl.DisplayNames.supportedLocalesOf ( locales [ , options ] )

When the supportedLocalesOf method of %DisplayNames% is called, the following steps are taken:

  1. Let availableLocales be %DisplayNames%.[[AvailableLocales]].
  2. Let requestedLocales be ? CanonicalizeLocaleList(locales).
  3. Return ? SupportedLocales(availableLocales, requestedLocales, options).

1.4.3 Internal slots

The value of the [[AvailableLocales]] internal slot is implementation defined within the constraints described in 9.1.

The value of the [[RelevantExtensionKeys]] internal slot is « ».

The value of the [[LocaleData]] internal slot is implementation defined within the constraints described in 9.1 and the following additional constraints:

  • [[LocaleData]].[[<locale>]] must have a [[types]] field for all locale values locale. The value of this field must be a Record, which must have fields with the names of one of the valid display name types: "language", "region", "script", and "currency", "calendar", and "dateTimeField".
  • The value of the field "language" must be a Record which must have fields with the names of one of the valid language displays: "dialect" and "standard".
  • The language display fields under display name type "language" should contain Records which must have fields with the names of one of the valid display name styles: "narrow", "short", and "long".
  • The value of fields "language", "region", "script", and "currency", "calendar", and "dateTimeField" must be a Record which must have fields with the names of one of the valid display name styles: "narrow", "short", and "long".
  • The display name styles fields under display name type "language" should contain Records, with keys corresponding to language codes according to unicode_language_id production. The value of these fields must be string values.
  • The display name styles fields under display name type "region" should contain Records, with keys corresponding to region codes. The value of these fields must be string values.
  • The display name styles fields under display name type "script" should contain Records, with keys corresponding to script codes. The value of these fields must be string values.
  • The display name styles fields under display name type "currency" should contain Records, with keys corresponding to currency codes. The value of these fields must be string values.
  • The display name styles fields under display name type "calendar" should contain Records, with keys corresponding to a String value with the type given in Unicode Technical Standard 35 for the calendar used for formatting. The value of these fields must be string values.
  • The display name styles fields under display name type "dateTimeField" should contain Records, with keys corresponding to codes listed in Table 1. The value of these fields must be string values.
Note
It is recommended that implementations use the locale data provided by the Common Locale Data Repository (available at http://cldr.unicode.org/).

1.5 Properties of the Intl.DisplayNames Prototype Object

The Intl.DisplayNames prototype object, referred to as %DisplayNamesPrototype%, is itself an ordinary object. It is not a Intl.DisplayNames instance, does not have an [[InitializedDisplayNames]] internal slot or any of the other internal slots of Intl.DisplayNames instance objects.

1.5.1 Intl.DisplayNames.prototype.constructor

The initial value of Intl.DisplayNames.prototype.constructor is the intrinsic object %DisplayNames%.

1.5.2 Intl.DisplayNames.prototype[ @@toStringTag ]

The initial value of the @@toStringTag property is the string value "Intl.DisplayNames".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

1.5.3 Intl.DisplayNames.prototype.of ( code )

When the Intl.DisplayNames.prototype.of is called with an argument code, the following steps are taken:

  1. Let displayNames be this value.
  2. If Type(displayNames) is not Object, throw a TypeError exception.
  3. If displayNames does not have an [[InitializedDisplayNames]] internal slot, throw a TypeError exception.
  4. Let code be ? ToString(code).
  5. Let code be ? CanonicalCodeForDisplayNames(displayNames.[[Type]], code).
  6. Let fields be displayNames.[[Fields]].
  7. Let name be fields[[<code>]].
  8. If name is not undefined, return name.
  9. If displayNames.[[Fallback]] is "code", return code.
  10. Return undefined.

1.5.4 Intl.DisplayNames.prototype.resolvedOptions ( )

This function provides access to the locale and options computed during initialization of the object.

  1. Let displayNames be this value.
  2. If Type(displayNames) is not Object, throw a TypeError exception.
  3. If displayNames does not have an [[InitializedDisplayNames]] internal slot, throw a TypeError exception.
  4. Let options be ! ObjectCreate(%ObjectPrototype%).
  5. For each row of Table 2, except the header row, in table order, do
    1. Let p be the Property value of the current row.
    2. Let v be the value of displayNames's internal slot whose name is the Internal Slot value of the current row.
    3. If v is not undefined, then
      1. Perform ! CreateDataPropertyOrThrow(options, p, v).
  6. Return options.
Table 2: Resolved Options of DisplayNames Instances
Internal Slot Property
[[Locale]] "locale"
[[Style]] "style"
[[Type]] "type"
[[Fallback]] "fallback"
[[LanguageDisplay]] "languageDisplay"

1.6 Properties of Intl.DisplayNames Instances

Intl.DisplayNames instances are ordinary objects that inherit properties from %DisplayNamesPrototype%.

Intl.DisplayNames instances have an [[InitializedDisplayNames]] internal slot.

Intl.DisplayNames instances also have several internal slots that are computed by the constructor:

  • [[Locale]] is a String value with the language tag of the locale whose localization is used for formatting.
  • [[Style]] is one of the String values "narrow", "short", or "long", identifying the display names style used.
  • [[Type]] is one of the String values "language", "region", "script", or "currency", "calendar", or "dateTimeField", identifying the type of the display names requested.
  • [[Fallback]] is one of the String values "code", or "none", identifying the fallback return when the system does not have the requested display name.
  • [[LanguageDisplay]] is one of the String values "dialect" or "standard", identifying the language display kind. It is only used when [[Type]] has the value "language".
  • [[Fields]] is a Record (see 1.4.3) which must have fields with keys corresponding to codes according to [[Style]] and, [[Type]], and [[LanguageDisplay]].

A Copyright & Software License

Copyright Notice

© 2021 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.