Getting started

Getting started

Usage

We recommend that you install x18n using NPM (npm install x18n), but there's a single file build (lib/x18n_build.js) for anyone else that uses AMD or wants a global x18n variable.

Since you'll be using x18n.t a lot we recommend just setting a variable let t = x18n.t for easy access. If you're using ES6 you can also require it at the same time as x18n.

Adding translations

x18n.register(locale, dictionary)

You'll want to register the translations first of all. It's a good idea to save the dictionary objects in JSON files and to load them when needed.

x18n.register('en', {
  language: 'Language',
  user: {
    welcome: 'Welcome %1',
    messages: 'You have %{n} messages.',
    logout: 'Logout',
    count: {
      1: 'There is 1 user online.',
      n: 'There are %1 users online.'
    }
  }
});

// And the German ones.

x18n.register('de', {
  language: 'Sprache',
  user: {
    welcome: 'Willkommen %1',
    messages: 'Du hast %{n} Nachrichten.',
    logout: 'Ausloggen',
    count: {
      1: 'Es ist 1 Benutzer online.',
      n: 'Es sind %1 Benutzer online.'
    }
  }
});

Setting the locale

x18n will auto detect the user locale and look for those translations first. You can also set a locale and a default local. x18n is smart enough to sort the available locales.

x18n.setDefault('de'); // The default value for this is 'en'
x18n.set('en'); // Set the user language

X18n will look for translations in this order, using only available locales:

• Chosen locale (x18n.set) and similiar ones
• Detected locale and similiar ones
• Default locale and similiar ones
• 'en' and similiar ones
• other available locales

So, if x18n can't find a translation for the chosen local, it will look for translations of similiar locales, then for translations for the detected locale and so on. If you want to know what translations are missing, read the dealing with missing translations wiki entry.

Similiar locales

Let's say you got these locales available:

• en
• en-us
• en-au
• de
• fr

Similiar locales for en will be en-us and en-au.

Retrieving translations

You can use the global t function to retrieve translations. We understand that you might use another library with a global t method so, there's t.noConflict to solve this problem.

t('language'); // 'Language'
t('user.logout'); // 'Logout'

Interpolation

X18n's interpolation is compatible with the one used by r18n.

There are two kinds of interpolation: Numeric and explicit interpolation.

t('user.welcome', 'John'); // 'Willkommen John'
t('user.messages', {n: 12}); // 'You have 12 messages.'

Numeric interpolation uses %number and explicit interpolation %{key}. When using numeric interpolation you just add more arguments to the t function, when using explicit interpolation you pass in an object.

Plurals

Let's say you registered this object:

user: {
  count: {
      1: 'There is 1 user online.',
      n: 'There are %1 users online.'
  }
}

Retrieving the right plural is easy:

t('user.count').plural(1); // 'There is 1 user online.'
t('user.count').plural(42); // 'There are 42 users online.'

Updating the UI

You'll want to update the UI everytime the language changes or new translations are added.

Currently there are helper libraries available for:

• React (recommended)
• Handlebars
• jQuery

You can of course also update the UI yourself or write your own adapter.

X18n provides an event system that allows you to get notified if the language changes or the dictionary is updated:

x18n.on(['lang:change', 'dict:change'], function () {
	// Update the UI
});

Events

• lang:change: Triggered everytime the local priority list changes, the old and the new list is passed to the subscriber
• dict:change: Triggered everytime you register new translations, the local of the new translations is passed to the subscriber
• missing-translation: dealing with missing translations