Stage 3 Draft / July 13, 2020

Intl.DisplayNames Proposal

1DisplayNames Objects

For motivation and a high-level introduction, see the explainer document.

This proposal is intended to provide translation for strings of particular items which are application-independent, rather than translation for all kinds of strings. There are two classes of strings we're considering here:

For example, for language/region names, W3C recommends users to use a locale selector when handling multilingual content, and currently that means shipping a long list of translated language/region names with every such website.

Such data may potentially be time and politically sensitive and is unlikely to be specific to any particular website (i.e., it's unlikely that website A will want a different translation of any language name from website B).

For that reason, providing this data in the engine lowers the cost of shipping multilingual websites with locale selectors and move the responsibility for keeping the mapping of BCP47 language/region codes to display names with the engine which is in a better position to keep it up to date.

The set of strings included may grow over time, but we expect to restrict the growth according to pragmatic requirements, including:

Additional strings included in Intl.DisplayNames should be added to the specification through a future ECMA-402 proposal, to be presented in the ECMA-402 Task Group and TC39 as part of its standardization through TC39 processes.

1.1Abstract Operations for DisplayNames Objects

1.1.1CanonicalCodeForDisplayNames ( type, code )

The CanonicalCodeForDisplayNames abstract operation is called with arguments type, and 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. Assert: type is "currency"
  5. If ! IsWellFormedCurrencyCode(code) is false, throw a RangeError exceptipon.
  6. Let code be the result of mapping code to upper case as described in 6.1.
  7. Return code.

1.2The Intl.DisplayNames Constructor

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

1.2.1Intl.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]], [[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" », 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.3.3).
  22. Let typeFields be types.[[<type>]].
  23. Assert: typeFields is a Record (see 1.3.3).
  24. Let styleFields be typeFields.[[<style>]].
  25. Assert: styleFields is a Record (see 1.3.3).
  26. Set displayNames.[[Fields]] to styleFields.
  27. Return displayNames.

1.3Properties of the Intl.DisplayNames Constructor

The Intl.DisplayNames constructor has the following properties:

1.3.1Intl.DisplayNames.prototype

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

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

1.3.2Intl.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.3.3Internal 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".
  • The value of fields "language", "region", "script", and "currency" must be a Records 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.
Note
It is recommended that implementations use the locale data provided by the Common Locale Data Repository (available at http://cldr.unicode.org/).

1.4Properties 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.4.1Intl.DisplayNames.prototype.constructor

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

1.4.2Intl.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.4.3Intl.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.4.4Intl.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 1, 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 1: Resolved Options of DisplayNames Instances
Internal Slot Property
[[Locale]] "locale"
[[Style]] "style"
[[Type]] "type"
[[Fallback]] "fallback"

1.5Properties 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", 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.
  • [[Fields]] is a Record (see 1.3.3) which must have fields with keys corresponding to codes according to [[Style]] and [[Type]].

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.