around-the-world

around-the-world

Simple to use ICU localization library built on MessageFormat

around-the-world is a utility library built on top of MessageFormat that makes it it simple to localize your app.

• Lazily loads localization templates.
• Supports custom formatters.
• Simple API.
• Dynamically change the locale.

Install

With yarn:

yarn add around-the-world

With npm:

npm install --save around-the-world

Usage

Basics

import aroundTheWorld from 'around-the-world';

(async () => {
  const { localize } = await aroundTheWorld({
    loadLocale: locale => {
      if (locale === 'en-US') {
        return {
          hello_world: 'Hello, world!',
        };
      }
      throw new Error('Unknown locale!');
    },
  });
})();

Loading From a Server

You can easily fetch string tables from your server using the loadLocale function. It must resolve to an object.

const { localize } = await aroundTheWorld({
  loadLocale: async locale => {
    const response = await fetch(`/i18n/${locale}.json`);
    return res.json();
  },
});

localize('hello-world');

Specifying Default Locale

You can specify the default locale to load using defaultLocale. If you don't supply this, navigator.locale is used.

const { localize } = await aroundTheWorld({
  loadLocale: locale => { /* ... */ }

  defaultLocale: 'en-AU',
});

Changing the Locale

You can read the current locale at any time by calling getCurrentLocale(), and you can set it by calling setCurrentLocale(). The latter returns a promise that resolves once the locale is loaded.

const {
  localize,
  getCurrentLocale,
  setCurrentLocale,
} = await aroundTheWorld({
  loadLocale: locale => {
    /* ... */
  },
});

getCurrentLocale(); // 'en-AU'
localize('hello'); // 'Hello'

await setCurrentLocale('jp');
localize('hello'); // 'こんにちは'

Adding Custom Formatters

MessageFormat supports custom formatters, and you can use them with this library!

const { localize } = await aroundTheWorld({
  loadLocale: locale => ({ number: '{value, decimal, 2}' })

  formatters: {
    decimal: (value, locale, arg) => value.toFixed(+arg),
  },
});

localize('number', { value: 12.3456 }); // -> '12.35'