intl-messageformat 1.0.1 → 1.1.0

package/README.md

@@ -7,8 +7,8 @@ Formats ICU Message strings with number, date, plural, and select placeholders t
 [![Build Status][travis-badge]][travis]
 [![Dependency Status][david-badge]][david]
 
+[![Sauce Test Status][sauce-badge]][sauce]
 
-[![Sauce Test Status](https://saucelabs.com/browser-matrix/intl-messageformat.svg)](https://saucelabs.com/u/intl-messageformat)
 
 Overview
 --------
@@ -29,7 +29,7 @@ Messages are provided into the constructor as a `String` message, or a [pre-pars
 var msg = new IntlMessageFormat(message, locales, [formats]);
 ```
 
-The string `message` is parsed, then stored internally in a compiled form that is optimized for the `format()` method to produce the formatted string for display to the user.
+The string `message` is parsed, then stored internally in a compiled form that is optimized for the `format()` method to produce the formatted string for displaying to the user.
 
 ```js
 var output = msg.format(values);
@@ -37,7 +37,7 @@ var output = msg.format(values);
 
 ### Common Usage Example
 
-A very common example is formatting messages that have numbers with plural lables. With this package you can make sure that the string is properly formatted for a person's locale, e.g.:
+A very common example is formatting messages that have numbers with plural labels. With this package you can make sure that the string is properly formatted for a person's locale, e.g.:
 
 ```js
 var MESSAGES = {
@@ -75,7 +75,7 @@ The message syntax that this package uses is not proprietary, in fact it's a com
 
 * Uses industry standards: [ICU Message syntax][ICU] and [CLDR locale data][CLDR].
 
-* Supports **plural** and **select** message arguments.
+* Supports **plural**, **select**, and **selectordinal** message arguments.
 
 * Formats numbers and dates/times in messages using [`Intl.NumberFormat`][Intl-NF] and [`Intl.DateTimeFormat`][Intl-DTF], respectively.
 
@@ -124,21 +124,13 @@ _Note: When using the Intl.js Polyfill in Node.js, it will automatically load th
 <script src="intl-messageformat/intl-messageformat.min.js"></script>
 ```
 
-By default, Intl MessageFormat ships with the locale data for English built-in to the runtime library. When you need to format data in another locale, include its data; e.g., for French:
+By default, Intl MessageFormat ships with the locale data for English (`en`) built-in to the library's runtime. When you need to format data in another locale, include its data; e.g., for French:
 
 ```html
 <script src="intl-messageformat/locale-data/fr.js"></script>
 ```
 
-_Note: All 150+ locales supported by this package use their root BCP 47 langage tag; i.e., the part before the first hyphen (if any)._
-
-#### Using Raw Git CDN
-
-If you'd like to load this package via a CDN, instead of hosting it yourself, one option is using [Raw Git][rawgit]. **Be sure to reference a `dist/` file using a Git tag:**
-
-```html
-<script src="https://cdn.rawgit.com/yahoo/intl-messageformat/v1.0.1/dist/intl-messageformat.min.js"></script>
-```
+_Note: All 200+ languages supported by this package use their root BCP 47 language tag; i.e., the part before the first hyphen (if any)._
 
 ### Loading Intl MessageFormat in Node.js
 
@@ -148,7 +140,7 @@ Simply `require()` this package:
 var IntlMessageFormat = require('intl-messageformat');
 ```
 
-_Note: in Node.js, the data for all 150+ locales is loaded along with the library._
+_Note: in Node.js, the data for all 200+ languages is loaded along with the library._
 
 ### Public API
 
@@ -157,7 +149,7 @@ To create a message to format, use the `IntlMessageFormat` constructor. The cons
 
  - **message** - _{String | AST}_ - String message (or pre-parsed AST) that serves as formatting pattern.
 
- - **locales** - _{String | String[]}_ - A string with a BCP 47 language tag, or an array of such strings. If you do not provide a locale, the default locale will be used, but you should _always_ provide one!
+ - **locales** - _{String | String[]}_ - A string with a BCP 47 language tag, or an array of such strings. If you do not provide a locale, the default locale will be used. When an array of locales is provided, each item and its ancestor locales are checked and the first one with registered locale data is returned. **See: [Locale Resolution](#locale-resolution) for more details.**
 
  - **[formats]** - _{Object}_ - Optional object with user defined options for format styles.
 
@@ -165,6 +157,38 @@ To create a message to format, use the `IntlMessageFormat` constructor. The cons
 var msg = new IntlMessageFormat('My name is {name}.', 'en-US');
 ```
 
+#### Locale Resolution
+
+`IntlMessageFormat` uses a locale resolution process similar to that of the built-in `Intl` APIs to determine which locale data to use based on the `locales` value passed to the constructor. The result of this resolution process can be determined by call the `resolvedOptions()` prototype method.
+
+The following are the abstract steps `IntlMessageFormat` goes through to resolve the locale value:
+
+* If no extra locale data is loaded, the locale will _always_ resolved to `"en"`.
+
+* If locale data is missing for a leaf locale like `"fr-FR"`, but there _is_ data for one of its ancestors, `"fr"` in this case, then its ancestor will be used.
+
+* If there's data for the specified locale, then that locale will be resolved; i.e.,
+
+    ```js
+    var mf = new IntlMessageFormat('', 'en-US');
+    assert(mf.resolvedOptions().locale === 'en-US'); // true
+    ```
+
+* The resolved locales are now normalized; e.g., `"en-us"` will resolve to: `"en-US"`.
+
+_Note: When an array is provided for `locales`, the above steps happen for each item in that array until a match is found._
+
+#### `resolvedOptions()` Method
+
+This method returns an object with the options values that were resolved during instance creation. It currently only contains a `locale` property; here's an example:
+
+```js
+var msg = new IntlMessageFormat('', 'en-us');
+console.log(msg.resolvedOptions().locale); // => "en-US"
+```
+
+Notice how the specified locale was the all lower-case value: `"en-us"`, but it was resolved and normalized to: `"en-US"`.
+
 #### `format(values)` Method
 
 Once the message is created, formatting the message is done by calling the `format()` method on the instance and passing a collection of `values`:
@@ -174,7 +198,7 @@ var output = msg.format({name: "Eric"});
 console.log(output); // => "My name is Eric."
 ```
 
-**Note:** A value _must_ be supplied for every argument in the message pattern the instance was constructed with.
+_Note: A value **must** be supplied for every argument in the message pattern the instance was constructed with._
 
 #### User Defined Formats
 
@@ -225,7 +249,7 @@ console.log(msg.format({numPhotos: 1}));    // => "You have one photo."
 console.log(msg.format({numPhotos: 1000})); // => "You have 1,000 photos."
 ```
 
-_Note how when `numPhotos` was `1000`, the number is formatted with the correct thousands separator._
+_Note: how when `numPhotos` was `1000`, the number is formatted with the correct thousands separator._
 
 
 License
@@ -241,6 +265,8 @@ See the [LICENSE file][LICENSE] for license text and copyright information.
 [david-badge]: https://img.shields.io/david/yahoo/intl-messageformat.svg?style=flat-square
 [travis]: https://travis-ci.org/yahoo/intl-messageformat
 [travis-badge]: https://img.shields.io/travis/yahoo/intl-messageformat.svg?style=flat-square
+[sauce]: https://saucelabs.com/u/intl-messageformat
+[sauce-badge]: https://saucelabs.com/browser-matrix/intl-messageformat.svg
 [strawman]: http://wiki.ecmascript.org/doku.php?id=globalization:messageformatting
 [parser]: https://github.com/yahoo/intl-messageformat-parser
 [ICU]: http://userguide.icu-project.org/formatparse/messages