npm package: @planet/localizer
Description: A localization utility for fetching and formatting ICU messages
Latest version: 1.4.0

# `localizer`

A localization utility for fetching and formatting ICU messages.

## Installation

Add the package as a dependency with npm:

    npm install @planet/localizer --save

## Use

Configure your localizer with a URL template and a lookup of supported locales:

```js
var Localizer = require('@planet/localizer');
var localizer = new Localizer({
  url: 'http://example.com/{locale}.json',
  supported: {en: 'English', es: 'Español'},
  default: 'en'
});
```

This provides you with a localizer that will load resource files for English (`en`) and Spanish (`es`) locales.

For this example, assume that `http://example.com/en.json` provides English messages for your application and has the following content:

```json
{
  "greeting": "Hello {name}!"
}
```

The localizer is an event emitter that will emit `update` events when resource files have been loaded and parsed.

```js
localizer.on('update', function(localize) {
  var message = localize('greeting', {name: 'Planet'});
  console.log(message); // "Hello Planet!"
});
```

The first of the `supported` locales is the default, and will be loaded after a localizer is constructed.  To change locales, call the `localizer.update(locale)` method.

```js
localizer.update('es');
```

Let's assume that `http://example.com/es.json` provides Spanish messages and has the following content:

```json
{
  "greeting": "¡Hola {name}!"
}
```

Your `update` listener will now get called with a `localize` method for formatting Spanish messages:

```js
localizer.on('update', function(localize) {
  var message = localize('greeting', {name: 'Planet'});
  console.log(message); // "¡Hola Planet!"
});
```

See the [Format.js guide](http://formatjs.io/guides/message-syntax/) for details on the supported ICU message syntax.

## API

### `new Localizer(config)`

**Arguments**

 * `config.url` - `string` Required URL template for loading resource files.  The template must have a single `{locale}` placeholder that will be replaced with the current locale identifier.  For example, `http://example.com/{locale}.json` would expand to `http://example.com/en.json` for the `en` locale.  Resource files are JSON objects with keys for [ICU formatted](http://formatjs.io/guides/message-syntax/) messages.

 * `config.supported` - `Object` Required lookup of supported locales.

 * `config.default` - `string` The default locale identifier.  The resource file for this locale will be loaded at construction.  If not provided, the first key in the `supported` lookup will be used as the default.

**Methods**

 * `update(locale)` - `function(string)` Update the current locale.  The requested locale will be resolved to one of the `supported` locales (e.g. if `en-AU` is requested and only `en` is supported, `en` will be used).  Calling update triggers a fetch for a resource file.  When the resource file is loaded (or if it has been previously cached), the `update` event will be triggered.

 * `isRTL(locale)` - `boolean` Utility method for determining if a locale is a [right-to-left language](https://en.wikipedia.org/wiki/Right-to-left).

**Properties**

 * `current` - `string` The currently loaded locale (read only).  You should access this property in an `update` event listener to determine the resolved locale.

 * `supported` - `Object` The lookup of supported locales provided to the constructor (read only).

**Events**

 * `update` - Triggered when resource files are loaded and parsed.  Listeners will be called with a `localize` function for formatting messages for the current locale.  The `localize` function takes a `string` message key and an optional lookup `Object` of values for replacement in the message.

 * `error` - Triggered when there is an error loading or parsing a resource file.  Listeners will be called with an `Error` describing what went wrong.

## Development

Install dependencies and run tests continuously during development:

    npm install && npm start

Tests may be run a single time with `npm test`.

### License

© Planet Labs, Inc.

Licensed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0) (the "License"); you may not use this file except in compliance with the License.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See [the License](http://www.apache.org/licenses/LICENSE-2.0) for the specific language governing permissions and limitations under the License.