Skip to main content

Internationalization of JavaScript apps

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 @babel/core
npm install --save @lingui/core

  1. 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 singleton, which is pretty simple:

import { i18n } from "@lingui/core";

// messages.js is generated by the cli
import { messages } from "path-to-locale/en/messages.js";

i18n.load("en", messages);
i18n.activate("en");

Localizing your app​

Once that is done, we can go ahead and use it! Wrap your text in t macro:

import { t } from "@lingui/macro";

t`Hello World!`;
// becomes "Salut le monde!"

const name = "Fred";
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;

plural(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"

select(gender, {
  offset: 1,
  female: plural(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(value, {...}),
  other: plural(value, {...}),
})

Further reading​