4 =========================
5 UI Internationalization
6 =========================
8 There are many types of data that need to be formatted into a locale specific format,
9 or require locale specific API operations.
11 Gecko provides a rich set of locale aware APIs for operations such as:
13 * date and time formatting
18 * calendar and locale information
22 Most of the APIs are backed by the Unicode projects `CLDR`_ and `ICU`_ and are
23 focused on enabling front-end code internationalization, which means the majority of
24 the APIs are primarily available in JavaScript, with C++ and Rust having only a small
25 subset of them exposed.
27 JavaScript Internationalization API
28 ===================================
30 Data internationalization APIs are formalized in the JavaScript standard `ECMA 402`_.
31 These APIs are supported by all major JS environments.
33 It is best to consult the MDN article on the current state of the `Intl API`_.
34 Mozilla has an excellent support of the API and relies on it for majority
35 of its needs. Yet, when working on Firefox UI the :js:`Services.intl` wrapper
41 :js:`Services.intl` is an extension of the JS Intl API which should be used whenever
42 working with Gecko app user interface with chrome privileges.
44 The API provides the same objects and methods as :js:`Intl.*`, but fine tunes them
45 to the Gecko app user preferences, including matching OS Preferences and
46 other locale choices that web content exposed JS Intl API cannot.
48 For example, here's an example of a locale aware date formatting
49 using the regular :js:`Intl.DateTimeFormat`:
51 .. code-block:: javascript
53 let rtf = new Intl.DateTimeFormat(navigator.languages, {
58 let value = rtf.format(new Date());
60 It will do a good job at formatting the date to the user locale, but it will
61 only be able to use the customization bits that are exposed to the Web, based on
62 the locale the user broadcasts to the Web and any additional settings.
64 But that ignores bits of information that could inform the formatting.
66 Public API such as :js:`Intl.*` will not be able to look into the Operating System for
67 regional preferences. It will also respect settings such as `Resist Fingerprinting`
68 by masking its timezone and locale settings.
70 This is a fair tradeoff when dealing with the Web Content, but in most cases, the
71 privileged UI of the Gecko application should be able to access all of those
72 additional bits and not be affected by the anti-fingerprinting masking.
74 `mozIntl` is a simple wrapper which in its simplest form works exactly the same. It's
75 exposed on :js:`Services.intl` object and can be used just like a regular `Intl` API:
77 .. code-block:: javascript
79 let rtf = new Services.intl.DateTimeFormat(undefined, {
84 let value = rtf.format(new Date());
86 The difference is that this API will now use the set of locales as defined for
87 Gecko, and will also respect additional regional preferences that Gecko
88 will fetch from the Operating System.
90 For those reasons, when dealing with Gecko application UI, it is always recommended
91 to use the :js:`Services.intl` wrapper.
96 On top of wrapping up `Intl` API, `mozIntl` provides a number of features
97 in form of additional options to existing APIs as well as completely new APIs.
99 Many of those extensions are in the process of being standardized, but are
100 already available to Gecko developers for internal use.
102 Below is the list of current extensions:
104 mozIntl.DateTimeFormat
105 ----------------------
107 `DateTimeFormat` in `mozIntl` gets additional options that provide greater
108 simplicity and consistency to the API.
110 * :js:`timeStyle` and :js:`dateStyle` can take values :js:`short`, :js:`medium`,
111 :js:`long` and :js:`full`.
112 These options can replace the manual listing of tokens like :js:`year`, :js:`day`, :js:`hour` etc.
113 and will compose the most natural date or time format of a given style for the selected
116 Using :js:`timeStyle` and :js:`dateStyle` is highly recommended over listing the tokens,
117 because different locales may use different default styles for displaying the same tokens.
119 Additional value is that using those styles allows `mozIntl` to look into
120 Operating System patterns, which gives users the ability to customize those
121 patterns to their liking.
125 .. code-block:: javascript
127 let dtf = new Services.intl.DateTimeFormat(undefined, {
131 let value = dtf.format(new Date());
133 This will select the best locale to match the current Gecko application locale,
134 then potentially check for Operating System regional preferences customizations,
135 produce the correct pattern for short date+time style and format the date into it.
138 mozIntl.getCalendarInfo(locale)
139 -------------------------------
141 The API will return the following calendar information for a given locale code:
144 an integer in the range 1=Monday to 7=Sunday indicating the day
145 considered the first day of the week in calendars, e.g. 7 for en-US,
146 1 for en-GB, 7 for bn-IN
148 an integer in the range of 1 to 7 indicating the minimum number
149 of days required in the first week of the year, e.g. 1 for en-US, 4 for de
151 an array with values in the range 1=Monday to 7=Sunday indicating the days
152 of the week considered as part of the weekend, e.g. [6, 7] for en-US and en-GB,
153 [7] for bn-IN (note that "weekend" is *not* necessarily two days)
155 Those bits of information should be especially useful for any UI that works
160 .. code-block:: javascript
162 // omitting the `locale` argument will make the API return data for the
163 // current Gecko application UI locale.
168 calendar, // "gregory"
170 } = Services.intl.getCalendarInfo();
173 mozIntl.DisplayNames(locales, options)
174 -----------------------------------------
176 :js:`DisplayNames` API is useful to retrieve various terms available in the
177 internationalization API. :js:`mozIntl.DisplayNames` extends the standard
178 `Intl.DisplayNames`_ to additionally provide localization for date-time types.
180 The API takes a locale fallback chain list, and an options object which can contain
183 * :js:`style` which can take values :js:`narrow`, :js:`short`, :js:`abbreviated`, :js:`long`
184 * :js:`type` which can take values :js:`language`, :js:`script`, :js:`region`,
185 :js:`currency`, :js:`weekday`, :js:`month`, :js:`quarter`, :js:`dayPeriod`,
190 .. code-block:: javascript
192 let dateTimeFieldDisplayNames = new Services.intl.DisplayNames(undefined, {
193 type: "dateTimeField",
195 dateTimeFieldDisplayNames.resolvedOptions().locale = "pl";
196 dateTimeFieldDisplayNames.of("year") = "rok";
198 let monthDisplayNames = new Services.intl.DisplayNames(undefined, {
199 type: "month", style: "long",
201 monthDisplayNames.of(1) = "styczeń";
203 let weekdaysDisplayNames = new Services.intl.DisplayNames(undefined, {
204 type: "weekday", style: "short",
206 weekdaysDisplayNames.of(1) = "pon";
208 let dayPeriodsDisplayNames = new Services.intl.DisplayNames(undefined, {
209 type: "dayPeriod", style: "narrow",
211 dayPeriodsDisplayNames.of("am") = "AM";
214 mozIntl.RelativeTimeFormat(locales, options)
215 --------------------------------------------
217 API which can be used to format an interval or a date into a textual
218 representation of a relative time, such as **5 minutes ago** or **in 2 days**.
220 This API is in the process of standardization and in its raw form will not handle
221 any calculations to select the best unit. It is intended to just offer a way
224 `mozIntl` wrapper extends the functionality providing the calculations and
225 allowing the user to get the current best textual representation of the delta.
229 .. code-block:: javascript
231 let rtf = new Services.intl.RelativeTimeFormat(undefined, {
232 style: "long", // "narrow" | "short" | "long" (default)
233 numeric: "auto", // "always" | "auto" (default)
236 let now = Date.now();
237 rtf.formatBestUnit(new Date(now - 3 * 1000 * 60)); // "3 minutes ago"
239 The option `numeric` has value set to `auto` by default, which means that when possible
240 the formatter will use special textual terms like *yesterday*, *last year*, and so on.
242 Those values require specific calculations that the raw `Intl.*` API cannot provide.
243 For example, *yesterday* requires the algorithm to know not only the time delta,
244 but also what time of the day `now` is. 15 hours ago may be *yesterday* if it
245 is 10am, but will still be *today* if it is 11pm.
247 For that reason the future `Intl.RelativeTimeFormat` will use *always* as default,
248 since terms such as *15 hours ago* are independent of the current time.
252 In the current form, the API should be only used to format standalone values.
253 Without additional capitalization rules, it cannot be freely used in sentences.
255 mozIntl.getLanguageDisplayNames(locales, langCodes)
256 ---------------------------------------------------
258 API which returns a list of language names formatted for display.
262 .. code-block:: javascript
264 let langs = getLanguageDisplayNames(["pl"], ["fr", "de", "en"]);
265 langs === ["Francuski", "Niemiecki", "Angielski"];
268 mozIntl.getRegionDisplayNames(locales, regionCodes)
269 ---------------------------------------------------
271 API which returns a list of region names formatted for display.
275 .. code-block:: javascript
277 let regs = getRegionDisplayNames(["pl"], ["US", "CA", "MX"]);
278 regs === ["Stany Zjednoczone", "Kanada", "Meksyk"];
280 mozIntl.getLocaleDisplayNames(locales, localeCodes)
281 ---------------------------------------------------
283 API which returns a list of region names formatted for display.
287 .. code-block:: javascript
289 let locs = getLocaleDisplayNames(["pl"], ["sr-RU", "es-MX", "fr-CA"]);
290 locs === ["Serbski (Rosja)", "Hiszpański (Meksyk)", "Francuski (Kanada)"];
292 mozIntl.getAvailableLocaleDisplayNames(type)
293 ---------------------------------------------------
295 API which returns a list of locale display name codes available for a
297 Available types are: "language", "region".
301 .. code-block:: javascript
303 let codes = getAvailableLocaleDisplayNames("region");
304 codes === ["au", "ae", "af", ...];
309 The most important best practice when dealing with data internationalization is to
310 perform it as close to the actual UI as possible; right before the UI is displayed.
312 The reason for this practice is that internationalized data is considered *"opaque"*,
313 which means that no code should ever attempt to operate on it. Late resolution also
314 increases the chance that the data will be formatted in the current locale
315 selection and not formatted and cached prematurely.
317 It's very important to not attempt to search, concatenate or in any other way
318 alter the output of the API. Once it gets formatted, the only thing to do with
319 the output should be to present it to the user.
324 The above is also important in the context of testing. It is a common mistake to
325 attempt to write tests that verify the output of the UI with internationalized data.
327 The underlying data set used to create the formatted version of the data may and will
328 change over time, both due to dataset improvements and also changes to the language
329 and regional preferences over time.
330 That means that tests that attempt to verify the exact output will require
331 significantly higher level of maintenance and will remain brittle.
333 Most of the APIs provide special method, like :js:`resolvedOptions` which should be used
334 instead to verify that the output is matching the expectations.
339 If you find yourself in the need of additional internationalization APIs not currently
340 supported, you can verify if the API proposal is already in the works here,
341 and file a bug in the component `Core::Internationalization`_ to request it.
343 .. _ECMA 402: https://tc39.github.io/ecma402/
344 .. _Intl API: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl
345 .. _CLDR: http://cldr.unicode.org/
346 .. _ICU: http://site.icu-project.org/
347 .. _Core::Internationalization: https://bugzilla.mozilla.org/enter_bug.cgi?product=Core&component=Internationalization
348 .. _Intl.DisplayNames: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DisplayNames