This repository has been archived by the owner on Jan 9, 2021. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 17
/
es-intl-1-final.html
3435 lines (2989 loc) · 202 KB
/
es-intl-1-final.html
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
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!doctype html>
<html lang="en-GB">
<head>
<meta charset="utf-8">
<title>ECMAScript Internationalization API Specification – ECMA-402 Edition 1.0</title>
<link href="es5.1.css" rel="stylesheet">
</head>
<body>
<img src="Ecma_RVB-003.jpg" alt="Ecma International Logo." width="373" height="146">
<hgroup>
<h1 style="color: #ff6600">Standard ECMA-402</h1>
<h1 style="color: #ff6600">1<sup>st</sup> Edition / December 2012</h1>
<h1 style="color: #ff6600; font-size: 250%; margin-top: 20px">ECMAScript Internationalization API Specification</h1>
</hgroup>
<div id="unofficial">
<p>This is the HTML rendering of <i>ECMA-402 Edition 1.0, ECMAScript Internationalization API Specification</i>.</p>
<p>The PDF rendering of this document is located at <a
href="http://www.ecma-international.org/ecma-402/1.0/ECMA-402.pdf">http://www.ecma-international.org/ecma-402/1.0/ECMA-402.pdf</a>.</p>
<p>The PDF version is the definitive specification. Any discrepancies between this HTML version and the PDF version are
unintentional.</p>
</div>
<section id="contents">
<h1>Contents</h1>
<ol class="toc">
<li>Introduction</li>
<li><span class="secnum"><a href="#sec-1" title="link to this section">1</a></span> Scope</li>
<li><span class="secnum"><a href="#sec-2" title="link to this section">2</a></span> Conformance</li>
<li><span class="secnum"><a href="#sec-3" title="link to this section">3</a></span> Normative References</li>
<li><span class="secnum"><a href="#sec-4" title="link to this section">4</a></span> Overview
<ol class="toc">
<li><span class="secnum"><a href="#sec-4.1" title="link to this section">4.1</a></span> Internationalization,
Localization, and Globalization</li>
<li><span class="secnum"><a href="#sec-4.2" title="link to this section">4.2</a></span> API Overview</li>
<li><span class="secnum"><a href="#sec-4.3" title="link to this section">4.3</a></span> Implementation Dependencies</li>
</ol>
</li>
<li><span class="secnum"><a href="#sec-5" title="link to this section">5</a></span> Notational Conventions</li>
<li><span class="secnum"><a href="#sec-6" title="link to this section">6</a></span> Identification of Locales, Time Zones, and
Currencies
<ol class="toc">
<li><span class="secnum"><a href="#sec-6.1" title="link to this section">6.1</a></span> Case Sensitivity and Case
Mapping</li>
<li><span class="secnum"><a href="#sec-6.2" title="link to this section">6.2</a></span> Language Tags
<ol class="toc">
<li><span class="secnum"><a href="#sec-6.2.1" title="link to this section">6.2.1</a></span> Unicode Locale Extension
Sequences</li>
<li><span class="secnum"><a href="#sec-6.2.2" title="link to this section">6.2.2</a></span>
IsStructurallyValidLanguageTag (locale)</li>
<li><span class="secnum"><a href="#sec-6.2.3" title="link to this section">6.2.3</a></span> CanonicalizeLanguageTag
(locale)</li>
<li><span class="secnum"><a href="#sec-6.2.4" title="link to this section">6.2.4</a></span> DefaultLocale ()</li>
</ol>
</li>
<li><span class="secnum"><a href="#sec-6.3" title="link to this section">6.3</a></span> Currency Codes
<ol class="toc">
<li><span class="secnum"><a href="#sec-6.3.1" title="link to this section">6.3.1</a></span> IsWellFormedCurrencyCode
(currency)</li>
</ol>
</li>
<li><span class="secnum"><a href="#sec-6.4" title="link to this section">6.4</a></span> Time Zone Names</li>
</ol>
</li>
<li><span class="secnum"><a href="#sec-7" title="link to this section">7</a></span> Requirements for Standard Built-in
ECMAScript Objects</li>
<li><span class="secnum"><a href="#sec-8" title="link to this section">8</a></span> The Intl Object
<ol class="toc">
<li><span class="secnum"><a href="#sec-8.1" title="link to this section">8.1</a></span> Properties of the Intl Object</li>
</ol>
</li>
<li><span class="secnum"><a href="#sec-9" title="link to this section">9</a></span> Locale and Parameter Negotiation
<ol class="toc">
<li><span class="secnum"><a href="#sec-9.1" title="link to this section">9.1</a></span> Internal Properties of Service
Constructors</li>
<li><span class="secnum"><a href="#sec-9.2" title="link to this section">9.2</a></span> Abstract Operations
<ol class="toc">
<li><span class="secnum"><a href="#sec-9.2.1" title="link to this section">9.2.1</a></span> CanonicalizeLocaleList
(locales)</li>
<li><span class="secnum"><a href="#sec-9.2.2" title="link to this section">9.2.2</a></span> BestAvailableLocale
(availableLocales, locale)</li>
<li><span class="secnum"><a href="#sec-9.2.3" title="link to this section">9.2.3</a></span> LookupMatcher
(availableLocales, requestedLocales)</li>
<li><span class="secnum"><a href="#sec-9.2.4" title="link to this section">9.2.4</a></span> BestFitMatcher
(availableLocales, requestedLocales)</li>
<li><span class="secnum"><a href="#sec-9.2.5" title="link to this section">9.2.5</a></span> ResolveLocale
(availableLocales, requestedLocales, options, relevantExtensionKeys, localeData)</li>
<li><span class="secnum"><a href="#sec-9.2.6" title="link to this section">9.2.6</a></span> LookupSupportedLocales
(availableLocales, requestedLocales)</li>
<li><span class="secnum"><a href="#sec-9.2.7" title="link to this section">9.2.7</a></span> BestFitSupportedLocales
(availableLocales, requestedLocales)</li>
<li><span class="secnum"><a href="#sec-9.2.8" title="link to this section">9.2.8</a></span> SupportedLocales
(availableLocales, requestedLocales, options)</li>
<li><span class="secnum"><a href="#sec-9.2.9" title="link to this section">9.2.9</a></span> GetOption (options,
property, type, values, fallback)</li>
<li><span class="secnum"><a href="#sec-9.2.10" title="link to this section">9.2.10</a></span> GetNumberOption
(options, property, minimum, maximum, fallback)</li>
</ol>
</li>
</ol>
</li>
<li><span class="secnum"><a href="#sec-10" title="link to this section">10</a></span> Collator Objects
<ol class="toc">
<li><span class="secnum"><a href="#sec-10.1" title="link to this section">10.1</a></span> The Intl.Collator Constructor
<ol class="toc">
<li><span class="secnum"><a href="#sec-10.1.1" title="link to this section">10.1.1</a></span> Initializing an Object
as a Collator</li>
<li><span class="secnum"><a href="#sec-10.1.2" title="link to this section">10.1.2</a></span> The Intl.Collator
Constructor Called as a Function</li>
<li><span class="secnum"><a href="#sec-10.1.3" title="link to this section">10.1.3</a></span> The Intl.Collator
Constructor Used in a new Expression</li>
</ol>
</li>
<li><span class="secnum"><a href="#sec-10.2" title="link to this section">10.2</a></span> Properties of the Intl.Collator
Constructor
<ol class="toc">
<li><span class="secnum"><a href="#sec-10.2.1" title="link to this section">10.2.1</a></span>
Intl.Collator.prototype</li>
<li><span class="secnum"><a href="#sec-10.2.2" title="link to this section">10.2.2</a></span>
Intl.Collator.supportedLocalesOf (locales [, options])</li>
<li><span class="secnum"><a href="#sec-10.2.3" title="link to this section">10.2.3</a></span> Internal Properties</li>
</ol>
</li>
<li><span class="secnum"><a href="#sec-10.3" title="link to this section">10.3</a></span> Properties of the Intl.Collator
Prototype Object
<ol class="toc">
<li><span class="secnum"><a href="#sec-10.3.1" title="link to this section">10.3.1</a></span>
Intl.Collator.prototype.constructor</li>
<li><span class="secnum"><a href="#sec-10.3.2" title="link to this section">10.3.2</a></span>
Intl.Collator.prototype.compare</li>
<li><span class="secnum"><a href="#sec-10.3.3" title="link to this section">10.3.3</a></span>
Intl.Collator.prototype.resolvedOptions ()</li>
</ol>
</li>
<li><span class="secnum"><a href="#sec-10.4" title="link to this section">10.4</a></span> Properties of Intl.Collator
Instances</li>
</ol>
</li>
<li><span class="secnum"><a href="#sec-11" title="link to this section">11</a></span> NumberFormat Objects
<ol class="toc">
<li><span class="secnum"><a href="#sec-11.1" title="link to this section">11.1</a></span> The Intl.NumberFormat
Constructor
<ol class="toc">
<li><span class="secnum"><a href="#sec-11.1.1" title="link to this section">11.1.1</a></span> Initializing an Object
as a NumberFormat</li>
<li><span class="secnum"><a href="#sec-11.1.2" title="link to this section">11.1.2</a></span> The Intl.NumberFormat
Constructor Called as a Function</li>
<li><span class="secnum"><a href="#sec-11.1.3" title="link to this section">11.1.3</a></span> The Intl.NumberFormat
Constructor Used in a new Expression</li>
</ol>
</li>
<li><span class="secnum"><a href="#sec-11.2" title="link to this section">11.2</a></span> Properties of the
Intl.NumberFormat Constructor
<ol class="toc">
<li><span class="secnum"><a href="#sec-11.2.1" title="link to this section">11.2.1</a></span>
Intl.NumberFormat.prototype</li>
<li><span class="secnum"><a href="#sec-11.2.2" title="link to this section">11.2.2</a></span>
Intl.NumberFormat.supportedLocalesOf (locales [, options])</li>
<li><span class="secnum"><a href="#sec-11.2.3" title="link to this section">11.2.3</a></span> Internal Properties</li>
</ol>
</li>
<li><span class="secnum"><a href="#sec-11.3" title="link to this section">11.3</a></span> Properties of the
Intl.NumberFormat Prototype Object
<ol class="toc">
<li><span class="secnum"><a href="#sec-11.3.1" title="link to this section">11.3.1</a></span>
Intl.NumberFormat.prototype.constructor</li>
<li><span class="secnum"><a href="#sec-11.3.2" title="link to this section">11.3.2</a></span>
Intl.NumberFormat.prototype.format</li>
<li><span class="secnum"><a href="#sec-11.3.3" title="link to this section">11.3.3</a></span>
Intl.NumberFormat.prototype.resolvedOptions ()</li>
</ol>
</li>
<li><span class="secnum"><a href="#sec-11.4" title="link to this section">11.4</a></span> Properties of Intl.NumberFormat
Instances</li>
</ol>
</li>
<li><span class="secnum"><a href="#sec-12" title="link to this section">12</a></span> DateTimeFormat Objects
<ol class="toc">
<li><span class="secnum"><a href="#sec-12.1" title="link to this section">12.1</a></span> The Intl.DateTimeFormat
Constructor
<ol class="toc">
<li><span class="secnum"><a href="#sec-12.1.1" title="link to this section">12.1.1</a></span> Initializing an Object
as a DateTimeFormat</li>
<li><span class="secnum"><a href="#sec-12.1.2" title="link to this section">12.1.2</a></span> The Intl.DateTimeFormat
Constructor Called as a Function</li>
<li><span class="secnum"><a href="#sec-12.1.3" title="link to this section">12.1.3</a></span> The Intl.DateTimeFormat
Constructor Used in a new Expression</li>
</ol>
</li>
<li><span class="secnum"><a href="#sec-12.2" title="link to this section">12.2</a></span> Properties of the
Intl.DateTimeFormat Constructor
<ol class="toc">
<li><span class="secnum"><a href="#sec-12.2.1" title="link to this section">12.2.1</a></span>
Intl.DateTimeFormat.prototype</li>
<li><span class="secnum"><a href="#sec-12.2.2" title="link to this section">12.2.2</a></span>
Intl.DateTimeFormat.supportedLocalesOf (locales [, options])</li>
<li><span class="secnum"><a href="#sec-12.2.3" title="link to this section">12.2.3</a></span> Internal Properties</li>
</ol>
</li>
<li><span class="secnum"><a href="#sec-12.3" title="link to this section">12.3</a></span> Properties of the
Intl.DateTimeFormat Prototype Object
<ol class="toc">
<li><span class="secnum"><a href="#sec-12.3.1" title="link to this section">12.3.1</a></span>
Intl.DateTimeFormat.prototype.constructor</li>
<li><span class="secnum"><a href="#sec-12.3.2" title="link to this section">12.3.2</a></span>
Intl.DateTimeFormat.prototype.format</li>
<li><span class="secnum"><a href="#sec-12.3.3" title="link to this section">12.3.3</a></span>
Intl.DateTimeFormat.prototype.resolvedOptions ()</li>
</ol>
</li>
<li><span class="secnum"><a href="#sec-12.4" title="link to this section">12.4</a></span> Properties of
Intl.DateTimeFormat Instances</li>
</ol>
</li>
<li><span class="secnum"><a href="#sec-13" title="link to this section">13</a></span> Locale Sensitive Functions of the
ECMAScript Language Specification
<ol class="toc">
<li><span class="secnum"><a href="#sec-13.1" title="link to this section">13.1</a></span> Properties of the String
Prototype Object
<ol class="toc">
<li><span class="secnum"><a href="#sec-13.1.1" title="link to this section">13.1.1</a></span>
String.prototype.localeCompare (that [, locales [, options]])</li>
</ol>
</li>
<li><span class="secnum"><a href="#sec-13.2" title="link to this section">13.2</a></span> Properties of the Number
Prototype Object
<ol class="toc">
<li><span class="secnum"><a href="#sec-13.2.1" title="link to this section">13.2.1</a></span>
Number.prototype.toLocaleString ([locales [, options]])</li>
</ol>
</li>
<li><span class="secnum"><a href="#sec-13.3" title="link to this section">13.3</a></span> Properties of the Date Prototype
Object
<ol class="toc">
<li><span class="secnum"><a href="#sec-13.3.1" title="link to this section">13.3.1</a></span>
Date.prototype.toLocaleString ([locales [, options]])</li>
<li><span class="secnum"><a href="#sec-13.3.2" title="link to this section">13.3.2</a></span>
Date.prototype.toLocaleDateString ([locales [, options]])</li>
<li><span class="secnum"><a href="#sec-13.3.3" title="link to this section">13.3.3</a></span>
Date.prototype.toLocaleTimeString ([locales [, options]])</li>
</ol>
</li>
</ol>
</li>
<li><span class="secnum"><a href="#sec-A" title="link to this section">Annex A </a></span> <span
class="section-status">(informative)</span> Implementation Dependent Behaviour</li>
</ol>
</section>
<section>
<h1>Introduction</h1>
<p>The ECMAScript Internationalization API provides key language-sensitive functionality as a complement to the ECMAScript
Language Specification, 5.1 edition or successor. Its functionality has been selected from that of well-established
internationalization APIs such as those of the Internationalization Components for Unicode (ICU) library, of the .NET framework,
or of the Java platform.</p>
<p>The API was developed by an ad-hoc group established by Ecma TC 39 in September 2010 based on a proposal by Nebojša Ćirić and
Jungshik Shin.</p>
<p>Internationalization of software is never complete. We expect significant enhancements in future editions of this
specification.</p>
<p><b>Editor</b></p>
<p>Norbert Lindenberg</p>
<p><b>Contributors</b></p>
<p>Eric Albright</p>
<p>Nebojša Ćirić</p>
<p>Peter Constable</p>
<p>Mark Davis</p>
<p>Richard Gillam</p>
<p>Steven Loomis</p>
<p>Mihai Nita</p>
<p>Addison Phillips</p>
<p>Roozbeh Pournader</p>
<p>Jungshik Shin</p>
<p>Shawn Steele</p>
<p>Allen Wirfs-Brock</p>
<p>Feedback provided by Erik Arvidsson, John J. Barton, Zbigniew Braniecki, Marcos Cáceres, Brendan Eich, John Emmons, Gordon P.
Hemsley, David Herman, Luke Hoban, Oliver Hunt, Suresh Jayabalan, Yehuda Katz, Mark S. Miller, Andrew Paprocki, Adam Peller,
Axel Rauschmayer, Andreas Rossberg, Alex Russell, Markus Scherer, Dmitry Soshnikov, Yusuke Suzuki, John Tamplin, Rick Waldron,
Anton Yatsenko, Nicholas Zakas.</p>
<p>This Ecma Standard has been adopted by the General Assembly of December 2012.</p>
<p><i>COPYRIGHT NOTICE</i></p>
<p><i>© 2012 Ecma International</i></p>
<p><i>This document may be copied, published and distributed to others, and certain derivative works of it may be prepared,
copied, published, and distributed, in whole or in part, provided that the above copyright notice and this Copyright License and
Disclaimer are included on all such copies and derivative works. The only derivative works that are permissible under this
Copyright License and Disclaimer are:</i></p>
<p><i>(i)</i> <i>works which incorporate all or portion of this document for the purpose of providing commentary or explanation
(such as an annotated version of the document),</i></p>
<p><i>(ii)</i> <i>works which incorporate all or portion of this document for the purpose of incorporating features that provide
accessibility,</i></p>
<p><i>(iii)</i> <i>translations of this document into languages other than English and into different formats and</i></p>
<p><i>(iv)</i> <i>works by making use of this specification in standard conformant products by implementing (e.g. by copy and
paste wholly or partly) the functionality therein.</i></p>
<p><i>However, the content of this document itself may not be modified in any way, including by removing the copyright notice or
references to Ecma International, except as required to translate it into languages other than English or into a different
format.</i></p>
<p><i>The official version of an Ecma International document is the English language version on the Ecma International website.
In the event of discrepancies between a translated version and the official version, the official version shall govern.</i></p>
<p><i>The limited permissions granted above are perpetual and will not be revoked by Ecma International or its successors or
assigns.</i></p>
<p><i>This document and the information contained herein is provided on an "AS IS" basis and ECMA INTERNATIONAL DISCLAIMS ALL
WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT
INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.</i></p>
</section>
<div class="inner-title">ECMAScript Internationalization API Specification </div>
<section id="sec-1">
<h1><span class="secnum"><a href="#sec-1" title="link to this section">1</a></span> Scope</h1>
<p>This Standard defines the application programming interface for ECMAScript objects that support programs that need to adapt
to the linguistic and cultural conventions used by different human languages and countries.</p>
</section>
<section id="sec-2">
<h1><span class="secnum"><a href="#sec-2" title="link to this section">2</a></span> Conformance</h1>
<p>A conforming implementation of the ECMAScript Internationalization API must conform to the ECMAScript Language Specification,
5.1 edition or successor, and must provide and support all the objects, properties, functions, and program semantics described
in this specification.</p>
<p>A conforming implementation of the ECMAScript Internationalization API is permitted to provide additional objects,
properties, and functions beyond those described in this specification. In particular, a conforming implementation of the
ECMAScript Internationalization API is permitted to provide properties not described in this specification, and values for those
properties, for objects that are described in this specification. A conforming implementation is not permitted to add optional
arguments to the functions defined in this specification.</p>
<p>A conforming implementation is permitted to accept additional values, and then have implementation-defined behaviour instead
of throwing a <b>RangeError</b>, for the following properties of <var>options</var> arguments:</p>
<ul>
<li>
<p>The <var>options</var> property localeMatcher in all constructors and supportedLocalesOf methods.</p>
</li>
<li>
<p>The <var>options</var> properties usage and sensitivity in the Collator constructor.</p>
</li>
<li>
<p>The <var>options</var> properties style and currencyDisplay in the NumberFormat constructor.</p>
</li>
<li>
<p>The <var>options</var> properties minimumIntegerDigits, minimumFractionDigits, maximumFractionDigits,
minimumSignificantDigits, and maximumSignificantDigits in the NumberFormat constructor, provided that the additional values
are interpreted as integer values higher than the specified limits.</p>
</li>
<li>
<p>The <var>options</var> property timeZone in the DateTimeFormat constructor, provided that the additional acceptable input
values are case-insensitive matches of Zone or Link identifiers in the IANA time zone database and are canonicalized to Zone
identifiers in the casing used in the database for the timeZone property of the object returned by
DateTimeFormat.resolvedOptions, except that "Etc/GMT" shall be canonicalized to "UTC".</p>
</li>
<li>
<p>The <var>options</var> properties listed in table 3 in the DateTimeFormat constructor.</p>
</li>
<li>
<p>The <var>options</var> property formatMatcher in the DateTimeFormat constructor.</p>
</li>
</ul>
</section>
<section id="sec-3">
<h1><span class="secnum"><a href="#sec-3" title="link to this section">3</a></span> Normative References</h1>
<p>The following referenced documents are required for the application of this document. For dated references, only the edition
cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.</p>
<p>ECMA-262, ECMAScript Language Specification, 5.1 edition or successor<br><a
href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">http://www.ecma-international.org/publications/standards/Ecma-262.htm</a></p>
<div class="note">
<p><span class="nh">NOTE</span> Throughout this document, the phrase “ES5, <i>x</i>”, where <i>x</i> is a sequence of numbers
separated by periods, may be used as shorthand for “ECMAScript Language Specification, 5.1 edition, subclause <i>x</i>”.</p>
</div>
<p>ISO/IEC 10646:2003: Information Technology – Universal Multiple-Octet Coded Character Set (UCS) plus Amendment 1:2005 and
Amendment 2:2006, plus additional amendments and corrigenda, or successor<br><a
href="http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=39921">http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=39921</a><br><a
href="http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=40755">http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=40755</a><br><a
href="http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=41419">http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=41419</a></p>
<p>ISO 4217:2008, Codes for the representation of currencies and funds, or successor<br><a
href="http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=46121">http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=46121</a></p>
<p>IETF BCP 47:</p>
<ul>
<li>
<p>RFC 5646, Tags for Identifying Languages, or successor<br><a
href="http://tools.ietf.org/html/rfc5646">http://tools.ietf.org/html/rfc5646</a></p>
</li>
<li>
<p>RFC 4647, Matching of Language Tags, or successor<br><a
href="http://tools.ietf.org/html/rfc4647">http://tools.ietf.org/html/rfc4647</a></p>
</li>
</ul>
<p>IETF RFC 6067, BCP 47 Extension U, or successor<br><a
href="http://tools.ietf.org/html/">http://tools.ietf.org/html/</a>rfc6067</p>
<p>IANA Time Zone Database<br><a href="http://www.iana.org/time-zones/">http://www.iana.org/time-zones/</a></p>
<p>The Unicode Standard<i>, Version 5.0</i>, or successor<br><a
href="http://www.unicode.org/versions/latest">http://www.unicode.org/versions/latest</a></p>
<p>Unicode Technical Standard 35, Unicode Locale Data Markup Language, version 21.0.1 or successor<br><a
href="http://unicode.org/reports/tr35/">http://unicode.org/reports/tr35/</a></p>
</section>
<section id="sec-4">
<h1><span class="secnum"><a href="#sec-4" title="link to this section">4</a></span> Overview</h1>
<p>This section contains a non-normative overview of the ECMAScript Internationalization API.</p>
<section id="sec-4.1">
<h1><span class="secnum"><a href="#sec-4.1" title="link to this section">4.1</a></span> Internationalization, Localization,
and Globalization</h1>
<p>Internationalization of software means designing it such that it supports or can be easily adapted to support the needs of
users speaking different languages and having different cultural expectations, and enables worldwide communication between
them. Localization then is the actual adaptation to a specific language and culture. Globalization of software is commonly
understood to be the combination of internationalization and localization. Globalization starts at the lowest level by using a
text representation that supports all languages in the world, and using standard identifiers to identify languages, countries,
time zones, and other relevant parameters. It continues with using a user interface language and data presentation that the
user understands, and finally often requires product-specific adaptations to the user’s language, culture, and
environment.</p>
<p>The ECMAScript Language Specification lays the foundation by using Unicode for text representation and by providing a few
language-sensitive functions, but gives applications little control over the behaviour of these functions. The ECMAScript
Internationalization API builds on this by providing a set of customizable language-sensitive functionality. The API is useful
even for applications that themselves are not internationalized, as even applications targeting only one language and one
region need to properly support that one language and region. However, the API also enables applications that support multiple
languages and regions, even concurrently, as may be needed in server environments.</p>
</section>
<section id="sec-4.2">
<h1><span class="secnum"><a href="#sec-4.2" title="link to this section">4.2</a></span> API Overview</h1>
<p>The ECMAScript Internationalization API is designed to complement the ECMAScript Language Specification by providing key
language-sensitive functionality. The API can be added to an implementation of the ECMAScript Language Specification, 5.1
edition or successor.</p>
<p>The ECMAScript Internationalization API provides three key pieces of language-sensitive functionality that are required in
most applications: String comparison (collation), number formatting, and date and time formatting. While the ECMAScript
Language Specification provides functions for this basic functionality (String.prototype.localeCompare,
Number.prototype.toLocaleString, Date.prototype.toLocaleString, Date.prototype.toLocaleDateString, and
Date.prototype.toLocaleTimeString), it leaves the actual behaviour of these functions largely up to implementations to define.
The Internationalization API Specification provides additional functionality, control over the language and over details of
the behaviour to be used, and a more complete specification of required functionality.</p>
<p>Applications can use the API in two ways:</p>
<ol class="proc">
<li>Directly, by using the constructors Intl.Collator, Intl.NumberFormat, or Intl.DateTimeFormat to construct an object,
specifying a list of preferred languages and options to configure the behaviour of the resulting object. The object then
provides a main function (compare or format), which can be called repeatedly. It also provides a resolvedOptions
function, which the application can use to find out the exact configuration of the object.</li>
<li>Indirectly, by using the functions of the ECMAScript Language Specification mentioned above, which are respecified in
this specification to accept the same arguments as the Collator, NumberFormat, and DateTimeFormat constructors and
produce the same results as their compare or format methods.</li>
</ol>
<p>The Intl object is used to package all functionality defined in the ECMAScript Internationalization API to avoid name
collisions.</p>
</section>
<section id="sec-4.3">
<h1><span class="secnum"><a href="#sec-4.3" title="link to this section">4.3</a></span> Implementation Dependencies</h1>
<p>Due to the nature of internationalization, the API specification has to leave several details implementation dependent:</p>
<ul>
<li>
<p><i>The set of locales that an implementation supports with adequate localizations:</i> Linguists estimate the number of
human languages to around 6000, and the more widely spoken ones have variations based on regions or other parameters. Even
large locale data collections, such as the Common Locale Data Repository, cover only a subset of this large set.
Implementations targeting resource-constrained devices may have to further reduce the subset.</p>
</li>
<li>
<p><i>The exact form of localizations such as format patterns:</i> In many cases locale-dependent conventions are not
standardized, so different forms may exist side by side, or they vary over time. Different internationalization libraries
may have implemented different forms, without any of them being actually wrong. In order to allow this API to be
implemented on top of existing libraries, such variations have to be permitted.</p>
</li>
<li>
<p><i>Subsets of Unicode:</i> Some operations, such as collation, operate on strings that can include characters from the
entire Unicode character set. However, both the Unicode standard and the ECMAScript standard allow implementations to
limit their functionality to subsets of the Unicode character set. In addition, locale conventions typically don’t specify
the desired behaviour for the entire Unicode character set, but only for those characters that are relevant for the
locale. While the Unicode Collation Algorithm combines a default collation order for the entire Unicode character set with
the ability to tailor for local conventions, subsets and tailorings still result in differences in behaviour.</p>
</li>
</ul>
</section>
</section>
<section id="sec-5">
<h1><span class="secnum"><a href="#sec-5" title="link to this section">5</a></span> Notational Conventions</h1>
<p>This standard uses a subset of the notational conventions of the ECMAScript Language Specification, 5.1 edition:</p>
<ul>
<li>Algorithm conventions, including the use of abstract operations, as described in <a
href="http://ecma-international.org/ecma-262/5.1/#sec-5.2">ES5, 5.2</a>.</li>
<li>Internal properties, as described in <a href="http://ecma-international.org/ecma-262/5.1/#sec-8.6.2">ES5, 8.6.2</a>.</li>
<li>The List specification type, as described in <a href="http://ecma-international.org/ecma-262/5.1/#sec-8.8">ES5,
8.8</a>.</li>
</ul>
<div class="note">
<p><span class="nh">NOTE</span> As described in the ECMAScript Language Specification, algorithms are used to precisely
specify the required semantics of ECMAScript constructs, but are not intended to imply the use of any specific implementation
technique. Internal properties are used to define the semantics of object values, but are not part of the API. They are
defined purely for expository purposes. An implementation of the API must behave as if it produced and operated upon internal
properties in the manner described here.</p>
</div>
<p>In addition, the Record specification type is used to describe data aggregations within the algorithms of this specification.
A Record type value consists of one or more named fields. The value of each field is an ECMAScript type value. Field names are
always enclosed in double brackets, for example [[field1]]. Field names can also be provided by a variable: The notation
“[[<<var>name</var>>]]” denotes a field whose name is given by the variable <var>name</var>, which must have a String
value. For example, if a variable <var>s</var> has the value <code>"a"</code>, then [[<<var>s</var>>]] denotes the field
[[a]].</p>
<p>In specification text and algorithms, dot notation may be used to refer to a specific field of a Record value. For example,
if <var>r</var> is a record, then <var>r</var>.[[field1]] is shorthand for “the field of <var>r</var> named [[field1]]”.</p>
<p>For ECMAScript objects, this standard may use variable-named internal properties: The notation “[[<<var>name</var>>]]”
denotes an internal property whose name is given by the variable <var>name</var>, which must have a String value. For example,
if a variable <var>s</var> has the value <code>"a"</code>, then [[<<var>s</var>>]] denotes the [[a]] internal
property.</p>
</section>
<section id="sec-6">
<h1><span class="secnum"><a href="#sec-6" title="link to this section">6</a></span> Identification of Locales, Time Zones, and
Currencies</h1>
<p>This clause describes the String values used in the ECMAScript Internationalization API to identify locales, currencies, and
time zones.</p>
<section id="sec-6.1">
<h1><span class="secnum"><a href="#sec-6.1" title="link to this section">6.1</a></span> Case Sensitivity and Case Mapping</h1>
<p>The String values used to identify locales, currencies, and time zones are interpreted in a case-insensitive manner,
treating the Unicode Basic Latin characters "A" to "Z" (U+0041 to U+005A) as equivalent to the corresponding Basic Latin
characters "a" to "z" (U+0061 to U+007A). No other case folding equivalences are applied. When mapping to upper case, a
mapping shall be used that maps characters in the range "a" to "z" (U+0061 to U+007A) to the corresponding characters in the
range "A" to "Z" (U+0041 to U+005A) and maps no other characters to the latter range.</p>
<div class="note">
<p><span class="nh">EXAMPLES</span> "ß" (U+00DF) must not match or be mapped to "SS" (U+0053, U+0053). "ı" (U+0131) must not
match or be mapped to "I" (U+0049).</p>
</div>
</section>
<section id="sec-6.2">
<h1><span class="secnum"><a href="#sec-6.2" title="link to this section">6.2</a></span> Language Tags</h1>
<p>The ECMAScript Internationalization API identifies locales using language tags as defined by IETF BCP 47 (RFCs 5646 and
4647 or their successors), which may include extensions such as those registered through RFC 6067. Their canonical form is
specified in RFC 5646 section 4.5 or its successor.</p>
<p>BCP 47 language tags that meet those validity criteria of RFC 5646 section 2.2.9 that can be verified without reference to
the IANA Language Subtag Registry are considered structurally valid. All structurally valid language tags are valid for use
with the APIs defined by this standard. However, the set of locales and thus language tags that an implementation supports
with adequate localizations is implementation dependent. The constructors Collator, NumberFormat, and DateTimeFormat map the
language tags used in requests to locales supported by their respective implementations.</p>
<section id="sec-6.2.1">
<h1><span class="secnum"><a href="#sec-6.2.1" title="link to this section">6.2.1</a></span> Unicode Locale Extension
Sequences</h1>
<p>This standard uses the term “Unicode locale extension sequence” for any substring of a language tag that starts with a
separator "-" and the singleton "u" and includes the maximum sequence of following non-singleton subtags and their preceding
"-" separators.</p>
</section>
<section id="sec-6.2.2">
<h1><span class="secnum"><a href="#sec-6.2.2" title="link to this section">6.2.2</a></span> IsStructurallyValidLanguageTag
(locale)</h1>
<p>The IsStructurallyValidLanguageTag abstract operation verifies that the <var>locale</var> argument (which must be a
String value)</p>
<ul>
<li>represents a well-formed BCP 47 language tag as specified in RFC 5646 section 2.1, or successor,</li>
<li>does not include duplicate variant subtags, and</li>
<li>does not include duplicate singleton subtags.</li>
</ul>
<p>The abstract operation returns true if <var>locale</var> can be generated from the ABNF grammar in section 2.1 of the
RFC, starting with Language-Tag, and does not contain duplicate variant or singleton subtags (other than as a private use
subtag). It returns false otherwise. Terminal value characters in the grammar are interpreted as the Unicode equivalents of
the ASCII octet values given.</p>
</section>
<section id="sec-6.2.3">
<h1><span class="secnum"><a href="#sec-6.2.3" title="link to this section">6.2.3</a></span> CanonicalizeLanguageTag
(locale)</h1>
<p>The CanonicalizeLanguageTag abstract operation returns the canonical and case-regularized form of the locale argument
(which must be a String value that is a structurally valid BCP 47 language tag as verified by the <a
href="#sec-6.2.2">IsStructurallyValidLanguageTag</a> abstract operation). It takes the steps specified in RFC 5646 section
4.5, or successor, to bring the language tag into canonical form, and to regularize the case of the subtags, but does not
take the steps to bring a language tag into “extlang form” and to reorder variant subtags.</p>
<p>The specifications for extensions to BCP 47 language tags, such as RFC 6067, may include canonicalization rules for the
extension subtag sequences they define that go beyond the canonicalization rules of RFC 5646 section 4.5. Implementations
are allowed, but not required, to apply these additional rules.</p>
</section>
<section id="sec-6.2.4">
<h1><span class="secnum"><a href="#sec-6.2.4" title="link to this section">6.2.4</a></span> DefaultLocale ()</h1>
<p>The DefaultLocale abstract operation returns a String value representing the structurally valid (<a
href="#sec-6.2.2">6.2.2</a>) and canonicalized (<a href="#sec-6.2.3">6.2.3</a>) BCP 47 language tag for the host
environment’s current locale.</p>
</section>
</section>
<section id="sec-6.3">
<h1><span class="secnum"><a href="#sec-6.3" title="link to this section">6.3</a></span> Currency Codes</h1>
<p>The ECMAScript Internationalization API identifies currencies using 3-letter currency codes as defined by ISO 4217. Their
canonical form is upper case.</p>
<p>All well-formed 3-letter ISO 4217 currency codes are allowed. However, the set of combinations of currency code and
language tag for which localized currency symbols are available is implementation dependent. Where a localized currency symbol
is not available, the ISO 4217 currency code is used for formatting.</p>
<section id="sec-6.3.1">
<h1><span class="secnum"><a href="#sec-6.3.1" title="link to this section">6.3.1</a></span> IsWellFormedCurrencyCode
(currency)</h1>
<p>The IsWellFormedCurrencyCode abstract operation verifies that the currency argument (after conversion to a String value)
represents a well-formed 3-letter ISO currency code. The following steps are taken:</p>
<ol class="proc">
<li>Let <i>c</i> be ToString(<i>currency</i>).</li>
<li>Let <i>normalized</i> be the result of mapping <i>c</i> to upper case as described in <a href="#sec-6.1">6.1</a>.</li>
<li>If the string length of <i>normalized</i> is not 3, return <b>false</b>.</li>
<li>If <i>normalized</i> contains any character that is not in the range "A" to "Z" (U+0041 to U+005A), return
<b>false</b>.</li>
<li>Return <b>true</b>.</li>
</ol>
</section>
</section>
<section id="sec-6.4">
<h1><span class="secnum"><a href="#sec-6.4" title="link to this section">6.4</a></span> Time Zone Names</h1>
<p>The ECMAScript Internationalization API defines a single time zone name, <code>"UTC"</code>, which identifies the UTC time
zone.</p>
<p>The Intl.DateTimeFormat constructor allows this time zone name; if the time zone is not specified, the host environment’s
current time zone is used. Implementations shall support UTC and the host environment’s current time zone (if different from
UTC) in formatting.</p>
<div class="note">
<p><span class="nh">NOTE</span> The Conformance clause allows implementations to accept additional time zone names under
specified conditions.</p>
</div>
</section>
</section>
<section id="sec-7">
<h1><span class="secnum"><a href="#sec-7" title="link to this section">7</a></span> Requirements for Standard Built-in
ECMAScript Objects</h1>
<p>Unless specified otherwise in this document, the objects, functions, and constructors described in this standard are subject
to the generic requirements and restrictions specified for standard built-in ECMAScript objects in the ECMAScript Language
Specification 5.1 edition, <a href="http://ecma-international.org/ecma-262/5.1/#sec-15">introduction of clause 15</a>, or
successor.</p>
</section>
<section id="sec-8">
<h1><span class="secnum"><a href="#sec-8" title="link to this section">8</a></span> The Intl Object</h1>
<p>The Intl object is a standard built-in object that is the initial value of the <code>Intl</code> property of the global
object.</p>
<p>The value of the [[Prototype]] internal property of the Intl object is the built-in Object prototype object specified by the
ECMAScript Language Specification.</p>
<p>The Intl object does not have a [[Construct]] internal property; it is not possible to use the Intl object as a constructor
with the new operator.</p>
<p>The Intl object does not have a [[Call]] internal property; it is not possible to invoke the Intl object as a function.</p>
<section id="sec-8.1">
<h1><span class="secnum"><a href="#sec-8.1" title="link to this section">8.1</a></span> Properties of the Intl Object</h1>
<p>The value of each of the standard built-in properties of the Intl object is a constructor. The behaviour of these
constructors is specified in the following clauses: Collator (<a href="#sec-10">10</a>), NumberFormat (<a
href="#sec-11">11</a>), and DateTimeFormat (<a href="#sec-12">12</a>).</p>
</section>
</section>
<section id="sec-9">
<h1><span class="secnum"><a href="#sec-9" title="link to this section">9</a></span> Locale and Parameter Negotiation</h1>
<p>The constructors for the objects providing locale sensitive services, Collator, NumberFormat, and DateTimeFormat, use a
common pattern to negotiate the requests represented by the locales and options arguments against the actual capabilities of
their implementations. The common behaviour is described here in terms of internal properties describing the capabilities and of
abstract operations using these internal properties.</p>
<section id="sec-9.1">
<h1><span class="secnum"><a href="#sec-9.1" title="link to this section">9.1</a></span> Internal Properties of Service
Constructors</h1>
<p>The constructors Intl.Collator, Intl.NumberFormat, and Intl.DateTimeFormat have the following internal properties:</p>
<ul>
<li>
<p>[[availableLocales]] is a <a href="#sec-5">List</a> that contains structurally valid (<a href="#sec-6.2.2">6.2.2</a>)
and canonicalized (<a href="#sec-6.2.3">6.2.3</a>) BCP 47 language tags identifying the locales for which the
implementation provides the functionality of the constructed objects. Language tags on the list must not have a Unicode
locale extension sequence. The list must include the value returned by the <a href="#sec-6.2.4">DefaultLocale</a> abstract
operation (<a href="#sec-6.2.4">6.2.4</a>), and must not include duplicates. Implementations must include in
[[availableLocales]] locales that can serve as fallbacks in the algorithm used to resolve locales (see <a
href="#sec-9.2.5">9.2.5</a>). For example, implementations that provide a "de-DE" locale must include a "de" locale that
can serve as a fallback for requests such as "de-AT" and "de-CH". For locales that in current usage would include a script
subtag (such as Chinese locales), old-style language tags without script subtags must be included such that, for example,
requests for "zh-TW" and "zh-HK" lead to output in traditional Chinese rather than the default simplified Chinese. The
ordering of the locales within [[availableLocales]] is irrelevant.</p>
</li>
<li>
<p>[[relevantExtensionKeys]] is an array of keys of the language tag extensions defined in Unicode Technical Standard 35
that are relevant for the functionality of the constructed objects.</p>
</li>
<li>
<p>[[sortLocaleData]] and [[searchLocaleData]] (for Intl.Collator) and [[localeData]] (for Intl.NumberFormat and
Intl.DateTimeFormat) are objects that have properties for each locale contained in [[availableLocales]]. The value of each
of these properties must be an object that has properties for each key contained in [[relevantExtensionKeys]]. The value
of each of these properties must be a non-empty array of those values defined in Unicode Technical Standard 35 for the
given key that are supported by the implementation for the given locale, with the first element providing the default
value.</p>
</li>
</ul>
<div class="note">
<p><span class="nh">EXAMPLE</span> An implementation of DateTimeFormat might include the language tag "th" in its
[[availableLocales]] internal property, and must (according to <a href="#sec-12.2.3">12.2.3</a>) include the key "ca" in its
[[relevantExtensionKeys]] internal property. For Thai, the "buddhist" calendar is usually the default, but an implementation
might also support the calendars "gregory", "chinese", and "islamicc" for the locale "th". The [[localeData]] internal
property would therefore at least include {"th": {ca: ["buddhist", "gregory", "chinese", "islamicc"]}}.</p>
</div>
</section>
<section id="sec-9.2">
<h1><span class="secnum"><a href="#sec-9.2" title="link to this section">9.2</a></span> Abstract Operations</h1>
<p>Where the following abstract operations take an <var>availableLocales</var> argument, it must be an [[availableLocales]] <a
href="#sec-5">List</a> as specified in <a href="#sec-9.1">9.1</a>.</p>
<section id="sec-9.2.1">
<h1><span class="secnum"><a href="#sec-9.2.1" title="link to this section">9.2.1</a></span> CanonicalizeLocaleList
(locales)</h1>
<p>The abstract operation CanonicalizeLocaleList takes the following steps:</p>
<ol class="proc">
<li>If <i>locales</i> is <b>undefined</b>, then
<ol class="block">
<li>Return a new empty <a href="#sec-5">List</a>.</li>
</ol>
</li>
<li>Let <i>seen</i> be a new empty <a href="#sec-5">List</a>.</li>
<li>If <i>locales</i> is a String value, then
<ol class="block">
<li>Let <i>locales</i> be a new array created as if by the expression <code>new Array(locales)</code> where
<code>Array</code> is the standard built-in constructor with that name and <i>locales</i> is the value of
<i>locales</i>.</li>
</ol>
</li>
<li>Let <i>O</i> be ToObject(<i>locales</i>).</li>
<li>Let <i>lenValue</i> be the result of calling the [[Get]] internal method of <i>O</i> with the argument
<code>"length"</code>.</li>
<li>Let <i>len</i> be ToUint32(<i>lenValue</i>).</li>
<li>Let <i>k</i> be 0.</li>
<li>Repeat, while <i>k</i> < <i>len</i>
<ol class="block">
<li>Let <i>Pk</i> be ToString(<i>k</i>).</li>
<li>Let <i>kPresent</i> be the result of calling the [[HasProperty]] internal method of <i>O</i> with argument
<i>Pk</i>.</li>
<li>If <i>kPresent</i> is <b>true</b>, then
<ol class="block">
<li>Let <i>kValue</i> be the result of calling the [[Get]] internal method of <i>O</i> with argument
<i>Pk</i>.</li>
<li>If the type of <i>kValue</i> is not String or Object, then throw a <b>TypeError</b> exception.</li>
<li>Let <i>tag</i> be ToString(<i>kValue</i>).</li>
<li>If the result of calling the abstract operation <a href="#sec-6.2.2">IsStructurallyValidLanguageTag</a>
(defined in <a href="#sec-6.2.2">6.2.2</a>), passing <i>tag</i> as the argument, is <b>false</b>, then throw a
<b>RangeError</b> exception.</li>
<li>Let <i>tag</i> be the result of calling the abstract operation <a
href="#sec-6.2.3">CanonicalizeLanguageTag</a> (defined in <a href="#sec-6.2.3">6.2.3</a>), passing <i>tag</i>
as the argument.</li>
<li>If <i>tag</i> is not an element of <i>seen</i>, then append <i>tag</i> as the last element of
<i>seen</i>.</li>
</ol>
</li>
<li>Increase <i>k</i> by 1.</li>
</ol>
</li>
<li>Return <i>seen</i>.</li>
</ol>
<div class="note">
<p><span class="nh">NOTE</span> Non-normative summary: The abstract operation interprets the <var>locales</var> argument
as an array and copies its elements into a <a href="#sec-5">List</a>, validating the elements as structurally valid
language tags and canonicalizing them, and omitting duplicates.</p>
</div>
<div class="note">
<p><span class="nh">NOTE</span> Requiring <var>kValue</var> to be a String or Object means that the Number value
<b>NaN</b> will not be interpreted as the language tag <code>"nan"</code>, which stands for Min Nan Chinese.</p>
</div>
</section>
<section id="sec-9.2.2">
<h1><span class="secnum"><a href="#sec-9.2.2" title="link to this section">9.2.2</a></span> BestAvailableLocale
(availableLocales, locale)</h1>
<p>The BestAvailableLocale abstract operation compares the provided argument <var>locale</var>, which must be a String value
with a structurally valid and canonicalized BCP 47 language tag, against the locales in <var>availableLocales</var> and
returns either the longest non-empty prefix of <var>locale</var> that is an element of <var>availableLocales</var>, or
<b>undefined</b> if there is no such element. It uses the fallback mechanism of RFC 4647, section 3.4. The following steps
are taken:</p>
<ol class="proc">
<li>Let <i>candidate</i> be <i>locale</i>.</li>
<li>Repeat
<ol class="block">
<li>If <i>availableLocales</i> contains an element equal to <i>candidate</i>, then return <i>candidate</i>.</li>
<li>Let <i>pos</i> be the character index of the last occurrence of <code>"-"</code> (U+002D) within <i>candidate</i>.
If that character does not occur, return <b>undefined</b>.</li>
<li>If <i>pos</i> ≥ 2 and the character <code>"-"</code> occurs at index <i>pos</i>-2 of <i>candidate</i>, then
decrease <i>pos</i> by 2.</li>
<li>Let <i>candidate</i> be the substring of <i>candidate</i> from position 0, inclusive, to position <i>pos</i>,
exclusive.</li>
</ol>
</li>
</ol>
</section>
<section id="sec-9.2.3">
<h1><span class="secnum"><a href="#sec-9.2.3" title="link to this section">9.2.3</a></span> LookupMatcher (availableLocales,
requestedLocales)</h1>
<p>The LookupMatcher abstract operation compares <var>requestedLocales</var>, which must be a <a href="#sec-5">List</a> as
returned by <a href="#sec-9.2.1">CanonicalizeLocaleList</a>, against the locales in <var>availableLocales</var> and
determines the best available language to meet the request. The following steps are taken:</p>
<ol class="proc">
<li>Let <i>i</i> be 0.</li>
<li>Let <i>len</i> be the number of elements in <i>requestedLocales</i>.</li>
<li>Let <i>availableLocale</i> be <b>undefined</b>.</li>
<li>Repeat while <i>i</i> < <i>len</i> and <i>availableLocale</i> is <b>undefined</b>:
<ol class="block">
<li>Let <i>locale</i> be the element of <i>requestedLocales</i> at 0-origined list position <i>i</i>.</li>
<li>Let <i>noExtensionsLocale</i> be the String value that is <i>locale</i> with all Unicode locale extension
sequences removed.</li>
<li>Let <i>availableLocale</i> be the result of calling the <a href="#sec-9.2.2">BestAvailableLocale</a> abstract
operation (defined in <a href="#sec-9.2.2">9.2.2</a>) with arguments <i>availableLocales</i> and
<i>noExtensionsLocale</i>.</li>
<li>Increase <i>i</i> by 1.</li>
</ol>
</li>
<li>Let <i>result</i> be a new <a href="#sec-5">Record</a>.</li>
<li>If <i>availableLocale</i> is not <b>undefined</b>, then
<ol class="block">
<li>Set <i>result</i>.[[locale]] to <i>availableLocale</i>.</li>
<li>If <i>locale</i> and <i>noExtensionsLocale</i> are not the same String value, then
<ol class="block">
<li>Let <i>extension</i> be the String value consisting of the first substring of <i>locale</i> that is a Unicode
locale extension sequence.</li>
<li>Let <i>extensionIndex</i> be the character position of the initial <code>"-"</code> of the first Unicode
locale extension sequence within <i>locale</i>.</li>
<li>Set <i>result</i>.[[extension]] to <i>extension</i>.</li>
<li>Set <i>result</i>.[[extensionIndex]] to <i>extensionIndex</i>.</li>
</ol>
</li>
</ol>
</li>
<li>Else
<ol class="block">
<li>Set <i>result</i>.[[locale]] to the value returned by the <a href="#sec-6.2.4">DefaultLocale</a> abstract
operation (defined in <a href="#sec-6.2.4">6.2.4</a>).</li>
</ol>
</li>
<li>Return <i>result</i>.</li>
</ol>
<div class="note">
<p><span class="nh">NOTE</span> The algorithm is based on the Lookup algorithm described in RFC 4647 section 3.4, but
options specified through Unicode locale extension sequences are ignored in the lookup. Information about such
subsequences is returned separately. The abstract operation returns a record with a [[locale]] field, whose value is the
language tag of the selected locale, which must be an element of <var>availableLocales</var>. If the language tag of the
request locale that led to the selected locale contained a Unicode locale extension sequence, then the returned record
also contains an [[extension]] field whose value is the first Unicode locale extension sequence, and an [[extensionIndex]]
field whose value is the index of the first Unicode locale extension sequence within the request locale language tag.</p>
</div>
</section>
<section id="sec-9.2.4">
<h1><span class="secnum"><a href="#sec-9.2.4" title="link to this section">9.2.4</a></span> BestFitMatcher
(availableLocales, requestedLocales)</h1>
<p>The BestFitMatcher abstract operation compares <var>requestedLocales</var>, which must be a <a href="#sec-5">List</a> as
returned by <a href="#sec-9.2.1">CanonicalizeLocaleList</a>, against the locales in <var>availableLocales</var> and
determines the best available language to meet the request. The algorithm is implementation dependent, but should produce
results that a typical user of the requested locales would perceive as at least as good as those produced by the <a
href="#sec-9.2.3">LookupMatcher</a> abstract operation. Options specified through Unicode locale extension sequences must be
ignored by the algorithm. Information about such subsequences is returned separately. The abstract operation returns a
record with a [[locale]] field, whose value is the language tag of the selected locale, which must be an element of
<var>availableLocales</var>. If the language tag of the request locale that led to the selected locale contained a Unicode
locale extension sequence, then the returned record also contains an [[extension]] field whose value is the first Unicode
locale extension sequence, and an [[extensionIndex]] field whose value is the index of the first Unicode locale extension
sequence within the request locale language tag.</p>
</section>
<section id="sec-9.2.5">
<h1><span class="secnum"><a href="#sec-9.2.5" title="link to this section">9.2.5</a></span> ResolveLocale (availableLocales,
requestedLocales, options, relevantExtensionKeys, localeData)</h1>
<p>The ResolveLocale abstract operation compares a BCP 47 language priority list <var>requestedLocales</var> against the
locales in <var>availableLocales</var> and determines the best available language to meet the request.
<var>availableLocales</var> and <var>requestedLocales</var> must be provided as <a href="#sec-5">List</a> values,
<var>options</var> as a <a href="#sec-5">Record</a>.</p>
<p>The following steps are taken:</p>
<ol class="proc">
<li>Let <i>matcher</i> be the value of <i>options</i>.[[localeMatcher]].</li>
<li>If <i>matcher</i> is <code>"lookup"</code>, then
<ol class="block">
<li>Let <i>r</i> be the result of calling the <a href="#sec-9.2.3">LookupMatcher</a> abstract operation (defined in <a
href="#sec-9.2.3">9.2.3</a>) with arguments <i>availableLocales</i> and <i>requestedLocales</i>.</li>
</ol>
</li>
<li>Else
<ol class="block">
<li>Let <i>r</i> be the result of calling the <a href="#sec-9.2.4">BestFitMatcher</a> abstract operation (defined in
<a href="#sec-9.2.4">9.2.4</a>) with arguments <i>availableLocales</i> and <i>requestedLocales</i>.</li>
</ol>
</li>
<li>Let <i>foundLocale</i> be the value of <i>r</i>.[[locale]].</li>
<li>If <i>r</i> has an [[extension]] field, then
<ol class="block">
<li>Let <i>extension</i> be the value of <i>r</i>.[[extension]].</li>
<li>Let <i>extensionIndex</i> be the value of <i>r</i>.[[extensionIndex]].</li>
<li>Let <i>split</i> be the standard built-in function object defined in <a
href="http://ecma-international.org/ecma-262/5.1/#sec-15.5.4.14">ES5, 15.5.4.14</a>.</li>
<li>Let <i>extensionSubtags</i> be the result of calling the [[Call]] internal method of <i>split</i> with
<i>extension</i> as the <b>this</b> value and an argument list containing the single item <code>"-"</code>.</li>
<li>Let <i>extensionSubtagsLength</i> be the result of calling the [[Get]] internal method of <i>extensionSubtags</i>
with argument <code>"length"</code>.</li>
</ol>