This repository has been archived by the owner on Jan 26, 2022. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 10
/
Copy pathspec.emu
325 lines (284 loc) · 16.8 KB
/
spec.emu
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
<!doctype html>
<meta charset="utf8">
<link rel="stylesheet" href="./spec.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.4/styles/github.min.css">
<script src="./spec.js"></script>
<pre class="metadata">
title: Intl.DisplayNames Proposal
status: proposal
stage: 3
location: /~https://github.com/tc39-transfer/proposal-intl-displaynames
copyright: true
contributors: Google, Ecma International
</pre>
<emu-biblio href="./biblio.json"></emu-biblio>
<emu-clause id="intl-displaynames-objects">
<h1>DisplayNames Objects</h1>
<p>
For motivation and a high-level introduction, see <a href="/~https://github.com/tc39/proposal-intl-displaynames/blob/master/README.md">the explainer document</a>.
</p>
<p>
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:
<ul>
<li>
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.
</li>
<li>
Strings that are universally standardized and are likely necessary for any multilingual JavaScript application. For example language/region names.
</li>
</ul>
</p>
<p>
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.
</p>
<p>
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).
</p>
<p>
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.
</p>
<p>
The set of strings included may grow over time, but we expect to restrict the growth according to pragmatic requirements, including:
<ul>
<li>
Strings which are included should be generically useful across multiple application types.
</li>
<li>
The inclusion of strings should not be too much of a burden on implementations in terms of data size.
</li>
<li>
There should be an open data source that implementations can use for the string values, e.g., CLDR.
</li>
<li>
Strings that rarely (never) change, and thus don't need to be dynamically generated.
</li>
<li>
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.
</li>
</ul>
</p>
<p>
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.
</p>
<emu-clause id="sec-intl-displaynames-abstracts">
<h1>Abstract Operations for DisplayNames Objects</h1>
<emu-clause id="sec-canonicalcodefordisplaynames" aoid="CanonicalCodeForDisplayNames">
<h1>CanonicalCodeForDisplayNames ( _type_, _code_ )</h1>
<p>
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 <a href="https://www.unicode.org/reports/tr35/#Identifiers">UTS 35's Unicode Language and Locale Identifiers grammar</a>. The following steps are taken:
</p>
<emu-alg>
1. If _type_ is `"language"`, then
1. If _code_ does not matches the `unicode_language_id` production, throw a *RangeError* exceptipon.
1. If IsStructurallyValidLanguageTag(_code_) is *false*, throw a *RangeError* exception.
1. Set _code_ to CanonicalizeUnicodeLocaleId(_code_).
1. Return _code_.
1. If _type_ is `"region"`, then
1. If _code_ does not matches the `unicode_region_subtag` production, throw a *RangeError* exceptipon.
1. Let _code_ be the result of mapping _code_ to upper case as described in <emu-xref href="#sec-case-sensitivity-and-case-mapping"></emu-xref>.
1. Return _code_.
1. If _type_ is `"script"`, then
1. If _code_ does not matches the `unicode_script_subtag` production, throw a *RangeError* exceptipon.
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 <emu-xref href="#sec-case-sensitivity-and-case-mapping"></emu-xref>.
1. Return _code_.
1. Assert: _type_ is `"currency"`
1. If ! IsWellFormedCurrencyCode(_code_) is *false*, throw a *RangeError* exceptipon.
1. Let _code_ be the result of mapping _code_ to upper case as described in <emu-xref href="#sec-case-sensitivity-and-case-mapping"></emu-xref>.
1. Return _code_.
</emu-alg>
</emu-clause>
</emu-clause>
<emu-clause id="sec-intl-displaynames-constructor">
<h1>The Intl.DisplayNames Constructor</h1>
<p>
The DisplayNames constructor is a standard built-in property of the Intl object.</p>
<emu-clause id="sec-Intl.DisplayNames">
<h1>Intl.DisplayNames ( _locales_ , _options_ )</h1>
<p>
When the *Intl.DisplayNames* function is called with arguments _locales_ and _options_, the following steps are taken:
</p>
<emu-alg>
1. If NewTarget is *undefined*, throw a *TypeError* exception.
1. Let _displayNames_ be ? OrdinaryCreateFromConstructor(NewTarget, `"%DisplayNamesPrototype%"`, « [[InitializedDisplayNames]], [[Locale]], [[Style]], [[Type]], [[Fallback]], [[Fields]] »).
1. Let _requestedLocales_ be ? CanonicalizeLocaleList(_locales_).
1. Let _options_ be ? ToObject(_options_).
1. Let _opt_ be a new Record.
1. Let _localeData_ be %DisplayNames%.[[LocaleData]].
1. Let _matcher_ be ? GetOption(_options_, `"localeMatcher"`, `"string"`, « `"lookup"`, `"best fit"` », `"best fit"`).
1. Set _opt_.[[localeMatcher]] to _matcher_.
1. Let _r_ be ResolveLocale(%DisplayNames%.[[AvailableLocales]], _requestedLocales_, _opt_, %DisplayNames%.[[RelevantExtensionKeys]]).
1. Let _style_ be ? GetOption(_options_, `"style"`, `"string"`, « `"narrow"`, `"short"`, `"long"` », `"long"`).
1. Set _displayNames_.[[Style]] to _style_.
1. Let _type_ be ? GetOption(_options_, `"type"`, `"string"`, « `"language"`, `"region"`, `"script"`, `"currency"` », *undefined*).
1. If _type_ is *undefined*, throw a *TypeError* exception.
1. Set _displayNames_.[[Type]] to _type_.
1. Let _fallback_ be ? GetOption(_options_, `"fallback"`, `"string"`, « `"code"`, `"none"` », `"code"`).
1. Set _displayNames_.[[Fallback]] to _fallback_.
1. Set _displayNames_.[[Locale]] to the value of _r_.[[Locale]].
1. Let _dataLocale_ be _r_.[[dataLocale]].
1. Let _dataLocaleData_ be _localeData_.[[<_dataLocale_>]].
1. Let _types_ be _dataLocaleData_.[[types]].
1. Assert: _types_ is a Record (see <emu-xref href="#sec-Intl.DisplayNames-internal-slots"></emu-xref>).
1. Let _typeFields_ be _types_.[[<_type_>]].
1. Assert: _typeFields_ is a Record (see <emu-xref href="#sec-Intl.DisplayNames-internal-slots"></emu-xref>).
1. Let _styleFields_ be _typeFields_.[[<_style_>]].
1. Assert: _styleFields_ is a Record (see <emu-xref href="#sec-Intl.DisplayNames-internal-slots"></emu-xref>).
1. Set _displayNames_.[[Fields]] to _styleFields_.
1. Return _displayNames_.
</emu-alg>
</emu-clause>
</emu-clause>
<emu-clause id="sec-properties-of-intl-displaynames-constructor">
<h1>Properties of the Intl.DisplayNames Constructor</h1>
<p>
The Intl.DisplayNames constructor has the following properties:
</p>
<emu-clause id="sec-Intl.DisplayNames.prototype">
<h1>Intl.DisplayNames.prototype</h1>
<p>
The value of *Intl.DisplayNames.prototype* is *%DisplayNamesPrototype%*.
</p>
<p>
This property has the attributes { [[Writable]]: *false*, [[Enumerable]]: *false*, [[Configurable]]: *false* }.
</p>
</emu-clause>
<emu-clause id="sec-Intl.DisplayNames.supportedLocalesOf">
<h1>Intl.DisplayNames.supportedLocalesOf ( _locales_ [, _options_ ])</h1>
<p>
When the *supportedLocalesOf* method of *%DisplayNames%* is called, the following steps are taken:
</p>
<emu-alg>
1. Let _availableLocales_ be *%DisplayNames%*.[[AvailableLocales]].
1. Let _requestedLocales_ be ? CanonicalizeLocaleList(_locales_).
1. Return ? SupportedLocales(_availableLocales_, _requestedLocales_, _options_).
</emu-alg>
</emu-clause>
<emu-clause id="sec-Intl.DisplayNames-internal-slots">
<h1>Internal slots</h1>
<p>
The value of the [[AvailableLocales]] internal slot is implementation defined within the constraints described in <emu-xref href="#sec-internal-slots"></emu-xref>.
</p>
<p>
The value of the [[RelevantExtensionKeys]] internal slot is « ».
</p>
<p>
The value of the [[LocaleData]] internal slot is implementation defined within the constraints described in <emu-xref href="#sec-internal-slots"></emu-xref> and the following additional constraints:
</p>
<ul>
<li>[[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"`.</li>
<li>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"`.</li>
<li>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.</li>
<li>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.</li>
<li>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.</li>
<li>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.</li>
</ul>
<emu-note>
It is recommended that implementations use the locale data provided by the Common Locale Data Repository (available at <a href="http://cldr.unicode.org/">http://cldr.unicode.org/</a>).
</emu-note>
</emu-clause>
</emu-clause>
<emu-clause id="sec-properties-of-intl-displaynames-prototype-object">
<h1>Properties of the Intl.DisplayNames Prototype Object</h1>
<p>
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.
</p>
<emu-clause id="sec-Intl.DisplayNames.prototype.constructor">
<h1>Intl.DisplayNames.prototype.constructor</h1>
<p>
The initial value of *Intl.DisplayNames.prototype.constructor* is the intrinsic object *%DisplayNames%*.
</p>
</emu-clause>
<emu-clause id="sec-Intl.DisplayNames.prototype-@@tostringtag">
<h1>Intl.DisplayNames.prototype[ @@toStringTag ]</h1>
<p>
The initial value of the @@toStringTag property is the string value `"Intl.DisplayNames"`.
</p>
<p>
This property has the attributes { [[Writable]]: *false*, [[Enumerable]]: *false*, [[Configurable]]: *true* }.
</p>
</emu-clause>
<emu-clause id="sec-Intl.DisplayNames.prototype.of" aoid="Intl.DisplayNames.prototype.of">
<h1>Intl.DisplayNames.prototype.of( _code_ )</h1>
<p>
When the *Intl.DisplayNames.prototype.of* is called with an argument _code_, the following steps are taken:
</p>
<emu-alg>
1. Let _displayNames_ be *this* value.
1. If Type(_displayNames_) is not Object, throw a *TypeError* exception.
1. If _displayNames_ does not have an [[InitializedDisplayNames]] internal slot, throw a *TypeError* exception.
1. Let _code_ be ? ToString(_code_).
1. Let _code_ be ? CanonicalCodeForDisplayNames(_displayNames_.[[Type]], _code_).
1. Let _fields_ be _displayNames_.[[Fields]].
1. Let _name_ be _fields_[[<_code_>]].
1. If _name_ is not *undefined*, return _name_.
1. If _displayNames_.[[Fallback]] is `"code"`, return _code_.
1. Return *undefined*.
</emu-alg>
</emu-clause>
<emu-clause id="sec-Intl.DisplayNames.prototype.resolvedOptions">
<h1>Intl.DisplayNames.prototype.resolvedOptions ()</h1>
<p>
This function provides access to the locale and options computed during initialization of the object.
</p>
<emu-alg>
1. Let _displayNames_ be *this* value.
1. If Type(_displayNames_) is not Object, throw a *TypeError* exception.
1. If _displayNames_ does not have an [[InitializedDisplayNames]] internal slot, throw a *TypeError* exception.
1. Let _options_ be ! ObjectCreate(%ObjectPrototype%).
1. For each row of <emu-xref href="#table-displaynames-resolvedoptions-properties"></emu-xref>, except the header row, in table order, do
1. Let _p_ be the Property value of the current row.
1. Let _v_ be the value of _displayNames_'s internal slot whose name is the Internal Slot value of the current row.
1. If _v_ is not *undefined*, then
1. Perform ! CreateDataPropertyOrThrow(_options_, _p_, _v_).
1. Return _options_.
</emu-alg>
<emu-table id="table-displaynames-resolvedoptions-properties">
<emu-caption>Resolved Options of DisplayNames Instances</emu-caption>
<table class="real-table">
<thead>
<tr>
<th>Internal Slot</th>
<th>Property</th>
</tr>
</thead>
<tr>
<td>[[Locale]]</td>
<td>`"locale"`</td>
</tr>
<tr>
<td>[[Style]]</td>
<td>`"style"`</td>
</tr>
<tr>
<td>[[Type]]</td>
<td>`"type"`</td>
</tr>
<tr>
<td>[[Fallback]]</td>
<td>`"fallback"`</td>
</tr>
</table>
</emu-table>
</emu-clause>
</emu-clause>
<emu-clause id="sec-properties-of-intl-displaynames-instances">
<h1>Properties of Intl.DisplayNames Instances</h1>
<p>
Intl.DisplayNames instances are ordinary objects that inherit properties from %DisplayNamesPrototype%.
</p>
<p>
Intl.DisplayNames instances have an [[InitializedDisplayNames]] internal slot.
</p>
<p>
Intl.DisplayNames instances also have several internal slots that are computed by the constructor:
</p>
<ul>
<li>[[Locale]] is a String value with the language tag of the locale whose localization is used for formatting.</li>
<li>[[Style]] is one of the String values `"narrow"`, `"short"`, or `"long"`, identifying the display names style used.</li>
<li>[[Type]] is one of the String values `"language"`, `"region"`, `"script"`, or `"currency"`, identifying the type of the display names requested.</li>
<li>[[Fallback]] is one of the String values `"code"`, or `"none"`, identifying the fallback return when the system does not have the requested display name.</li>
<li>[[Fields]] is a Record (see <emu-xref href="#sec-Intl.DisplayNames-internal-slots"></emu-xref>) which
must have fields with keys corresponding to codes according to [[Style]] and [[Type]].</li>
</ul>
</emu-clause>
</emu-clause>