Tutorial - Internationalization of JavaScript apps

Warning

This is a draft of tutorial. Feel free to send a PR if you want to contribute.

In this tutorial, we’ll learn how to use LinguiJS’s internationalization features that do not depend on React. We’ll take a minimalist approach and cover the main functions from the @lingui/core package.

Installing LinguiJS

LinguiJS isn’t just a package. It’s a set of tools which helps you to internationalize. You can pick whichever tool you want to use in your project. We’re trying to use most of them to show the full power of LinguiJS.

Let’s start with the three major packages:

@lingui/cli

CLI for i18n management and working with message catalogs

@lingui/core

The core library responsible for translation and handling of message catalogs

@lingui/macro

Transforms messages wrapped in tagged template literals to ICU MessageFormat and validates them.

  1. Install @lingui/cli, @lingui/macro, babel-plugin-macros and Babel core packages as a development dependencies and @lingui/core as a runtime dependency:

    npm install --save-dev @lingui/cli @lingui/macro babel-plugin-macros
npm install --save @lingui/core

# If you use Babel 7:
npm install --save-dev babel-core@bridge @babel/core

# If you use Babel 6:
npm install --save-dev babel-core

    If you use Yarn, add following:

    yarn add --dev @lingui/cli @lingui/macro babel-plugin-macros
yarn add @lingui/core

# If you use Babel 7:
yarn add --dev babel-core@bridge @babel/core

# If you use Babel 6:
yarn add --dev babel-core

  2. Add macros plugin to Babel config (e.g: .babelrc):

    {
  "plugins": [
    "macros"
  ]
}

Now we have the environment up and running and we can start internationalizing our app!

Setting up i18n

First we need to setup the i18n object, which is pretty simple:

import { setupI18n } from '@lingui/core'

// messages.js is generated by the cli
import englishMessages from 'path-to-locale/en/messages.js';


// setup the i18n object with active language and catalogs
let i18n = setupI18n({
  language: 'en',
  catalogs: {
    en: englishMessages,
  },
});

Localizing your app

Once that is done, we can go ahead and use it! Wrap you text in t macro and pass it to i18n._() method:

import { t } from "@lingui/macro"

i18n._(t`Hello World!`)
// becomes "Salut le monde!"

const name = "Fred"
i18n._(t`My name is ${ name }`)
// becomes "Je m'appelle Fred"

Plurals and selections are possible using plural and select methods:

import { plural } from "@lingui/macro"

const count = 42

i18n._(plural({
  value: count,
  one: "# book",
  other: "# books"
}))
// becomes "42 livres"

It’s also possible to nest message formats. Each message format method in i18n has a standalone companion, which only returns message without performing the translation:

import { t, select, plural } from "@lingui/macro"

i18n._(select({
  value: gender,
  offset: 1,
  female: plural({
    value: numOfGuests,
    offset: 1,
    0: t`${host} does not give a party.`,
    1: t`${host} invites ${guest} to her party.`,
    2: t`${host} invites ${guest} and one other person to her party.`,
    other: t`${host} invites ${guest} and # other people to her party.`
  }),
  male: plural({...}),
  other: plural({...}),
}))