README.md

@18f/identity-i18n

JavaScript implementation of a Rails-like localization utility.

When paired with @18f/identity-rails-i18n-webpack-plugin, it provides a seamless localization experience to retrieve locale data from Rails locale data.

Usage

Usage should provide a behavior similar to Rails Internationalization, where a given key would be expected to match locale data based on the folder structure found in config/locales.

For example, a key of foo.bar.baz, would match the file at config/locales/foo/en.yml (for English locales), whose content includes...

en:
  foo:
    bar:
      baz: Message

Basic

Call the translate function with a key to retrieve the translated message.

# config/locales/messages/en.yml
en:
  messages:
    greeting: Hello world!

import { t } from '@18f/identity-i18n';

t('messages.greeting');
// "Hello world!"

Interpolation

Include an object of variables to interpolate those values in the matched entry.

# config/locales/messages/en.yml
en:
  messages:
    greeting: Hello %{recipient}!

import { t } from '@18f/identity-i18n';

t('messages.greeting', { recipient: 'world' });
// "Hello world!"

Pluralization

An entry which is an object including one or other keys will automatically choose the correct message based on the count variable.

# config/locales/messages/en.yml
en:
  messages:
    greeting:
      one: Hello to you!
      other: Hello to all!

import { t } from '@18f/identity-i18n';

t('messages.greeting', { count: 1 });
// "Hello to you!"

t('messages.greeting', { count: 2 });
// "Hello to all!"

Array Values

An entry may be a single string or an array of strings. Passing an array of key(s) will return an array of messages.

# config/locales/messages/en.yml
en:
  messages:
    greetings:
      - Hello!
      - Howdy!

import { t } from '@18f/identity-i18n';

t(['messages.greetings']);
// ["Hello!", "Howdy!"]