next-translate

In this article, we will show you how to integrate SimpleLocalize with NextJS using next-translate and local files. Next-translate is a library that is gaining popularity among frontend developers. It provides a simple way to manage translations in NextJS apps, and it seems to be a good alternative to next-i18next.

The article is based on a demo application available on GitHub.

Prerequisites

Next-translate by default organizes translations in JSON files that are stored locally. We will place our translations in /locales/{lang}/{ns}.json directory, where:

• {ns} - is a namespace,
• {lang} - is a language key

Namespaces are optional, they are used to group translations. For example, you can have a common namespace for translations that are used across the application and a home namespace for translations that are used only on the home page.

In this example there are two namespaces: common and home and 4 locales: en, es, fr, pl, and the files structure will look like this:

.
├── en
│   ├── common.json
│   └── home.json
├── es
│   ├── common.json
│   └── home.json
├── pl
│   ├── common.json
│   └── home.json
└── fr
    ├── common.json
    └── home.json

Installation

Install next-translate for NextJS

# with npm
npm install --save next-translate

# with yarn
yarn add next-translate

Install SimpleLocalize CLI that will help us to automate import and export workflow.

# macOS / Linux / Windows (WSL)
curl -s https://get.simplelocalize.io/2.7/install | bash

# Windows (PowerShell)
. { iwr -useb https://get.simplelocalize.io/2.7/install-windows } | iex;

Configuration

Let's configure NextJS and next-translate to work with SimpleLocalize CLI.

next-translate

Create a i18n.json file in project root.

{
  "locales": ["en", "es", "fr", "pl"],
  "defaultLocale": "en",
  "pages": {
    "*": ["common"],
    "/": ["home"]
  }
}

Import next-translate configuration file in next.config.js like below:

const nextTranslate = require('next-translate')

module.exports = nextTranslate({
  webpack: (config, { isServer, webpack }) => {
    return config;
  }
})

SimpleLocalize CLI

Create simplelocalize.yml file with CLI configuration in your project root directory.

apiKey: YOUR_PROJECT_API_KEY
downloadFormat: single-language-json
downloadPath: ./locales/{lang}/{ns}.json

uploadFormat: single-language-json
uploadPath: ./locales/{lang}/{ns}.json

Next-translate uses one JSON file per language and namespace, hence we set single-language-json format for both download and upload. You can more learn more about this format here: single-language-json.

Usage

Usage of next-translate is straightforward. You can use useTranslation hook to get translations from JSON files. You can also use namespaces in the useTranslation hook to get translations from a specific namespace.

next-translate

Import useTranslation hook from next-translate package and use t function to get translated text.

import useTranslation from 'next-translate/useTranslation'

//translations from common.json
const { t } = useTranslation('common')
console.log(t('LEARN_MORE')) // output: Learn more

//translations from home.json
const {t: homeT} = useTranslation('home');
console.log(homeT('HELLO_WORLD')) // output: Hello world

SimpleLocalize CLI

Now you can run upload command to upload translations to translation editor.

$ simplelocalize upload

Add --replace if you want to replace translations in the translation editor with the translations from the local files. Otherwise, CLI only adds missing translations and creates new translation keys.

Before we start downloading translations you can add some languages in the Web UI and run auto-translate command to translate your app to multiple languages at once, like below:

$ simplelocalize auto-translate

Optionally, you can translate them manually in the translation editor. Regardless of the method, you can go back to the CLI and use download command to download translations from translation editor.

$ simplelocalize download

Translation editor

The last step is to manage translations in the translation editor, where you can invite translators, adjust translations, and more.

When you add a new language to your project, you can start auto-translation for all languages at once from the Languages tab.

After you finish translating your app, you can run simplelocalize download command to download translations to your local files.

Plurals and interpolation

next-translates works with files in single-language-json file format that keep translations in a simple key-value format, so you can use interpolation and pluralization directly in the translations.

{
  "ITEMS_SIMPLE": "{itemCount} items",
  "ITEMS_PLURAL": "I have {itemCount, plural, =0 {no items} one {1 item} other {# items}}"
}

Learn more about message interpolation.

Resources

• Blog: Next-translate integration
• Blog: Number formatting in JavaScript