How to: Localise your React App with LinguiJS and Localazy

Do you have an app that you use and you want to localize it? Localizing is very important to ensure that all people can use your app with ease. With Localazy and LinguiJS you can achieve it easily (and for free)!

Localazy is a free translation management system to help developers and translators focus on their jobs and make the translation process seamless. It provides a pro-active translation memory called ShareTM which provides highly accurate automatic translations for even easier localization.

App setup

Let's start with the React app. Create a new project with the following command:

npx create-react-app localazy-react-example
cd localazy-react-example

Open the newly created project and install LinguiJS for in-app translation management.

npm install --save-dev @lingui/cli @babel/core babel-core@bridge
npm install --save-dev @lingui/macro babel-plugin-macros  # required for macros
npm install --save @lingui/react

Localazy setup and integration

Sign up on Localazy and create a new app. I will use English as a source language, but you can choose any other. Then on the integration screen, select JSON. We will upload the source strings in a bit.

Afterwards, you can install Localazy's CLI for Linux, MacOS or Windows.

Come back to your project. In the root folder, create a file called localazy.json and paste the following. Make sure to fill in your writeKey and readKey which you can retrieve from your app either under the settings tab or in the first step of the JSON CLI guide on the select integration screen.

{
  "writeKey": "your-write-key", 
  "readKey": "your-read-key",

  "upload": {
    "type": "json",
    "files": "src/locales/en.json"
  },

  "download": {
    "files": "src/locales/${lang}.json"
  }
}

Then, we need to create a file called .linguirc in our root directory. Fill it in as so, make sure to include whatever locales you use. In this article we'll use en and es.

{
   "catalogs": [{
       "path": "src/locales/{locale}",
       "include": "src"
   }],
   "sourceLocale": "en",
   "locales": ["en", "es"],
   "format": "minimal"
}

Afterwards, we need to do a little modification to your package.json file. Add the following command:

{
   "scripts": {
      ...

      "localise": "localazy download && lingui extract && lingui compile"
   }
}

Now, we can create a ./src/locales folder. This is the folder in which we will store all of our locale files. Create a file called en.json in the ./src/locales folder and paste the following:

{
  "welcome": "Welcome, {name}",
  "today": "Today is {date}.",
  "thatsAll": "That's all for today!"
}

You can change these as you please. That's just an example of the kinds of things you can do. We are almost ready. Let's upload the source English phrases to Localazy. Run localazy upload and you should see your strings on the project screen (you need to refresh the page). ✨ Magical! ✨

Go to Settings and scroll down. You should see three options. Make sure Use community translations (ShareTM) is switched on.

Learn more about how ShareTM works.

At this point, you may add new languages, for which you can use automatic or manual translations. Automatic translations use highly accurate community translations, so they are generally very precise. However, they support translations only from English at the moment, so you need to have the English language added. It does not have to be your source language though.

Before downloading, you need to review automatically translated strings. Otherwise, they have only a candidate status and won't be published. In case you, as an owner, translate anything, the strings are automatically accepted without the review process. Try to add Spanish language and review the suggested phrases or translate them manually (it does not need to be proper Spanish).

Now, run npm run localise to download these new files and set them up with LinguiJS. And just like that, your app is almost done! It's time to get into the nitty-gritty.

Using Localazy translations with LinguiJS

Here, we are going to give a brief example. LinguiJS already has an amazing guide here

In your index.js file, add these lines:

Change these imports to match your project. We are just creating a basic welcome page.

import React from 'react'
import { render } from 'react-dom'
import Welcome from './welcome.js'
import { i18n } from '@lingui/core'
import { I18nProvider } from '@lingui/react'


const locale = "es" // or whatever you need it to be
const catalog = require(`./locales/${locale}.js`)
i18n.load(locale, catalog.messages)
i18n.activate(locale)

const App = () => (
  <I18nProvider i18n={i18n}>
    <Welcome  name="Joe" />
  </I18nProvider>
)

render(<App />, document.getElementById('root'))

And in your welcome.js file, paste this:

import React from 'react'
import { Trans } from '@lingui/macro';

const Welcome = ({name}) => {
  const date = new Date().toString() // Date will not be translated, you can use more advanced techniques to do so
   return (
     <div>
       <h1><Trans>welcome</Trans> {name}</h1>
       <p><Trans>today</Trans> {date}</p>
       <footer><Trans>thatsAll</Trans></footer>
      </div>
   )
}

export default Welcome;

As you can see, to translate with Lingui, we have surrounded the keys with the <Trans></Trans> tags.

You may check out the final repo here. Remember, this is just a sample, you will have to tweak this to fit into your application, however, this is a great first step to ensure that your project is ready to be localized and allow everyone to use your app, regardless of what languages they speak.

As always, please post your questions, comments, and concerns below.