Getting started

Getting started

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.

X18n also had a second concept of interpolation: Dynamic data bindings. These are incredibly useful when you need interpolation and plurals to change dynamically or you always want to interpolate the same values.

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.

If you use jQuery, you can use the jQuery adapter. All you have to do is to add attributes to your HTML and the adapter will take car of updating the UI for you.

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
});