├── .github
└── main.workflow
├── LICENSE
├── README.md
├── biblio.json
├── deploy.sh
├── index.html
├── index_old.html
├── package.json
├── spec.emu
└── spec_old.emu
/.github/main.workflow:
--------------------------------------------------------------------------------
1 | workflow "publish on release" {
2 | on = "push"
3 | resolves = ["publish"]
4 | }
5 |
6 | action "publish" {
7 | uses = "actions/npm@master"
8 | args = "publish"
9 | secrets = ["NPM_AUTH_TOKEN"]
10 | }
11 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2017 ECMA TC39 and contributors
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | ## Proposal: Intl.DisplayNames
2 |
3 | ### Stage
4 | Stage 4
5 | * [Advanced into Stage 4 in TC39 2020-09-21 meeting](https://docs.google.com/presentation/d/1SicCmt1bo4jyMTvAUiumCBW2ZqUh_-a18xrTO9nqG7U/edit#slide=id.p).
6 | * Advanced into Stage 3 in TC39 2019-10-2.
7 | * Advanced into Stage 2 in TC39 2019-6-5.
8 | * Advanced into Stage 1 in TC39 2019-1-31.
9 | * Discussed within ECMA402 members since July 2017.
10 |
11 | For additional Feature Requests- please fire issues under the new [v2 repo](https://github.com/FrankYFTang/intl-displaynames-v2/)
12 |
13 | ### Motivation
14 | Main motivation for Intl.DisplayNames project was to enable developers to get translation of language, region or script display names on the client. Translation of languages, regions or script display names requires large amount of data to transmit on the network, which is already available in most browsers. These display name translations also carry steep data size penalty for developers. This API will allow web developers to shrink the size of their HTML and/ or ECMA script code without the need to include the human readble form of display names and therefore reduce the download size to decrease latency. Also, this API will reduce the localization cost for the web developers. Our goal is to expose this data through Intl API for use in e.g. language, region and script pickers, etc.
15 |
16 | ### Benefit
17 | * Reduce download size of apps and therefore improve latency.
18 | * Easy for users to build internationalized language, region or script selection UI components (drop down menu or other kinds).
19 | * Reduce translation cost for developers.
20 | * Consistent translation of language, region and script display name on the web.
21 |
22 | ### Scope
23 | 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:
24 |
25 | - Strings that are already available because they're needed for other APIs. For example, names for the days of the week are necessary to provide Intl.DateTimeFormat capabilities. In the absence of a direct API, we see programs parsing the output of Intl.DateTimeFormat to find these names, which is an unreliable/unstable technique.
26 | - Strings that are universally standardized and are likely necessary for any multilingual JavaScript application. For example language/region names.
27 |
28 | 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.
29 | 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).
30 | 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.
31 |
32 | The set of strings included may grow over time, but we expect to restrict the growth according to pragmatic requirements, including:
33 | - Strings which are included should be generically useful across multiple application types.
34 | - The inclusion of strings should not be too much of a burden on implementations in terms of data size.
35 | - There should be an open data source that implementations can use for the string values, e.g., CLDR.
36 | - Strings that rarely (never) change, and thus don't need to be dynamically
37 | generated.
38 | - Sets of strings that have so few items that it's more of a burden to expose
39 | Web API and maintain it forever than it would be for a website to just include
40 | those strings directly.
41 |
42 | 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.
43 |
44 | ### Syntax
45 | To get localized names of language, script or region, create a Intl.DisplayName object and call the method by passing in appropriate standard code.
46 |
47 | The parameter for Intl.DisplayNames constructor follow other Intl Objects in ECMA402 Standard.
48 | The first parameter is *locales*, which is either a BCP 47 language tag or an array of such language tags ([more information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_identification_and_negotiation)); the second parameter is an option Object.
49 |
50 | ```js
51 | Intl.DisplayNames( locales , options)
52 | Intl.DisplayNames.prototype.of( code )
53 | ```
54 | * _options_ need to have "type" properties.
55 | * The value of _type_ could be either "region", "script", "language", or "currency".
56 | * _options_ may have "localeMatcher", "style", and "fallback" properties.
57 | * The value of _style_ could be either "narrow", "short" or "long" to indicate the length of the display names. For example, for type of "language", of("en-US") will return "English (United States)" under "long" style, but "English (US)" under "short" style. The default is "long".
58 | * _code_ is a String.
59 | * Intl.DisplayNames.prototype.of( code ) function take a String as input and return a String, the display name of the _code_.
60 | * If the type is "region", the _code_ should be either an [ISO-3166 two letters region code](https://www.iso.org/iso-3166-country-codes.html),
61 | or a [three digits UN M49 Geographic Regions](https://unstats.un.org/unsd/methodology/m49/).
62 | * If the type is "script", the _code_ should be an [ISO-15924 four letters script code](http://unicode.org/iso15924/iso15924-codes.html).
63 | * If the type is "language", the _code_ should be a _languageCode_ ["-" _scriptCode_] ["-" _regionCode_ ] *("-" _variant_ ) subsequence of the unicode_language_id grammar in [UTS 35's Unicode Language and Locale Identifiers grammar](http://unicode.org/reports/tr35/#Unicode_language_identifier). _languageCode_ is either a two letters ISO 639-1 language code or a three letters ISO 639-2 language code.
64 | * If the type is "currency", the _code_ should be a [3-letter ISO 4217 currency code](https://www.iso.org/iso-4217-currency-codes.html).
65 |
66 | ### Authors
67 | * Frank Tang (@FrankYFTang)
68 | * Zibi Braniecki (@zbraniecki)
69 | * Sascha Brawer (@brawer)
70 | * Nebojša Ćirić (@nciric)
71 |
72 | ### Stage 3 Reviewers
73 | * Reviewers
74 | * Daniel Ehrenberg (@littledan)
75 | * Bradley Farias (@mbeck)
76 | * Editors
77 | * Jordan Harband (@ljharb)
78 | * Kevin Smith (@zenparsing)
79 |
80 | ### Prior art
81 | Mozilla already has [vendor specific implementation](https://firefox-source-docs.mozilla.org/intl/dataintl.html#mozintl-getlanguagedisplaynames-locales-langcodes).
82 |
83 | ### Usage
84 | #### Region Code Display Names
85 | To create an Intl.DisplayNames for a locale and get the display name for a
86 | region code.
87 | ```js
88 | // Get display names of region in English
89 | var regionNames = new Intl.DisplayNames(['en'], {type: 'region'});
90 | console.log(regionNames.of('419')); // "Latin America"
91 | console.log(regionNames.of('BZ')); // "Belize"
92 | console.log(regionNames.of('US')); // "United States"
93 | console.log(regionNames.of('BA')); // "Bosnia & Herzegovina"
94 | console.log(regionNames.of('MM')); // "Myanmar (Burma)"
95 |
96 | // Get display names of region in Traditional Chinese
97 | regionNames = new Intl.DisplayNames(['zh-Hant'], {type: 'region'});
98 | console.log(regionNames.of('419')); // "拉丁美洲"
99 | console.log(regionNames.of('BZ')); // "貝里斯"
100 | console.log(regionNames.of('US')); // "美國"
101 | console.log(regionNames.of('BA')); // "波士尼亞與赫塞哥維納"
102 | console.log(regionNames.of('MM')); // "緬甸"
103 | ```
104 |
105 | #### Language Display Names
106 | To create an Intl.DisplayNames for a locale and get the display name for a
107 | language-script-region sequence.
108 | ```js
109 | // Get display names of language in English
110 | var languageNames = new Intl.DisplayNames(['en'], {type: 'language'});
111 | console.log(languageNames.of('fr')); // "French"
112 | console.log(languageNames.of('de')); // "German"
113 | console.log(languageNames.of('fr-CA')); // "Canadian French"
114 | console.log(languageNames.of('zh-Hant')); // "Traditional Chinese"
115 | console.log(languageNames.of('en-US')); // "American English"
116 | console.log(languageNames.of('zh-TW')); // "Chinese (Taiwan)"]
117 |
118 | // Get display names of language in Traditional Chinese
119 | languageNames = new Intl.DisplayNames(['zh-Hant'], {type: 'language'});
120 | console.log(languageNames.of('fr')); // "法文"
121 | console.log(languageNames.of('zh')); // "中文"
122 | console.log(languageNames.of('de')); // "德文"
123 | ```
124 |
125 | #### Script Code Display Names
126 | To create an Intl.DisplayNames for a locale and get the display name for
127 | a script code.
128 | ```js
129 | // Get display names of script in English
130 | var scriptNames = new Intl.DisplayNames(['en'], {type: 'script'});
131 | // Get script names
132 | console.log(scriptNames.of('Latn')); // "Latin"
133 | console.log(scriptNames.of('Arab')); // "Arabic"
134 | console.log(scriptNames.of('Kana')); // "Katakana"
135 |
136 | // Get display names of script in Traditional Chinese
137 | scriptNames = new Intl.DisplayNames(['zh-Hant'], {type: 'script'});
138 | console.log(scriptNames.of('Latn')); // "拉丁文"
139 | console.log(scriptNames.of('Arab')); // "阿拉伯文"
140 | console.log(scriptNames.of('Kana')); // "片假名"
141 | ```
142 | #### Currency Code Display Names
143 | To create an Intl.DisplayNames for a locale and get the display name for
144 | currency code.
145 | ```js
146 | // Get display names of currency code in English
147 | var currencyNames = new Intl.DisplayNames(['en'], {type: 'currency'});
148 | // Get currency names
149 | console.log(currencyNames.of('USD')); // "US Dollar"
150 | console.log(currencyNames.of('EUR')); // "Euro"
151 | console.log(currencyNames.of('TWD')); // "New Taiwan Dollar"
152 | console.log(currencyNames.of('CNY')); // "Chinese Yuan"
153 |
154 | // Get display names of currency code in Traditional Chinese
155 | currencyNames = new Intl.DisplayNames(['zh-Hant'], {type: 'currency'});
156 | console.log(currencyNames.of('USD')); // "美元"
157 | console.log(currencyNames.of('EUR')); // "歐元"
158 | console.log(currencyNames.of('TWD')); // "新台幣"
159 | console.log(currencyNames.of('CNY')); // "人民幣"
160 | ```
161 |
162 | ### Supporting Materials:
163 | * [Slide for promoting from Stage 0 to Stage 1 for TC39 2019 January meeting.](https://goo.gl/qzQK8A)
164 | * [Slide for promoting from Stage 1 to Stage 2 for TC39 2019 June meeting.](https://goo.gl/ZAaVds)
165 | * [Slide for promoting from Stage 2 to Stage 3 for TC39 2019 October meeting.](https://docs.google.com/presentation/d/1bq9h8BvP7a4_Tn3NM-DQ0QSlSr9uGZpmNSTFRRlCsV8/edit#slide=id.p)
166 | * [Slide for promoting from Stage 3 to Stage 4 for TC39 2020 September meeting.](https://docs.google.com/presentation/d/1SicCmt1bo4jyMTvAUiumCBW2ZqUh_-a18xrTO9nqG7U/edit#slide=id.p)
167 |
168 |
--------------------------------------------------------------------------------
/biblio.json:
--------------------------------------------------------------------------------
1 | {
2 | "https://tc39.github.io/ecma402/": [
3 | {
4 | "type": "op",
5 | "aoid": "GetOption",
6 | "id": "sec-getoption"
7 | },
8 | {
9 | "type": "op",
10 | "aoid": "ResolveLocale",
11 | "id": "sec-resolvelocale"
12 | },
13 | {
14 | "type": "op",
15 | "aoid": "IsWellFormedCurrencyCode",
16 | "id": "sec-iswellformedcurrencycode"
17 | },
18 | {
19 | "type": "op",
20 | "aoid": "CanonicalizeLocaleList",
21 | "id": "sec-canonicalizelocalelist"
22 | },
23 | {
24 | "type": "op",
25 | "aoid": "CanonicalizeUnicodeLocaleId",
26 | "id": "sec-canonicalizeunicodelocaleid"
27 | },
28 | {
29 | "type": "op",
30 | "aoid": "IsStructurallyValidLanguageTag",
31 | "id": "sec-isstructurallyvalidlanguagetag"
32 | },
33 | {
34 | "type": "op",
35 | "aoid": "SupportedLocales",
36 | "id": "sec-supportedlocales"
37 | },
38 | {
39 | "type": "clause",
40 | "number": "6.1",
41 | "id": "sec-case-sensitivity-and-case-mapping"
42 | },
43 | {
44 | "type": "clause",
45 | "number": "9.1",
46 | "id": "sec-internal-slots"
47 | }
48 | ]
49 | }
50 |
--------------------------------------------------------------------------------
/deploy.sh:
--------------------------------------------------------------------------------
1 | #!/bin/bash
2 |
3 | set -ev
4 |
5 | # Pull requests and commits to other branches shouldn't try to deploy, just build to verify
6 | if [[ "$TRAVIS_BRANCH" != master ]]; then
7 | echo "Skipping deploy; just doing a build."
8 | npm run build
9 | exit 0
10 | fi
11 |
12 | # Enable SSH authentication
13 |
14 | ENCRYPTED_KEY_VAR="encrypted_${ENCRYPTION_LABEL}_key"
15 | ENCRYPTED_IV_VAR="encrypted_${ENCRYPTION_LABEL}_iv"
16 | ENCRYPTED_KEY=${!ENCRYPTED_KEY_VAR}
17 | ENCRYPTED_IV=${!ENCRYPTED_IV_VAR}
18 |
19 | if [[ $ENCRYPTED_KEY == "" ]]; then
20 | echo "Auto-deploy GitHub key missing; exiting without a build"
21 | exit 0
22 | fi
23 |
24 | $(npm bin)/set-up-ssh --key "$ENCRYPTED_KEY" \
25 | --iv "$ENCRYPTED_IV" \
26 | --path-encrypted-key "$PRIVATE_KEY_FILE_NAME"
27 |
28 | # Update the content from the `gh-pages` branch
29 |
30 | $(npm bin)/update-branch --commands "mkdir out && ecmarkup spec/index.html out/index.html" \
31 | --commit-message "Update gh-pages [skip ci]" \
32 | --directory "out" \
33 | --distribution-branch "gh-pages" \
34 | --source-branch "master"
35 |
--------------------------------------------------------------------------------
/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 | Intl.DisplayNames Proposal
1813 | For motivation and a high-level introduction, see the explainer document.
1814 |
1815 |
1816 |
1817 | 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:
1818 |
1819 |
1820 |
1821 | Strings that are already available because they're needed for other APIs. For example, names for the days of the week are necessary to provide Intl.DateTimeFormat capabilities. In the absence of a direct API, we see programs parsing the output of Intl.DateTimeFormat to find these names, which is an unreliable/unstable technique.
1822 |
1823 |
1824 |
1825 | Strings that are universally standardized and are likely necessary for any multilingual JavaScript application. For example language/region names.
1826 |
1827 |
1828 |
1829 |
1830 |
1831 | 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.
1832 |
1833 |
1834 |
1835 | 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).
1836 |
1837 |
1838 |
1839 | 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.
1840 |
1841 |
1842 |
1843 | The set of strings included may grow over time, but we expect to restrict the growth according to pragmatic requirements, including:
1844 |
1845 |
1846 |
1847 | Strings which are included should be generically useful across multiple application types.
1848 |
1849 |
1850 |
1851 | The inclusion of strings should not be too much of a burden on implementations in terms of data size.
1852 |
1853 |
1854 |
1855 | There should be an open data source that implementations can use for the string values, e.g., CLDR.
1856 |
1857 |
1858 |
1859 | Strings that rarely (never) change, and thus don't need to be dynamically generated.
1860 |
1861 |
1862 |
1863 | Sets of strings that have so few items that it's more of a burden to expose Web API and maintain it forever than it would be for a website to just include those strings directly.
1864 |
1865 |
1866 |
1867 |
1868 |
1869 | 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.
1870 |
1871 |
1872 |
1873 |
1.1Abstract Operations for DisplayNames Objects
1874 |
1875 |
1876 |
1.1.1CanonicalCodeForDisplayNames ( type, code )
1877 |
1878 | 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:
1879 |
1880 |
1881 |
If type is "language", then
If code does not matches the unicode_language_id production, throw a RangeError exceptipon.
If code does not matches the unicode_region_subtag production, throw a RangeError exceptipon.
Let code be the result of mapping code to upper case as described in 6.1.
Return code.
If type is "script", then
If code does not matches the unicode_script_subtag production, throw a RangeError exceptipon.
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.
1944 | The value of the [[AvailableLocales]] internal slot is implementation defined within the constraints described in 9.1.
1945 |
1946 |
1947 |
1948 |
1949 | The value of the [[RelevantExtensionKeys]] internal slot is « ».
1950 |
1951 |
1952 |
1953 |
1954 | The value of the [[LocaleData]] internal slot is implementation defined within the constraints described in 9.1 and the following additional constraints:
1955 |
1956 |
1957 |
1958 |
1959 |
[[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".
1960 |
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".
1961 |
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.
1962 |
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.
1963 |
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.
1964 |
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.
1965 |
1966 |
1967 | Note
1968 | It is recommended that implementations use the locale data provided by the Common Locale Data Repository (available at http://cldr.unicode.org/).
1969 |
1970 |
1971 |
1972 |
1973 |
1974 |
1975 |
1976 |
1.4Properties of the Intl.DisplayNames Prototype Object
1977 |
1978 |
1979 | 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.
1980 |
1981 |
1982 |
1983 |
1984 |
1.4.1Intl.DisplayNames.prototype.constructor
1985 |
1986 |
1987 | The initial value of Intl.DisplayNames.prototype.constructor is the intrinsic object %DisplayNames%.
1988 |
1989 |
1990 |
1991 |
1992 |
1993 |
1.4.2Intl.DisplayNames.prototype[ @@toStringTag ]
1994 |
1995 |
1996 | The initial value of the @@toStringTag property is the string value "Intl.DisplayNames".
1997 |
1998 |
1999 |
2000 | This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.
2001 |
2002 |
2003 |
2004 |
2005 |
2006 |
1.4.3Intl.DisplayNames.prototype.of( code )
2007 |
2008 |
2009 | When the Intl.DisplayNames.prototype.of is called with an argument code, the following steps are taken:
2010 |
2011 |
2012 |
2013 |
Let displayNames be this value.
If Type(displayNames) is not Object, throw a TypeError exception.
If displayNames does not have an [[InitializedDisplayNames]] internal slot, throw a TypeError exception.
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.
2094 |
2095 |
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
2096 |
2097 |
2098 |
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2099 |
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.
2100 |
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.
2101 |
2102 |
2103 |
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.
21 | 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:
22 |
23 |
24 | Strings that are already available because they're needed for other APIs. For example, names for the days of the week are necessary to provide Intl.DateTimeFormat capabilities. In the absence of a direct API, we see programs parsing the output of Intl.DateTimeFormat to find these names, which is an unreliable/unstable technique.
25 |
26 |
27 | Strings that are universally standardized and are likely necessary for any multilingual JavaScript application. For example language/region names.
28 |
29 |
30 |
31 |
32 | 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.
33 |
34 |
35 | 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).
36 |
37 |
38 | 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.
39 |
40 |
41 | The set of strings included may grow over time, but we expect to restrict the growth according to pragmatic requirements, including:
42 |
43 |
44 | Strings which are included should be generically useful across multiple application types.
45 |
46 |
47 | The inclusion of strings should not be too much of a burden on implementations in terms of data size.
48 |
49 |
50 | There should be an open data source that implementations can use for the string values, e.g., CLDR.
51 |
52 |
53 | Strings that rarely (never) change, and thus don't need to be dynamically generated.
54 |
55 |
56 | Sets of strings that have so few items that it's more of a burden to expose Web API and maintain it forever than it would be for a website to just include those strings directly.
57 |
58 |
59 |
60 |
61 | 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.
62 |
63 |
64 |
Abstract Operations for DisplayNames Objects
65 |
66 |
67 |
CanonicalCodeForDisplayNames ( _type_, _code_ )
68 |
69 | 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:
70 |
71 |
72 | 1. If _type_ is `"language"`, then
73 | 1. If _code_ does not matches the `unicode_language_id` production, throw a *RangeError* exceptipon.
74 | 1. If IsStructurallyValidLanguageTag(_code_) is *false*, throw a *RangeError* exception.
75 | 1. Set _code_ to CanonicalizeUnicodeLocaleId(_code_).
76 | 1. Return _code_.
77 | 1. If _type_ is `"region"`, then
78 | 1. If _code_ does not matches the `unicode_region_subtag` production, throw a *RangeError* exceptipon.
79 | 1. Let _code_ be the result of mapping _code_ to upper case as described in .
80 | 1. Return _code_.
81 | 1. If _type_ is `"script"`, then
82 | 1. If _code_ does not matches the `unicode_script_subtag` production, throw a *RangeError* exceptipon.
83 | 1. 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 .
84 | 1. Return _code_.
85 | 1. Assert: _type_ is `"currency"`
86 | 1. If ! IsWellFormedCurrencyCode(_code_) is *false*, throw a *RangeError* exceptipon.
87 | 1. Let _code_ be the result of mapping _code_ to upper case as described in .
88 | 1. Return _code_.
89 |
90 |
91 |
92 |
93 |
94 |
95 |
The Intl.DisplayNames Constructor
96 |
97 |
98 | The DisplayNames constructor is a standard built-in property of the Intl object.
99 |
100 |
101 |
Intl.DisplayNames ( _locales_ , _options_ )
102 |
103 |
104 | When the *Intl.DisplayNames* function is called with arguments _locales_ and _options_, the following steps are taken:
105 |
106 |
107 |
108 | 1. If NewTarget is *undefined*, throw a *TypeError* exception.
109 | 1. Let _displayNames_ be ? OrdinaryCreateFromConstructor(NewTarget, `"%DisplayNamesPrototype%"`, « [[InitializedDisplayNames]], [[Locale]], [[Style]], [[Type]], [[Fallback]], [[Fields]] »).
110 | 1. Let _requestedLocales_ be ? CanonicalizeLocaleList(_locales_).
111 | 1. Let _options_ be ? ToObject(_options_).
112 | 1. Let _opt_ be a new Record.
113 | 1. Let _localeData_ be %DisplayNames%.[[LocaleData]].
114 | 1. Let _matcher_ be ? GetOption(_options_, `"localeMatcher"`, `"string"`, « `"lookup"`, `"best fit"` », `"best fit"`).
115 | 1. Set _opt_.[[localeMatcher]] to _matcher_.
116 | 1. Let _r_ be ResolveLocale(%DisplayNames%.[[AvailableLocales]], _requestedLocales_, _opt_, %DisplayNames%.[[RelevantExtensionKeys]]).
117 | 1. Let _style_ be ? GetOption(_options_, `"style"`, `"string"`, « `"narrow"`, `"short"`, `"long"` », `"long"`).
118 | 1. Set _displayNames_.[[Style]] to _style_.
119 | 1. Let _type_ be ? GetOption(_options_, `"type"`, `"string"`, « `"language"`, `"region"`, `"script"`, `"currency"` », *undefined*).
120 | 1. If _type_ is *undefined*, throw a *TypeError* exception.
121 | 1. Set _displayNames_.[[Type]] to _type_.
122 | 1. Let _fallback_ be ? GetOption(_options_, `"fallback"`, `"string"`, « `"code"`, `"none"` », `"code"`).
123 | 1. Set _displayNames_.[[Fallback]] to _fallback_.
124 | 1. Set _displayNames_.[[Locale]] to the value of _r_.[[Locale]].
125 | 1. Let _dataLocale_ be _r_.[[dataLocale]].
126 | 1. Let _dataLocaleData_ be _localeData_.[[<_dataLocale_>]].
127 | 1. Let _types_ be _dataLocaleData_.[[types]].
128 | 1. Assert: _types_ is a Record (see ).
129 | 1. Let _typeFields_ be _types_.[[<_type_>]].
130 | 1. Assert: _typeFields_ is a Record (see ).
131 | 1. Let _styleFields_ be _typeFields_.[[<_style_>]].
132 | 1. Assert: _styleFields_ is a Record (see ).
133 | 1. Set _displayNames_.[[Fields]] to _styleFields_.
134 | 1. Return _displayNames_.
135 |
136 |
137 |
138 |
139 |
140 |
Properties of the Intl.DisplayNames Constructor
141 |
142 |
143 | The Intl.DisplayNames constructor has the following properties:
144 |
145 |
146 |
147 |
Intl.DisplayNames.prototype
148 |
149 |
150 | The value of *Intl.DisplayNames.prototype* is *%DisplayNamesPrototype%*.
151 |
152 |
153 | This property has the attributes { [[Writable]]: *false*, [[Enumerable]]: *false*, [[Configurable]]: *false* }.
154 |
161 | When the *supportedLocalesOf* method of *%DisplayNames%* is called, the following steps are taken:
162 |
163 |
164 |
165 | 1. Let _availableLocales_ be *%DisplayNames%*.[[AvailableLocales]].
166 | 1. Let _requestedLocales_ be ? CanonicalizeLocaleList(_locales_).
167 | 1. Return ? SupportedLocales(_availableLocales_, _requestedLocales_, _options_).
168 |
169 |
170 |
171 |
172 |
173 |
Internal slots
174 |
175 |
176 | The value of the [[AvailableLocales]] internal slot is implementation defined within the constraints described in .
177 |
178 |
179 |
180 | The value of the [[RelevantExtensionKeys]] internal slot is « ».
181 |
182 |
183 |
184 | The value of the [[LocaleData]] internal slot is implementation defined within the constraints described in and the following additional constraints:
185 |
186 |
187 |
188 |
[[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"`.
189 |
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"`.
190 |
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.
191 |
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.
192 |
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.
193 |
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.
194 |
195 |
196 |
197 | It is recommended that implementations use the locale data provided by the Common Locale Data Repository (available at http://cldr.unicode.org/).
198 |
199 |
200 |
201 |
202 |
203 |
204 |
Properties of the Intl.DisplayNames Prototype Object
205 |
206 |
207 | 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.
208 |
209 |
210 |
211 |
Intl.DisplayNames.prototype.constructor
212 |
213 |
214 | The initial value of *Intl.DisplayNames.prototype.constructor* is the intrinsic object *%DisplayNames%*.
215 |
216 |
217 |
218 |
219 |
Intl.DisplayNames.prototype[ @@toStringTag ]
220 |
221 |
222 | The initial value of the @@toStringTag property is the string value `"Intl.DisplayNames"`.
223 |
224 |
225 | This property has the attributes { [[Writable]]: *false*, [[Enumerable]]: *false*, [[Configurable]]: *true* }.
226 |
227 |
228 |
229 |
230 |
Intl.DisplayNames.prototype.of( _code_ )
231 |
232 |
233 | When the *Intl.DisplayNames.prototype.of* is called with an argument _code_, the following steps are taken:
234 |
235 |
236 |
237 | 1. Let _displayNames_ be *this* value.
238 | 1. If Type(_displayNames_) is not Object, throw a *TypeError* exception.
239 | 1. If _displayNames_ does not have an [[InitializedDisplayNames]] internal slot, throw a *TypeError* exception.
240 | 1. Let _code_ be ? ToString(_code_).
241 | 1. Let _code_ be ? CanonicalCodeForDisplayNames(_displayNames_.[[Type]], _code_).
242 | 1. Let _fields_ be _displayNames_.[[Fields]].
243 | 1. Let _name_ be _fields_[[<_code_>]].
244 | 1. If _name_ is not *undefined*, return _name_.
245 | 1. If _displayNames_.[[Fallback]] is `"code"`, return _code_.
246 | 1. Return *undefined*.
247 |
248 |
249 |
250 |
251 |
Intl.DisplayNames.prototype.resolvedOptions ()
252 |
253 |
254 | This function provides access to the locale and options computed during initialization of the object.
255 |
256 |
257 |
258 | 1. Let _displayNames_ be *this* value.
259 | 1. If Type(_displayNames_) is not Object, throw a *TypeError* exception.
260 | 1. If _displayNames_ does not have an [[InitializedDisplayNames]] internal slot, throw a *TypeError* exception.
261 | 1. Let _options_ be ! ObjectCreate(%ObjectPrototype%).
262 | 1. For each row of , except the header row, in table order, do
263 | 1. Let _p_ be the Property value of the current row.
264 | 1. Let _v_ be the value of _displayNames_'s internal slot whose name is the Internal Slot value of the current row.
265 | 1. If _v_ is not *undefined*, then
266 | 1. Perform ! CreateDataPropertyOrThrow(_options_, _p_, _v_).
267 | 1. Return _options_.
268 |
269 |
270 |
271 | Resolved Options of DisplayNames Instances
272 |
273 |
274 |
275 |
Internal Slot
276 |
Property
277 |
278 |
279 |
280 |
[[Locale]]
281 |
`"locale"`
282 |
283 |
284 |
[[Style]]
285 |
`"style"`
286 |
287 |
288 |
[[Type]]
289 |
`"type"`
290 |
291 |
292 |
[[Fallback]]
293 |
`"fallback"`
294 |
295 |
296 |
297 |
298 |
299 |
300 |
301 |
Properties of Intl.DisplayNames Instances
302 |
303 |
304 | Intl.DisplayNames instances are ordinary objects that inherit properties from %DisplayNamesPrototype%.
305 |
306 |
307 |
308 | Intl.DisplayNames instances have an [[InitializedDisplayNames]] internal slot.
309 |
310 |
311 |
312 | Intl.DisplayNames instances also have several internal slots that are computed by the constructor:
313 |
314 |
315 |
316 |
[[Locale]] is a String value with the language tag of the locale whose localization is used for formatting.
317 |
[[Style]] is one of the String values `"narrow"`, `"short"`, or `"long"`, identifying the display names style used.
318 |
[[Type]] is one of the String values `"language"`, `"region"`, `"script"`, or `"currency"`, identifying the type of the display names requested.
319 |
[[Fallback]] is one of the String values `"code"`, or `"none"`, identifying the fallback return when the system does not have the requested display name.
320 |
[[Fields]] is a Record (see ) which
321 | must have fields with keys corresponding to codes according to [[Style]] and [[Type]].
21 | 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:
22 |
23 |
24 | Strings that are already available because they're needed for other APIs. For example, names for the days of the week are necessary to provide Intl.DateTimeFormat capabilities. In the absence of a direct API, we see programs parsing the output of Intl.DateTimeFormat to find these names, which is an unreliable/unstable technique.
25 |
26 |
27 | Strings that are universally standardized and are likely necessary for any multilingual JavaScript application. For example language/region names.
28 |
29 |
30 |
31 |
32 | 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.
33 |
34 |
35 | 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).
36 |
37 |
38 | 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.
39 |
40 |
41 | The set of strings included may grow over time, but we expect to restrict the growth according to pragmatic requirements, including:
42 |
43 |
44 | Strings which are included should be generically useful across multiple application types.
45 |
46 |
47 | The inclusion of strings should not be too much of a burden on implementations in terms of data size.
48 |
49 |
50 | There should be an open data source that implementations can use for the string values, e.g., CLDR.
51 |
52 |
53 |
54 | Additional strings included in Intl.DisplayNames would 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.
55 |
56 |
57 |
Abstract Operations for DisplayNames Objects
58 |
59 |
60 |
IsValidCodeForDisplayNames ( _type_, _code_ )
61 |
62 | The IsValidCodeForDisplayNames 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. The algorithm refers to UTS 35's Unicode Language and Locale Identifiers grammar. The following steps are taken:
63 |
64 |
65 | 1. If _type_ is `"language"`, then
66 | 1. If _code_ matches the `unicode_language_id` production, return *true*.
67 | 1. Return *false*.
68 | 1. If _type_ is `"region"`, then
69 | 1. If _code_ matches the `unicode_region_subtag` production, return *true*.
70 | 1. Return *false*.
71 | 1. If _type_ is `"script"`, then
72 | 1. If _code_ matches the `unicode_script_subtag` production, return *true*.
73 | 1. Return *false*.
74 | 1. If _type_ is `"currency"`, return ! IsWellFormedCurrencyCode(_code_).
75 | 1. If _type_ is `"weekday"`, return ! IsValidWeekdayCode(_code_).
76 | 1. If _type_ is `"month"`, return ! IsValidMonthCode(_code_).
77 | 1. If _type_ is `"quarter"`, return ! IsValidQuarterCode(_code_).
78 | 1. If _type_ is `"dayPeriod"`, return ! IsValidDayPeriodCode(_code_).
79 | 1. Assert: _type_ is `"dateTimeField"`
80 | 1. Return ! IsValidDateTimeFieldCode(_code_).
81 |
82 |
83 |
84 |
85 |
IsValidWeekdayCode ( _weekday_ )
86 |
87 | The IsValidWeekdayCode abstract operation is called with arguments _weekday_. It verifies that the _weekday_ argument represents a valid weekday code. The following steps are taken:
88 |
89 |
90 | 1. Let _weekday_ be ? ToNumber(_weekday_).
91 | 1. If _weekday_ is listed in , return *true*.
92 | 1. Return *false*.
93 |
94 |
95 |
96 | Codes For Date Time of DisplayNames
97 |
98 |
99 |
100 |
Code
101 |
Description
102 |
103 |
104 |
105 |
`1`
106 |
Monday, e.g. M, Mon, Monday, etc.
107 |
108 |
109 |
`2`
110 |
Tuesday, e.g. Tu, Tue, Tuesday, etc.
111 |
112 |
113 |
`3`
114 |
Wednesday, e.g. W, Wed, Wednesday, etc.
115 |
116 |
117 |
`4`
118 |
Thursday, e.g. Th, Thur, Thursday, etc.
119 |
120 |
121 |
`5`
122 |
Friday, e.g. F, Fri, Friday, etc.
123 |
124 |
125 |
`6`
126 |
Saturday, e.g. Sa, Sat, Saturday, etc.
127 |
128 |
129 |
`7`
130 |
Sunday, e.g. Su, Sun, Sunday, etc.
131 |
132 |
133 |
134 |
135 |
136 |
137 |
138 |
IsValidMonthCode ( _month_ )
139 |
140 | The IsValidMonthCode abstract operation is called with arguments _month_. It verifies that the _month_ argument represents a valid month code. The following steps are taken:
141 |
142 |
143 | 1. Let _month_ be ? ToNumber(_month_).
144 | 1. If _month_ is listed in , return *true*.
145 | 1. Return *false*.
146 |
147 |
148 |
149 | Codes For Month of DisplayNames
150 |
151 |
152 |
153 |
Code
154 |
Description
155 |
156 |
157 |
158 |
`1`
159 |
The first month of the year, e.g. Jan, January.
160 |
161 |
162 |
`2`
163 |
The second month of the year, e.g. Feb, February.
164 |
165 |
166 |
`3`
167 |
The third month of the year, e.g. Mar, March.
168 |
169 |
170 |
`4`
171 |
The fourth month of the year, e.g. Apr, April.
172 |
173 |
174 |
`5`
175 |
The fifth month of the year, e.g. May.
176 |
177 |
178 |
`6`
179 |
The sixth month of the year, e.g. Jun, June.
180 |
181 |
182 |
`7`
183 |
The seventh month of the year, e.g. Jul, July.
184 |
185 |
186 |
`8`
187 |
The eigth month of the year, e.g. Aug, August.
188 |
189 |
190 |
`9`
191 |
The ninth month of the year, e.g. Sep, September.
192 |
193 |
194 |
`10`
195 |
The tenth month of the year, e.g. Oct, October.
196 |
197 |
198 |
`11`
199 |
The eleventh month of the year, e.g. Nov, November.
200 |
201 |
202 |
`12`
203 |
The twelfth month of the year, e.g. Dec, December.
204 |
205 |
206 |
`13`
207 |
The thirteenth month, for relevant calendar systems.
208 |
209 |
210 |
211 |
212 |
213 |
214 |
215 |
IsValidQuarterCode ( _quarter_ )
216 |
217 | The IsValidQuarterCode abstract operation is called with arguments _quarter_. It verifies that the _quarter_ argument represents a valid month code. The following steps are taken:
218 |
219 |
220 | 1. Let _quarter_ be ? ToNumber(_quarter_).
221 | 1. If _quarter_ is listed in , return *true*.
222 | 1. Return *false*.
223 |
224 |
225 |
226 | Codes For Quarter of DisplayNames
227 |
228 |
229 |
230 |
Code
231 |
Description
232 |
233 |
234 |
235 |
`1`
236 |
The first quarter in year, e.g. Q1, first quarter, 1st quarter.
237 |
238 |
239 |
`2`
240 |
The second quarter in year, e.g. Q2, second quarter, 2nd quarter.
241 |
242 |
243 |
`3`
244 |
The third quarter in year, e.g. Q3, third quarter, 3rd quarter.
245 |
246 |
247 |
`4`
248 |
The fourth quarter in year, e.g. Q4, fourth quarter, 4th quarter.
249 |
250 |
251 |
252 |
253 |
254 |
255 |
256 |
IsValidDayPeriodCode ( _dayperiod_ )
257 |
258 | The IsValidDayPeriodCode abstract operation is called with arguments _dayperiod_. It verifies that the _dayperiod_ argument represents a valid day period code. The following steps are taken:
259 |
260 |
261 | 1. If _dayperiod_ is listed in , return *true*.
262 | 1. Return *false*.
263 |
264 |
265 |
266 | Codes For Day Period of DisplayNames
267 |
268 |
269 |
270 |
Code
271 |
Description
272 |
273 |
274 |
275 |
`"am"`
276 |
Ante meridiem, e.g. AM, a.m.
277 |
278 |
279 |
`"pm"`
280 |
Post meridiem, e.g. PM, p.m.
281 |
282 |
283 |
284 |
285 |
286 |
287 |
288 |
IsValidDateTimeFieldCode ( _field_ )
289 |
290 | The IsValidDateTimeFieldCode abstract operation is called with arguments _field_. It verifies that the __field_ argument represents a valid date time field code. The following steps are taken:
291 |
292 |
293 | 1. If _field_ is listed in , return *true*.
294 | 1. Return *false*.
295 |
296 |
297 |
298 | Codes For Date Time Field of DisplayNames
299 |
300 |
301 |
302 |
Code
303 |
Description
304 |
305 |
306 |
307 |
`"era"`
308 |
The field indicating the era, e.g., AD or BC in the Gregorian (Julian) calendar.
309 |
310 |
311 |
`"year"`
312 |
The field indicating the year.
313 |
314 |
315 |
`"quarter"`
316 |
The field indicating the quarter, e.g., Q2, 2nd quarter, etc.
317 |
318 |
319 |
`"month"`
320 |
The field indicating the month, e.g. Sep, September, etc.
321 |
322 |
323 |
`"weekOfYear"`
324 |
The field indicating the week number within the current year.
325 |
326 |
327 |
`"weekday"`
328 |
The field indicating the day of week, e.g. Tue, Tuesday, etc.
329 |
330 |
331 |
`"day"`
332 |
The field indicating the day in month.
333 |
334 |
335 |
`"dayPeriod"`
336 |
The field indicating the day period, either am/pm marker or others, e.g. noon, evening.
337 |
338 |
339 |
`"hour"`
340 |
The field indicating the hour in day.
341 |
342 |
343 |
`"minute"`
344 |
The field indicating the minute in hour.
345 |
346 |
347 |
`"second"`
348 |
The field indicating the second in minute.
349 |
350 |
351 |
`"timeZoneName"`
352 |
The field indicating the timezone name, e.g. PDT, Pacific Daylight Time, etc.
353 |
354 |
355 |
356 |
357 |
358 |
359 |
360 |
361 |
362 |
The Intl.DisplayNames Constructor
363 |
364 |
365 | The DisplayNames constructor is a standard built-in property of the Intl object.
366 |
367 |
368 |
Intl.DisplayNames ([ _locales_ [ , _options_ ]])
369 |
370 |
371 | When the *Intl.DisplayNames* function is called with optional arguments the following steps are taken:
372 |
373 |
374 |
375 | 1. If NewTarget is *undefined*, throw a *TypeError* exception.
376 | 1. Let _displayNames_ be ? OrdinaryCreateFromConstructor(NewTarget, `"%DisplayNamesPrototype%"`, « [[InitializedDisplayNames]], [[Locale]], [[Calendar]], [[Style]], [[Type]], [[Fallback]], [[Fields]] »).
377 | 1. Let _requestedLocales_ be ? CanonicalizeLocaleList(_locales_).
378 | 1. If _options_ is *undefined*, then
379 | 1. Let _options_ be ObjectCreate(*null*).
380 | 1. Else
381 | 1. Let _options_ be ? ToObject(_options_).
382 | 1. Let _opt_ be a new Record.
383 | 1. Let _localeData_ be %DisplayNames%.[[LocaleData]].
384 | 1. Let _matcher_ be ? GetOption(_options_, `"localeMatcher"`, `"string"`, « `"lookup"`, `"best fit"` », `"best fit"`).
385 | 1. Set _opt_.[[localeMatcher]] to _matcher_.
386 | 1. Let _calendar_ be ? GetOption(_options_, `"calendar"`, `"string"`, *undefined*, *undefined*).
387 | 1. If _calendar_ is not *undefined*, then
388 | 1. If _calendar_ does not match the `(3*8alphanum) *("-" (3*8alphanum))` sequence, throw a *RangeError* exception.
389 | 1. Set _opt_.[[ca]] to _calendar_.
390 | 1. Let _r_ be ResolveLocale(%DisplayNames%.[[AvailableLocales]], _requestedLocales_, _opt_, %DisplayNames%.[[RelevantExtensionKeys]]).
391 | 1. Let _style_ be ? GetOption(_options_, `"style"`, `"string"`, « `"narrow"`, `"short"`, `"long"` », `"long"`).
392 | 1. Set _displayNames_.[[Style]] to _style_.
393 | 1. Let _type_ be ? GetOption(_options_, `"type"`, `"string"`, « `"language"`, `"region"`, `"script"`, `"currency"`, `"weekday"`, `"month"`, `"quarter"`, `"dayPeriod"`, `"dateTimeField"` », `"language"`).
394 | 1. Set _displayNames_.[[Type]] to _type_.
395 | 1. Let _fallback_ be ? GetOption(_options_, `"fallback"`, `"string"`, « `"code"`, `"none"` », `"code"`).
396 | 1. Set _displayNames_.[[Fallback]] to _fallback_.
397 | 1. Set _displayNames_.[[Locale]] to the value of _r_.[[Locale]].
398 | 1. Let _calendar_ be _r_.[[ca]].
399 | 1. Set _displayNames_.[[Calendar]] to _calendar_.
400 | 1. Let _dataLocale_ be _r_.[[dataLocale]].
401 | 1. Let _dataLocaleData_ be _localeData_.[[<_dataLocale_>]].
402 | 1. Let _types_ be _dataLocaleData_.[[types]].
403 | 1. Assert: _types_ is a Record (see ).
404 | 1. Let _typeFields_ be _types_.[[<_type_>]].
405 | 1. Assert: _typeFields_ is a Record (see ).
406 | 1. If _type_ is `"weekday"`, `"month"`, `"quarter"`, or `"dayPeriod"`, then
407 | 1. Let _styleFields_ be _typeFields_.[[<_calendar_>]].[[<_style_>]].
408 | 1. Else,
409 | 1. Let _styleFields_ be _typeFields_.[[<_style_>]].
410 | 1. Assert: _styleFields_ is a Record (see ).
411 | 1. Set _displayNames_.[[Fields]] to _styleFields_.
412 | 1. Return _displayNames_.
413 |
414 |
415 |
416 |
417 |
418 |
Properties of the Intl.DisplayNames Constructor
419 |
420 |
421 | The Intl.DisplayNames constructor has the following properties:
422 |
423 |
424 |
425 |
Intl.DisplayNames.prototype
426 |
427 |
428 | The value of *Intl.DisplayNames.prototype* is *%DisplayNamesPrototype%*.
429 |
430 |
431 | This property has the attributes { [[Writable]]: *false*, [[Enumerable]]: *false*, [[Configurable]]: *false* }.
432 |
439 | When the *supportedLocalesOf* method of *%DisplayNames%* is called, the following steps are taken:
440 |
441 |
442 |
443 | 1. Let _availableLocales_ be *%DisplayNames%*.[[AvailableLocales]].
444 | 1. Let _requestedLocales_ be ? CanonicalizeLocaleList(_locales_).
445 | 1. Return ? SupportedLocales(_availableLocales_, _requestedLocales_, _options_).
446 |
447 |
448 |
449 |
450 |
451 |
Internal slots
452 |
453 |
454 | The value of the [[AvailableLocales]] internal slot is implementation defined within the constraints described in .
455 |
456 |
457 |
458 | The value of the [[RelevantExtensionKeys]] internal slot is « `"ca"` ».
459 |
460 |
461 |
462 | The value of the [[LocaleData]] internal slot is implementation defined within the constraints described in and the following additional constraints:
463 |
464 |
465 |
466 |
[[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"`, `"currency"`, `"weekday"`, `"month"`, `"quarter"`, `"dayPeriod"`, and `"dateTimeField"`.
467 |
The value of fields `"language"`, `"region"`, `"script"`, `"currency"`, and `"dateTimeField"` must be a Records which must have fields with the names of one of the valid display name styles: `"narrow"`, `"short"`, and `"long"`.
468 |
The value of fields `"weekday"`, `"month"`, `"quarter"`, and `"dayPeriod"` must have a [[<_calendar_>]] field for all calendar values _calendar_. The value of each of those fields in turn must be a Records which must have fields with the names of one of the valid display name styles: `"narrow"`, `"short"`, and `"long"`.
469 |
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.
470 |
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.
471 |
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.
472 |
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.
473 |
The display name styles fields under display name type `"weekday"` should contain Records, with keys corresponding to codes listed in . The value of these fields must be string values.
474 |
The display name styles fields under display name type `"month"` should contain Records, with keys corresponding to codes listed in . The value of these fields must be string values.
475 |
The display name styles fields under display name type `"quarter"` should contain Records, with keys corresponding to codes listed in . The value of these fields must be string values.
476 |
The display name styles fields under display name type `"dayPeriod"` should contain Records, with keys corresponding to codes listed in . The value of these fields must be string values.
477 |
The display name styles fields under display name type `"dateTimeField"` should contain Records, with keys corresponding to codes listed in . The value of these fields must be string values.
478 |
479 |
480 |
481 | It is recommended that implementations use the locale data provided by the Common Locale Data Repository (available at http://cldr.unicode.org/).
482 |
483 |
484 |
485 |
486 |
487 |
488 |
Properties of the Intl.DisplayNames Prototype Object
489 |
490 |
491 | 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.
492 |
493 |
494 |
495 |
Intl.DisplayNames.prototype.constructor
496 |
497 |
498 | The initial value of *Intl.DisplayNames.prototype.constructor* is the intrinsic object *%DisplayNames%*.
499 |
500 |
501 |
502 |
503 |
Intl.DisplayNames.prototype[ @@toStringTag ]
504 |
505 |
506 | The initial value of the @@toStringTag property is the string value `"Intl.DisplayNames"`.
507 |
508 |
509 | This property has the attributes { [[Writable]]: *false*, [[Enumerable]]: *false*, [[Configurable]]: *true* }.
510 |
511 |
512 |
513 |
514 |
Intl.DisplayNames.prototype.of( _code_ )
515 |
516 |
517 | When the *Intl.DisplayNames.prototype.of* is called with an argument _code_, the following steps are taken:
518 |
519 |
520 |
521 | 1. Let _displayNames_ be *this* value.
522 | 1. If Type(_displayNames_) is not Object, throw a *TypeError* exception.
523 | 1. If _displayNames_ does not have an [[InitializedDisplayNames]] internal slot, throw a *TypeError* exception.
524 | 1. If Type(_code_) is not String, Number or Object, throw a *TypeError* exception.
525 | 1. If Type(_code_) is Object, then
526 | 1. Let _code_ be ? ToString(_code_).
527 | 1. If the result of ! IsValidCodeForDisplayNames(_displayNames_.[[Type]], _code_) is *false*, throw a *RangeError* exception.
528 | 1. Let _fields_ be _displayNames_.[[Fields]].
529 | 1. Let _name_ be _fields_[[<_code_>]].
530 | 1. If _name_ is not *undefined*, return _name_.
531 | 1. If _displayNames_.[[Fallback]] is `"code"`, return _code_.
532 | 1. Return *undefined*.
533 |
534 |
535 |
536 |
537 |
Intl.DisplayNames.prototype.resolvedOptions ()
538 |
539 |
540 | This function provides access to the locale and options computed during initialization of the object.
541 |
542 |
543 |
544 | 1. Let _displayNames_ be *this* value.
545 | 1. If Type(_displayNames_) is not Object, throw a *TypeError* exception.
546 | 1. If _displayNames_ does not have an [[InitializedDisplayNames]] internal slot, throw a *TypeError* exception.
547 | 1. Let _options_ be ! ObjectCreate(%ObjectPrototype%).
548 | 1. For each row of , except the header row, in table order, do
549 | 1. Let _p_ be the Property value of the current row.
550 | 1. Let _v_ be the value of _displayNames_'s internal slot whose name is the Internal Slot value of the current row.
551 | 1. If _v_ is not *undefined*, then
552 | 1. Perform ! CreateDataPropertyOrThrow(_options_, _p_, _v_).
553 | 1. Return _options_.
554 |
555 |
556 |
557 | Resolved Options of DisplayNames Instances
558 |
559 |
560 |
561 |
Internal Slot
562 |
Property
563 |
564 |
565 |
566 |
[[Locale]]
567 |
`"locale"`
568 |
569 |
570 |
[[Calendar]]
571 |
`"calendar"`
572 |
573 |
574 |
[[Style]]
575 |
`"style"`
576 |
577 |
578 |
[[Type]]
579 |
`"type"`
580 |
581 |
582 |
[[Fallback]]
583 |
`"fallback"`
584 |
585 |
586 |
587 |
588 |
589 |
590 |
591 |
Properties of Intl.DisplayNames Instances
592 |
593 |
594 | Intl.DisplayNames instances are ordinary objects that inherit properties from %DisplayNamesPrototype%.
595 |
596 |
597 |
598 | Intl.DisplayNames instances have an [[InitializedDisplayNames]] internal slot.
599 |
600 |
601 |
602 | Intl.DisplayNames instances also have several internal slots that are computed by the constructor:
603 |
604 |
605 |
606 |
[[Locale]] is a String value with the language tag of the locale whose localization is used for formatting.
607 |
[[Calendar]] is a String value with the `"type"` given in Unicode Technical Standard 35 for the calendar used for formatting.
608 |
[[Style]] is one of the String values `"narrow"`, `"short"`, or `"long"`, identifying the display names style used.
609 |
[[Type]] is one of the String values `"language"`, `"region"`, `"script"`, `"currency"`, `"weekday"`, `"month"`, `"quarter"`, `"dayPeriod"`, or `"dateTimeField"`, identifying the type of the display names requested.
610 |
[[Fallback]] is one of the String values `"code"`, or `"none"`, identifying the fallback return when the system does not have the requested display name.
611 |
[[Fields]] is a Record (see ) which
612 | must have fields with keys corresponding to codes according to [[Style]] and [[Type]].