UNPKG

9.73 kBMarkdownView Raw
1# Intl.js [![Build Status][]](https://travis-ci.org/andyearnshaw/Intl.js)
2
3In December 2012, ECMA International published the first edition of Standard ECMA-402,
4better known as the _ECMAScript Internationalization API_. This specification provides
5the framework to bring long overdue localization methods to ECMAScript implementations.
6
7All modern browsers, except safari, have implemented this API. `Intl.js` fills the void of availability for this API. It will provide the framework as described by the specification, so that developers can take advantage of the native API
8in environments that support it, or `Intl.js` for legacy or unsupported environments.
9
10[Build Status]: https://travis-ci.org/andyearnshaw/Intl.js.svg?branch=master
11
12
13## Getting started
14
15### Intl.js and FT Polyfill Service
16
17Intl.js polyfill was recently added to the [Polyfill service][], which is developed and maintained by a community of contributors led by a team at the [Financial Times](http://www.ft.com/). It is available through `cdn.polyfill.io` domain, which routes traffic through [Fastly](http://www.fastly.com/), which makes it available with global high availability and superb performance no matter where your users are.
18
19To use the Intl polyfill through the [Polyfill service][] just add one script tag in your page before you load or parse your own JavaScript:
20
21```
22<script src="https://cdn.polyfill.io/v2/polyfill.min.js?features=Intl.~locale.en"></script>
23```
24
25When specifying the `features` to use through the polyfill service, you have to specify what locale, or locales to load along with the Intl polyfill for the page to function, in the example above we are specifying `Intl.~locale.en`, which means only `en`, but you could do something like this:
26
27```
28<script src="https://cdn.polyfill.io/v2/polyfill.min.js?features=Intl.~locale.fr,Intl.~locale.pt"></script>
29```
30
31_note: the example above will load the polyfill with two locale data set, `fr` and `pt`._
32
33This is by far the best option to use the Intl polyfill since it will only load the polyfill code and the corresponding locale data when it is really needed (e.g.: safari will get the code and patch the runtime while chrome will get an empty script tag).
34
35[Polyfill service]: https://cdn.polyfill.io/v1/docs/
36
37### Intl.js and Node
38
39For Node.js applications, you can install `intl` using NPM:
40
41 npm install intl
42
43Node.js 0.12 has the Intl APIs built-in, but only includes the English locale data by default. If your app needs to support more locales than English, you'll need to [get Node to load the extra locale data](https://github.com/nodejs/node/wiki/Intl), or use `intl` npm package to patch the runtime with the Intl polyfill. Node.js versions prior to 0.12 and ≥v3.1 don't provide the Intl APIs, so they require that the runtime is polyfilled.
44
45The following code snippet uses the intl polyfill and [intl-locales-supported](https://github.com/yahoo/intl-locales-supported) npm packages which will help you polyfill the Node.js runtime when the Intl APIs are missing, or if the built-in Intl is missing locale data that's needed for your app:
46
47```javascript
48var areIntlLocalesSupported = require('intl-locales-supported');
49
50var localesMyAppSupports = [
51 /* list locales here */
52];
53
54if (global.Intl) {
55 // Determine if the built-in `Intl` has the locale data we need.
56 if (!areIntlLocalesSupported(localesMyAppSupports)) {
57 // `Intl` exists, but it doesn't have the data we need, so load the
58 // polyfill and patch the constructors we need with the polyfill's.
59 var IntlPolyfill = require('intl');
60 Intl.NumberFormat = IntlPolyfill.NumberFormat;
61 Intl.DateTimeFormat = IntlPolyfill.DateTimeFormat;
62 }
63} else {
64 // No `Intl`, so use and load the polyfill.
65 global.Intl = require('intl');
66}
67```
68
69### Intl.js and Browserify/webpack
70
71If you build your application using [browserify][] or [webpack][], you will install `intl` npm package as a dependency of your application. Ideally, you will avoid loading this library if the browser supports the
72built-in `Intl`. An example of conditional usage using [browserify][] or [webpack][] _might_ look like this:
73
74```javascript
75function runMyApp() {
76 var nf = new Intl.NumberFormat(undefined, {style:'currency', currency:'GBP'});
77 document.getElementById('price').textContent = nf.format(100);
78}
79if (!global.Intl) {
80 require.ensure([
81 'intl',
82 'intl/locale-data/jsonp/en.js'
83 ], function (require) {
84 require('intl');
85 require('intl/locale-data/jsonp/en.js');
86 runMyApp()
87 });
88} else {
89 runMyApp()
90}
91```
92
93_note: the locale data is required for the polyfill to function when using it in a browser environment, in the example above, the english (`en`) locale is being required along with the polyfill itself._
94
95[webpack]: https://webpack.github.io/
96[browserify]: http://browserify.org/
97
98### Intl.js and Bower
99
100Intl.js is also available as a [Bower](http://bower.io) component for the front-end:
101
102 bower install intl
103
104Then include the polyfill in your pages as described below:
105
106```html
107<script src="path/to/intl/Intl.js"></script>
108<script src="path/to/intl/locale-data/jsonp/en.js"></script>
109```
110
111_note: use the locale for the current user, instead of hard-coding to `en`._
112
113## Status
114Current progress is as follows:
115
116### Implemented
117 - All internal methods except for some that are implementation dependent
118 - Checking structural validity of language tags
119 - Canonicalizing the case and order of language subtags
120 - __`Intl.NumberFormat`__
121 - The `Intl.NumberFormat` constructor ([11.1](http://www.ecma-international.org/ecma-402/1.0/#sec-11.1))
122 - Properties of the `Intl.NumberFormat` Constructor ([11.2](http://www.ecma-international.org/ecma-402/1.0/#sec-11.2))
123 - Properties of the `Intl.NumberFormat` Prototype Object ([11.3](http://www.ecma-international.org/ecma-402/1.0/#sec-11.3))
124 - Properties of Intl.NumberFormat Instances([11.4](http://www.ecma-international.org/ecma-402/1.0/#sec-11.4))
125 - __`Intl.DateTimeFormat`__
126 - The `Intl.DateTimeFormat` constructor ([12.1](http://www.ecma-international.org/ecma-402/1.0/#sec-12.1))
127 - Properties of the `Intl.DateTimeFormat` Constructor ([12.2](http://www.ecma-international.org/ecma-402/1.0/#sec-12.2))
128 - Properties of the `Intl.DateTimeFormat` Prototype Object ([12.3](http://www.ecma-international.org/ecma-402/1.0/#sec-12.3))
129 - Properties of Intl.DateTimeFormat Instances([12.4](http://www.ecma-international.org/ecma-402/1.0/#sec-12.4))
130 - Locale Sensitive Functions of the ECMAScript Language Specification
131 - Properties of the `Number` Prototype Object ([13.2](http://www.ecma-international.org/ecma-402/1.0/#sec-13.2))
132 - Properties of the `Date` prototype object ([13.3](http://www.ecma-international.org/ecma-402/1.0/#sec-13.3))
133
134### Not Implemented
135 - `BestFitSupportedLocales` internal function
136 - Implementation-dependent numbering system mappings
137 - Calendars other than Gregorian
138 - Support for time zones
139 - Collator objects (`Intl.Collator`) (see below)
140 - Properties of the `String` prototype object
141
142A few of the implemented functions may currently be non-conforming and/or incomplete.
143Most of those functions have comments marked as 'TODO' in the source code.
144
145The test suite is run with Intl.Collator tests removed, and the Collator
146constructor removed from most other tests in the suite. Also some parts of
147tests that cannot be passed by a JavaScript implementation have been disabled,
148as well as a small part of the same tests that fail due to [this bug in v8][].
149
150 [this bug in v8]: https://code.google.com/p/v8/issues/detail?id=2694
151
152
153## What about Intl.Collator?
154
155Providing an `Intl.Collator` implementation is no longer a goal of this project. There
156are several reasons, including:
157
158 - The CLDR convertor does not automatically convert collation data to JSON
159 - The Unicode Collation Algorithm is more complicated that originally anticipated,
160 and would increase the code size of Intl.js too much.
161 - The Default Unicode Collation Element Table is huge, even after compression, and
162 converting to a native JavaScript object would probably make it slightly larger.
163 Server-side JavaScript environments will (hopefully) soon support Intl.Collator,
164 and we can't really expect client environments to download this data.
165
166
167## Compatibility
168Intl.js is designed to be compatible with ECMAScript 3.1 environments in order to
169follow the specification as closely as possible. However, some consideration is given
170to legacy (ES3) environments, and the goal of this project is to at least provide a
171working, albeit non-compliant implementation where ES5 methods are unavailable.
172
173A subset of the tests in the test suite are run in IE 8. Tests that are not passable
174are skipped, but these tests are mostly about ensuring built-in function behavior.
175
176
177## Locale Data
178`Intl.js` uses the Unicode CLDR locale data, as recommended by the specification. The main `Intl.js` file contains no locale data itself. In browser environments, the
179data should be provided, passed into a JavaScript object using the
180`Intl.__addLocaleData()` method. In Node.js, or when using `require('intl')`, the data
181is automatically added to the runtime and does not need to be provided.
182
183Contents of the `locale-data` directory are a modified form of the Unicode CLDR
184data found at http://www.unicode.org/cldr/.
185
186
187## Contribute
188
189See the [CONTRIBUTING file][] for info.
190
191[CONTRIBUTING file]: https://github.com/andyearnshaw/Intl.js/blob/master/CONTRIBUTING.md
192
193
194## License
195
196Copyright (c) 2013 Andy Earnshaw
197
198This software is licensed under the MIT license. See the `LICENSE.txt` file
199accompanying this software for terms of use.