Localization library built for MessageFormat

Usage no npm install needed!

<script type="module">
  import aroundTheWorld from '';



Travis Prettier npm semantic-release License

Simple to use ICU localization library built for MessageFormat

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

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


With yarn:

yarn add around-the-world

With npm:

npm install --save around-the-world


Loading From a Server

You can easily fetch string tables from your server using the loadLocale function and dynamic imports. The format is expected to be produced by the MessageFormat compiler.

const { localize } = await aroundTheWorld({
  loadLocale: locale => import(`/i18n/${locale}.js`),


Compiling in the Client

You can compile ICU messages in the client directly with MessageFormat#compile.

import aroundTheWorld from 'around-the-world';
import MessageFormat from 'messageformat';

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

Specifying Default Locale

You can specify the default locale to load using defaultLocale. If you don't supply this, navigator.language 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'); // 'こんにちは'