getting-started.md

Getting started

Getting started

Installation

i18next can be added to your project using npm or yarn:

# npm
$ npm install i18next --save

# yarn
$ yarn add i18next

The default export is UMD compatible (commonjs, requirejs, global).

In the /dist folder you may find additional builds for commonjs, es6 modules. Optimized to load i18next in webpack, rollup, ... or node.js. The correct entry points are already configured in the package.json so there should be no extra setup to get the best build option.

Load from CDN

You can also directly add a script tag loading i18next from one of the CDNs providing it:

unpkg.com

• https://unpkg.com/i18next/dist/umd/i18next.js
• https://unpkg.com/i18next/dist/umd/i18next.min.js

esm or cjs:

• https://unpkg.com/i18next/dist/esm/i18next.js
• https://unpkg.com/i18next/dist/cjs/i18next.js

Make sure to use a fixed version in production like https://unpkg.com/[email protected]/dist/umd/i18next.js as passing no version will redirect to latest version which might contain breaking changes in future.

cdnjs.com

• https://cdnjs.com/libraries/i18next

Important Caveat

Before we dive into the first sample, please note the following: By default, i18next uses a key-based notation to look up translations, which comes with the benefit of additional structure for your translation files.

The downside of this is that your keys must not be in natural language — the names of the keys are not used as fallback content and the key names must not include reserved characters : and . since those are used by i18next.

If you prefer using natural language in keys, please read the fallback guide.

Basic sample

Please be aware these samples are just showing basic usage of the core functionality. For production usage please consider using one of our framework integrations to get better and simpler integrations (Setting innerHTML is just done to show how it works).

import i18next from 'i18next';

i18next.init({
  lng: 'en',
  debug: true,
  resources: {
    en: {
      translation: {
        "key": "hello world"
      }
    }
  }
}, function(err, t) {
  // initialized and ready to go!
  document.getElementById('output').innerHTML = i18next.t('key');
});

Or using Promises:

i18next.init({
  lng: 'en',
  debug: true,
  resources: {
    en: {
      translation: {
        "key": "hello world"
      }
    }
  }
}).then(function(t) {
  // initialized and ready to go!
  document.getElementById('output').innerHTML = i18next.t('key');
});

As you might see, this basic sample provides only one language directly added on init… let's extend this to have buttons to change language from English to German:

source code

This is a working sample showing translated text. To learn more, have a look at the following extended sample:

Extended sample

The extended sample adds the language detector for our browser and the xhr-backend to load translation files from this documentation's i18next-gitbook repo.

source code

You should now have an idea about how to achieve the basic setup. It's time to learn more about:

• The translation functions like interpolation, formatting and plurals.
• Find an extension for your project, eg. react-i18next, jquery-i18next and others. Using those wrappers around i18next makes using i18next a lot simpler in your project. Most of such modules come with extended examples.
• Find out more about the configuration options.
• Add a language detector to detect the preferred language of your user
• Add a backend plugin to load the translations from the server or filesystem