next-i18next

In this article, you will learn how to configure and use i18next for Next.js using next-i18next library and how to manage translations via web translation editor. We will use SimpleLocalize CLI to upload and download translations, if you would like to configure i18next to automatically create missing keys and update translations in your app, please refer to the i18next integration tutorial.

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

Prerequisites

In this example, we will keep translations in the /public/locales/{lang}/{ns}.json directory, where lang is a language (or locale) code (e.g.: en, es, fr_FR, pl) and ns is a namespace (e.g.: common and home).

Using namespaces is 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.

Our file structure will look like this:

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

Every directory contains two JSON files with translation for each namespace, common and home, every JSON file contains translations for a specific language/locale.

Installation

We will need to add next-i18next dependency to our project and install command-line tool to automate the process of uploading and downloading translations from the translation editor.

Install next-i18next

Please install next-i18next library in your project.

# NPM
npm install --save next-i18next

# Yarn
yarn add next-i18next

Install SimpleLocalize CLI

SimpleLocalize CLI does not require any additional dependencies, you can install it on any operating system, including Windows, macOS (Intel and ARM), and Linux.

# 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

Once we have installed the required dependencies, we need to configure our NextJS application and SimpleLocalize CLI.

next-i18next

Create next-i18next.config.js file in project root.

module.exports = {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'pl', 'fr_FR'],
  },
};

Import the newly created file in next.config.js

const {i18n} = require("./next-i18next.config");
const nextConfig = {
  reactStrictMode: true,
  i18n
}

module.exports = nextConfig

SimpleLocalize CLI

SimpleLocalize CLI configuration is stored in the simplelocalize.yml file. We will use it to configure the API key and paths to translation files, so we won't have to provide them every time we run the CLI as arguments. Create simplelocalize.yml file in your project root directory.

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

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

Please note that the uploadPath and downloadPath must match the path to translation files in your project.

Usage

Now we can wrap things up and start using the translations in our NextJS application.

next-i18next

To use translations in your NextJS application, you can use useTranslation hook from next-i18next library like this:

//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 use the SimpleLocalize CLI to upload and download translations from the translation editor.

$ simplelocalize upload

Optionally, you can add --replace argument to update existing translations. It's helpful when you update translations directly in the JSON files, and you want to push them to the translation editor. Without this option, the CLI will only add missing translations and new keys.

If you added to your project new languages you can run simplelocalize auto-translate command to translate your app to multiple languages at once.

After that you can download translations to your local files for all languages:

$ simplelocalize download

Managing translations

If you followed the steps above, you should have your translations in the translation editor along with auto-translated strings for added languages. You can manage them in the Translations tab, adjust translations, invite translators, and more.

You can also start auto-translation for all languages at once from the Languages tab or set up an automation to translate new keys automatically.

Interpolation and plurals

next-i18next uses i18next under the hood, hence interpolation and pluralization work the same way as in i18next. Pluralization, interpolation and variables are stored directly in the translations in single-language-json format, can read more about it here: message interpolation in single-language-json format.

Conclusion

In this article, you learned how to configure and use i18next for Next.js using next-i18next library with local files and how to manage and auto-translate strings via the web translation editor and CLI. If you have any questions or need help, please contact us at [email protected]