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
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<div class="intro">
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <p>The Internationalization utility supports the management of localized resources such as strings and formatting patterns.</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<h2 id="scenarios">Usage Scenarios for the Internationalization Utility</h2>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>The YUI Internationalization utility supports externalization, that is,
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiseparating data that needs to change for different languages or markets
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaifrom the code of a software product, so that the same code can be used
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiworldwide.</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>Depending on the kind of software you create with YUI, you will interact
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiwith the Internationalization utility in different ways.</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<h3 id="monolingualApps">Monolingual Applications</h3>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>Many applications using YUI are not internationalized themselves; they
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiuse one user interface language to target one market.
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen DesaiHowever, such applications still want language-sensitive modules that
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaithey rely on to be internationalized and localized for their language.
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen DesaiFor example, an application using Chinese to target Hong Kong wants dates
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaito be displayed in a Chinese format appropriate for Hong Kong, and so
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desairelies on the DataType utility to provide such formats.</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>If the modules that such an application uses support the language of
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaithe application, the problem is solved by simply
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<a href="#prefLang">requesting preferred languages</a>. Otherwise, the
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiapplication may be able to fill the gap by
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<a href="#appResources">providing resources to modules</a>.</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<h3 id="multilingualApps">Multilingual Applications</h3>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>An application that's intended for users in different markets or
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiusing different languages has to be internationalized.<p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>Primarily, this means developing its code in the form of
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<a href="#intlModules">internationalized modules</a>, determining
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaithe preferred user interface language(s),
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<a href="#prefLang">requesting preferred languages</a>, and possibly
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<a href="#appResources">providing resources to modules</a>.</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>Optionally, an application can provide a user interface element
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaithat lets the user <a href="#switchingLangs">switch languages</a>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaion the fly.</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<h3 id="intlModules">Internationalized Modules</h3>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>A module whose functionality is sensitive to different markets and
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desailanguages and that's intended for use by multilingual applications
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaior by different monolingual applications
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaihas to be <a href="#modules">internationalized</a>.</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai{{>getting-started}}
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<h2 id="using">Using the Internationalization Utility</h2>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<h3 id="bcp47">Using BCP 47 Language Tags</h3>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>BCP 47 language tags are the identifiers for languages used on the internet.
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen DesaiBCP stands for IETF Best Current Practice, and BCP 47 is currently the combination
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiof <a href="http://tools.ietf.org/html/rfc5646">RFC 5646</a> and
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<a href="http://tools.ietf.org/html/rfc4647">RFC 4647</a>.
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen DesaiThese tags allow the description of languages in varying levels of detail, from
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai"Chinese" ("zh") to "Chinese written in traditional characters as used in Taiwan"
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai("zh-Hant-TW") and more. Typical components ("subtags") are ISO 639 language codes,
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen DesaiISO 15924 script codes, and ISO 3166 country codes. Subtags are separated by
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>Here are the language tags for some popular languages:</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<tr><th>Language Tag<th>Description
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<tr><td>zh-Hans-CN<td>Chinese, simplified characters, China
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<tr><td>es<td>Spanish
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<tr><td>en<td>English
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<tr><td>hi-IN<td>Hindi, India
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<tr><td>ar<td>Arabic
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<tr><td>en-US<td>English, U.S.A.
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<tr><td>id-ID<td>Indonesian, Indonesia
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<tr><td>pt-BR<td>Portuguese, Brazil
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<tr><td>ru-RU<td>Russian, Russia
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<tr><td>fr<td>French
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<tr><td>ja-JP<td>Japanese, Japan
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<tr><td>es-MX<td>Spanish, Mexico
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>BCP 47 also defines a "Lookup" algorithm, which is commonly used to determine
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaithe best language for a user interface. Its input is an ordered list of
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desailanguages that the user prefers, and the list of languages that the software
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaisupports. When looking for a language, the algorithm uses a fallback that
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaisuccessively simplifies a language tag. For example, when looking for
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaia requested "zh-Hans-CN", it also checks whether "zh-Hans" or "zh" are
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiavailable.</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>The Internationalization utility provides the Lookup algorithm as the
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai`Intl.lookupBestLang` method, and the YUI loader uses it to determine
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaithe best language based on an application's request and a module's language
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>When requesting a language, it's generally a good idea to be specific and
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiinclude the country, because in some cases the differences between countries
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiare significant. For example, "3/5/10" means "March 5, 2010" in U.S. English,
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaibut "3 May 2010" in British English.</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>When providing language support, on the other hand, you should also support
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaithe less specific variant without country ("en", "es", "zh-Hans", etc.), so that
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaithe fallback finds something when a request includes a country that you don't
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaisupport. Where the usage in different countries using the same language diverges
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaisiginificantly, try to be neutral, e.g., by formatting dates in ISO notation
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaias 2010-03-05.</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<h3 id="applications">Internationalizing Applications</h3>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<h4 id="prefLang">Requesting Preferred Languages</h4>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>When creating a YUI instance, you can specify a list of preferred languages.</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>For a monolingual application, this list starts with the user interface
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desailanguage of the application, but it may include other languages that
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiusers are likely to understand, in case a module doesn't support the
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaipreferred language. For example, an application in Arabic for Morocco might
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaispecify French as a second choice since French is widely spoken in Morocco.</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>A multilingual application might maintain user language preferences as part of
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaithe application, derive the preference list from the `Accept-Language`
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiheader provided by the browser, or determine the list in some other fashion.</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>The preference list is specified as the `lang` property of the YUI
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiinstance's config object. The YUI instance uses it to select the best available
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desailanguage for each module and load the necessary resource bundles.</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai// Create new YUI instance, specify preferred languages,
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai// and populate it with the required modules
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen DesaiYUI({lang:"ar-MA,fr-FR"}).use('datatype-date', function(Y) {
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai // DataType available, and hopefully localized into one of the preferred languages
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<h4 id="appResources">Providing Resources to Modules</h4>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>In some cases, a module is internationalized, but doesn't have a resource
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaibundle for the desired language. It may however have specified the contents
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiof the resource bundle needed. In such a case, the application can register
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaia resource bundle for its language with the Internationalization utility and
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiset the language of that module.</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>For example, date formatting in the DataType utility has support for a
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desailarge number of languages built in, but Punjabi is not one of them. If
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiyou need date formatting for Punjabi, you can provide a resource bundle for this
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desailanguage (see the <a href="../datatype/index.html#addDateFormat">DataType</a>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaidocumentation for information on the contents of the resource bundle):</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen DesaiYUI().use("intl", "datatype-date-format", function(Y) {
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai // provide data for Punjabi in India
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai Y.Intl.add("datatype-date-format", "pa-IN", {
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai "a":["ਐਤ.","ਸੋਮ.","ਮੰਗਲ.","ਬੁਧ.","ਵੀਰ.","ਸ਼ੁਕਰ.","ਸ਼ਨੀ."],
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai "A":["ਐਤਵਾਰ","ਸੋਮਵਾਰ","ਮੰਗਲਵਾਰ","ਬੁਧਵਾਰ","ਵੀਰਵਾਰ","ਸ਼ੁੱਕਰਵਾਰ","ਸ਼ਨੀਚਰਵਾਰ"],
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai "b":["ਜਨਵਰੀ","ਫ਼ਰਵਰੀ","ਮਾਰਚ","ਅਪ੍ਰੈਲ","ਮਈ","ਜੂਨ","ਜੁਲਾਈ","ਅਗਸਤ","ਸਤੰਬਰ","ਅਕਤੂਬਰ","ਨਵੰਬਰ","ਦਸੰਬਰ"],
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai "B":["ਜਨਵਰੀ","ਫ਼ਰਵਰੀ","ਮਾਰਚ","ਅਪ੍ਰੈਲ","ਮਈ","ਜੂਨ","ਜੁਲਾਈ","ਅਗਸਤ","ਸਤੰਬਰ","ਅਕਤੂਬਰ","ਨਵੰਬਰ","ਦਸੰਬਰ"],
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai "c":"%a, %Y %b %d %l:%M:%S %p %Z",
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai "p":["ਸਵੇਰੇ","ਸ਼ਾਮ"],
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai "P":["ਸਵੇਰੇ","ਸ਼ਾਮ"],
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai "x":"%d/%m/%Y",
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai "X":"%l:%M:%S %p"
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai // switch to Punjabi
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai Y.Intl.setLang("datatype-date-format", "pa-IN");
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai // now dates are formatted in Punjabi
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai alert(Y.DataType.Date.format(new Date(), {format:"%A %x %X"}));
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<h4 id="switchingLangs">Switching Languages</h4>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>Some applications let the user change the user interface language on the fly.
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen DesaiThe Internationalization utility offers some low-level support for this:</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <li>Applications that want to make the languages offered reflect the actually
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai available languages in one or more modules can obtain the necessary
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai information from `Intl.getAvailableLangs`.
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <li>Once a new language has been selected, the application can load the
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai required resource bundles and call `Intl.setLang` to
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai switch localizable modules to the new language.
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <li>Modules that have language sensitive behavior, whether relying on
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai their own resource bundles or on other modules', can listen to
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai `intl:langChange` events to find out about language changes.
f0b53deafb42d1f29309dc4fa0d4aeb1d7bc3c1eSatyen Desai<p>The <a href="../datatype/datatype-dateformat-lang.html">Formatting
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen DesaiDates Using Language Resource Bundles</a> example shows how to use these interfaces.</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<h3 id="modules">Internationalizing Modules</h3>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<h4 id="externalizing">Externalizing Resources</h4>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>Externalization means moving all language-sensitive data into external data files,
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaialso known as "resource bundles". Most of this data will be user interface strings
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaithat have to be translated, but there may also be patterns strings, font names, or
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiother items. Resource bundles store this data as simple key-value pairs.</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>The first resource bundle you always have to provide for an internationalized module
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiis the root bundle, identified by the empty language tag "" and using the bundle name
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<code>lang/<i>module</i></code>.
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen DesaiThis is the bundle that will be used when an application requests a language that your module does
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desainot support. Additional languages are identified by their BCP 47 language tags, and their resource
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaibundles use the names <code>lang/<i>module</i>_<i>language</i></code>.</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>If you've used resource bundles in Java or other internationalization libraries,
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiyou may be familiar with the fallback mechanisms in their ResourceBundle classes.
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen DesaiThese do not exist in YUI, so that the loader doesn't have to load multiple bundles.
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen DesaiAs a consequence, each YUI resource bundle must provide the complete set of key-value
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaipairs that the module needs.</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>YUI currently supports two source formats for resource bundles: JSON-style
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen DesaiJavaScript source files, and Yahoo Resource Bundle format.</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>In JSON-style format, a resource bundle is a simple object whose properties
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desairepresent the bundle's key-value pairs. Source files use the JavaScript suffix
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai".js" and can contain comments, so that you can provide localizers with the
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiinformation they need for correct localization.
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen DesaiHere is a family of JSON files providing the same set of strings in English,
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen DesaiGerman, and simplified Chinese:</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <th>English <span style="text-transform:none">(root)</span></th>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <th>German<th>Simplified Chinese</th>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <th>File</th>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <th>Contents</th>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai HELLO: "Hello!",
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai GOODBYE: "Goodbye!"
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai HELLO: "Hallo!",
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai GOODBYE: "Tschüß!"
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai HELLO: "你好！",
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai GOODBYE: "再见！"
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>The <a href="#yrb">Yahoo Resource Bundles format</a> is a simple
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaitext format for resource bundles that Yahoo open-sourced in 2009.
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen DesaiIt uses the file name suffix ".pres".
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen DesaiHere are the same resource bundles as above in YRB format:</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <th>English <span style="text-transform:none">(root)</span></th>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <th>German</th>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <th>Simplified Chinese</th>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <th>File</th>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <th>Contents</th>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai HELLO = Hello!
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai GOODBYE = Goodbye!
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai HELLO = Hallo!
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai GOODBYE = Tschüß!
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai GOODBYE = 再见！
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<h4 id="packaging">Packaging Resources</h4>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>The YUI loader expects resource bundles in a specific format. If you use the YUI Builder
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaito build your module, resource bundles in JSON or YRB format will be automatically
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiconverted into the format expected by the loader. All you have to do is provide the source
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaifiles in the <code>src/<i>module</i>/lang/</code> directory, and specify the list of
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiavailable languages as the `component.lang` property of the module's
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>If you use some other build process, you have to produce JavaScript files in the
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaifollowing format:</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai "greetings", // associated module
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai "zh-Hans", // BCP 47 language tag
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai // key-value pairs for this module and language
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai HELLO: "你好！",
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai GOODBYE: "再见！"
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<h4 id="specifying">Specifying Available Languages</h4>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>The YUI loader also needs to be told that your module uses resource bundles,
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiand for which languages it has resource bundles available. You provide this
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiinformation as the `lang` property of the module meta data:</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai "greetings": {
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai lang: ["de", "zh-Hans"]
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<h4 id="obtaining">Obtaining Resources</h4>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>To access its resources, a module simply calls `Intl.get` with its
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaimodule name. When instantiating YUI, the application will have requested its
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaiuser interface language, so `Intl.get` will return the appropriate
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desailocalized resource bundle.</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaifunction Greetings() {
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai // Get localized strings in the current language
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai hello: function() {
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai goodbye: function() {
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<h3 id="yrb">Yahoo Resource Bundle Format</h3>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai<p>The Yahoo Resource Bundle (YRB) format is a simple text format for
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desairesource bundles. It's similar to Java properties files, but based
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desaion UTF-8 and with additional heredoc support.</p>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <li>Files are encoded in UTF-8. The first line may be prefixed with a byte order mark (BOM).</li>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <li>Lines whose first non-whitespace character is “#” are comment lines and are ignored.</li>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <li>Lines that contain only whitespace characters and are not part of a heredoc string are ignored.</li>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <li>Key-value definitions come in two forms:
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <li>The simple form has a key string, followed by “=”, followed by the value, all on one line.
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai The tokens may or may not be surrounded by whitespace characters. Leading and trailing
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai whitespace is trimmed from both key and value. The value cannot start with "<<<";
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai for values starting with this character sequence, use the heredoc form.
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <li>The heredoc form starts with a key string, followed by “=”, followed by “<<<”,
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai followed by an identifier, all on one line.
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai The tokens may or may not be surrounded by whitespace characters
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai Leading and trailing whitespace is trimmed from both key and identifier.
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai The heredoc form ends with a termination line that contains only the identifier,
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai possibly followed by a semicolon.
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai The lines between these two lines, except comment lines, form the heredoc string.
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai The line break before the termination line is removed, all other line breaks are preserved.
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <li>Lines that are not comment lines, whitespace lines, or part of a key-value definition are illegal.</li>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <li>The following escape sequences are recognized in values:
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <li>“\\” stands for “\”.</li>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <li>“\n” stands for the newline character, U+000A.</li>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <li>“\t” stands for the horizontal tab character, U+0009.</li>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <li>“\ ” stands for the space character, U+0020. This is only needed if the value of a key-value
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai pair starts or ends with a space character.</li>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <li>“\#” stands for the number sign character, U+0023. This is only needed if a line within a
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai heredoc string starts with this character.</li>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <li>A sequence of “\” followed by a character not listed above is illegal.
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai A “\” immediately preceding the end of the file is illegal.</li>
63395602d80d1bec7472deebcb4909b24a5f98cdSatyen Desai <li>Only the characters horizontal tab, U+0009, and space, U+0020, are considered whitespace.</li>