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
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`),
});
localize('hello-world');
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!');
},
});
})();
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',
});
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'); // 'こんにちは'