https://github.com/azz/around-the-world
Simple to use ICU localization library built for MessageFormat
https://github.com/azz/around-the-world
icu localization messageformat
Last synced: 8 months ago
JSON representation
Simple to use ICU localization library built for MessageFormat
- Host: GitHub
- URL: https://github.com/azz/around-the-world
- Owner: azz
- License: mit
- Created: 2018-10-01T13:43:01.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2018-10-02T02:02:33.000Z (about 7 years ago)
- Last Synced: 2025-02-01T07:03:24.923Z (8 months ago)
- Topics: icu, localization, messageformat
- Language: JavaScript
- Homepage:
- Size: 89.8 KB
- Stars: 1
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# `around-the-world`
[](https://travis-ci.org/azz/around-the-world)
[](https://github.com/prettier/prettier)
[](https://npmjs.org/around-the-world)
[](https://github.com/semantic-release/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.
- [x] Lazily loads localization templates.
- [x] Simple API.
- [x] Dynamically change the locale.
## Install
With `yarn`:
```shellsession
yarn add around-the-world
```
With `npm`:
```shellsession
npm install --save around-the-world
```
## Usage
### 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.
```js
const { localize } = await aroundTheWorld({
loadLocale: locale => import(`/i18n/${locale}.js`),
});
localize('hello-world');
```
### Compiling in the Client
You can compile ICU messages in the client directly with `MessageFormat#compile`.
```js
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`](https://mdn.io/navigator.language) is used.
```js
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.
```js
const { localize, getCurrentLocale, setCurrentLocale } = await aroundTheWorld({
loadLocale: locale => {
/* ... */
},
});
getCurrentLocale(); // 'en-AU'
localize('hello'); // 'Hello'
await setCurrentLocale('jp');
localize('hello'); // 'こんにちは'
```
[messageformat]: https://github.com/messageformat/messageformat