@planet/localizer

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:

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:

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

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

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.

localizer.update('es');

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

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

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

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

See the Format.js guide 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 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.

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 (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 for the specific language governing permissions and limitations under the License.