DEV Community: i18nexus

Next.js — The Scalable Way to Internationalize Using next-i18next

i18nexus — Wed, 07 Jul 2021 04:46:46 +0000

In this tutorial, we’re going to learn how to internationalize a Next.js app using next-i18next. To make things even easier, we’re going to use i18nexus to auto-translate and manage our strings for us.

Let’s go! ⚡️

Getting Started

Let’s bootstrap together a simple Next.js application using create-next-app:

npx create-next-app

After typing in a title for our app, we will cd into the app directory and install next-i18next:

npm install next-i18next --save

Time to internationalize! 🌐

Configuration

With the release of Next.js v10, we received an awesome built-in solution for handling internationalized routing and locale detection. next-i18next is designed to work hand-in-hand with this new internationalization support.

To use next-i18next, we need to create an i18next config file at the root of our app called next-i18next.config.js. This will define the languages we want our app to use. Let’s support English and Swedish.

We need to initialize our defaultLocale (the default language for our app) and locales (a list of languages that we want our app to support):

next-i18next.config.js

module.exports = {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'sv']
  },
  reloadOnPrerender: process.env.NODE_ENV === 'development'
}

It is also recommended to enable the reloadOnPrerender option in development. When this option is enabled, next-i18next will reload our translations when we make changes to our translation files.

Next, we need to add the i18n property to next.config.js by simply importing the i18n object from the i18next config:

next.config.js

const { i18n } = require('./next-i18next.config');

module.exports = {
  i18n,
  reactStrictMode: true
}

The next-i18next library uses the same i18n config structure that Next requires. So instead of having to manage the same settings in two places, we simply import the next-i18next config into next.config.js as recommended in the next-i18next docs.

appWithTranslation

One last step for setting up next-i18next is to wrap our app with the appWithTranslation HOC (higher-order component). This component will provide our i18next context to all of our pages. Our _app.js file should look like this:

_app.js

import '../styles/globals.css';
import { appWithTranslation } from 'next-i18next';

const MyApp = ({ Component, pageProps }) => <Component {...pageProps} />

export default appWithTranslation(MyApp);

And now we’re ready to go! 🚀

i18nexus Integration

If you’ve used i18next before but have never used it with i18nexus, you’re in for a treat.

i18nexus makes managing our translations a million times easier by storing our app texts in the cloud. It even machine translates our strings using DeepL and Google Translate to as many languages as we need. Whenever we’re ready to hire professional translators, we just invite them to our i18nexus project and let them edit the translations!

Let’s do it!

If you don’t already have an i18nexus account, go to i18nexus.com and sign up for a free account. After naming our project we’ll be directed to our language dashboard:

i18nexus project dashboard

The first language tile is our base language, which should match the language we set for the defaultLocale property in next-i18next.config.js.

Next, we’ll click Add Language to select the locales that we want our app to support. Since we already added sv (Swedish) to our locales list in next-i18next.config.js, we’ll select Swedish:

Adding Swedish as a supported language

Now let’s click Open Project in the top right corner to go to the Strings Management page where we will be adding our strings.

Namespaces

At the top of the page, there is a dropdown labeled namespaces, which contains one namespace already created for us called “default”.

It is convention to have one namespace for each Page in your app, as well as a namespace called “common” for common strings that appear on more than one page.

Let’s rename the “default” namespace to “common”, and then create a namespace called “home” to be used for our Home page:

Managing namespaces

Important: Even though we will not be using the “common” namespace in this walkthrough, it is required. We will discuss why shortly. 🙂

To add our first string, click Add String. I’m going to add a string in my “home” namespace that says “Hello, and welcome to my app!”:

Adding a new string with key “welcome_msg”

The key is how we will reference this string in our code.

The value is the text that will be rendered in our app.

The details field is optional. It is meant to provide any extra information about the context of our string for when we’re ready to bring in professional translators. We can even add an image here for more context.

After adding the string, we can expand the row to see our automatic translations (using DeepL and Google Translate):

New strings are automatically translated to all of our supported languages

Connecting our Translations

We’re going to use the i18nexus CLI to import our i18nexus translations in our Next.js app:

npm install i18nexus-cli -g

If we go to the Export tab in i18nexus, we’ll be able to find our project API key:

i18nexus Export tab

In our app directory, all we have to do is run i18nexus pull with our API key and all of our latest translations will be downloaded to our project directory!

$ i18nexus pull --api-key <YOUR_API_KEY>

Now all our translations will be located in public/locales, which is where next-i18next expects them.

We can also add our API key as an environment variable named I18NEXUS_API_KEY so that we can just use i18nexus pull without typing your API key every time.

To do this, we simply create an environment variable file called .env at the root of our app that contains I18NEXUS_API_KEY=YOUR_API_KEY.

Bonus Points:

If we want to automatically pull our latest translations every time we start up our dev server or build our app, all we have to do is update our scripts in package.json:

package.json

...
"scripts": {
   "dev": "i18nexus pull && next dev",
   "build": "i18nexus pull && next build",
   "start": "i18nexus pull && next start"
 }
...

If you do this, you should also install the i18nexus-cli as a dev dependency:

npm install i18nexus-cli --save-dev

Rendering our Translations

Right now our app is just using the boilerplate create-next-app home page:

Boilerplate create-next-app

serverSideTranslations

In our home page we need to import a function called serverSideTranslations from next-i18next. This function needs to be run in getStaticProps on each page-level component. It provides our page with our translations and configuration options as props. We’ll add this to our pages/index.js:

pages/index.js

import { serverSideTranslations } from 'next-i18next/serverSideTranslations';

export async function getStaticProps({ locale }) {
  return {
    props: {
      ...(await serverSideTranslations(locale, ['home'])),
    }
  } 
}

...

The severSideTranslations function accepts a locale as the first argument and the namespaces required for this page as the second argument. This ensures that our app only has to load the namespaces needed for the page. The locale is passed down from getStaticProps by Next.

useTranslation

Lastly, let’s import the useTranslation hook from next-i18next. The useTranslation hook contains a function called t that takes a key as an argument and renders the proper translation.

I’m going to clear out most of the boilerplate that was generated by create-next-app and just render a single line of text on my Home page. Here’s my entire home page using useTranslation to render my welcome_msg string:

pages/index.js

import Head from "next/head";
import styles from "../styles/Home.module.css";
import { serverSideTranslations } from "next-i18next/serverSideTranslations";
import { useTranslation } from "next-i18next";

export async function getStaticProps({ locale }) {
  return {
    props: {
      ...(await serverSideTranslations(locale, ["home"]))
    }
  };
}

export default function Home() {
  const { t } = useTranslation();

  return (
    <div className={styles.container}>
      <Head>
        <title>Create Next App</title>
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main className={styles.main}>
        <h1 className={styles.title}>{t("home:welcome_msg")}</h1>
      </main>
    </div>
  );
}

Notice that when we use useTranslation, we need to specify the namespace with the key like so: home:welcome_msg.

The only time we do not need to specify the namespace in useTranslation is when the key we are referencing is in our default namespace. By default, i18next sets our default namespace to “common”. If you’d like, you can change your default namespace via the defaultNS config option in next-i18next.config.js.

Now lets run npm run dev, and check it out!

http://localhost:3000

Rendering English translation

We did it! 🎉

Using Other Languages

Right now, our app is using en because that is what we set as our defaultLocale in next.config.js.

If you recall, we added Swedish (sv) to our list of locales. To see our app in Swedish, all we have to do is add /sv to the end of the URL. If a user’s browser language is set to Swedish, Next will automatically redirect them to the /sv route. Let’s see what out app looks like in Swedish:

http://localhost:3000/sv

Rendering Swedish translation

Looks like we’re internationalization pros! 😎

To learn more about internationalized routing and changing to different languages, take a quick read of the Next.js docs here.

That’s all folks!

You now have a Next.js app fully set up with internationalized routing, i18next integration, and automated translation management with i18nexus!

React Localization with i18next and Google Translate

i18nexus — Fri, 06 Nov 2020 06:43:29 +0000

We’re going to take a look at localizing a React app with react-i18next and i18nexus. i18next is one of the most popular JavaScript localization libraries around, but its power is truly unleashed when used with i18nexus and its awesome API for scalable translation management and Google Translate automation.

Start up the project

I am going to bootstrap together a simple React application using create-react-app:

npx create-react-app my-app

Next, let’s cd into the React app directory and install a few i18next packages:

npm install i18next react-i18next i18next-http-backend i18next-browser-languagedetector --save

Don’t worry, these packages are all very lightweight and easy to use. Here’s what they do:

i18next: The base i18next library.
react-i18next: Gives us React-friendly hooks, components, and functions for i18next.
i18next-http-backend: Let’s us use AJAX for loading translation files.
i18next-browser-languagedetector: Detects your users’ preferred language based on browser settings.

Let’s start up our development server with npm start

Here we go!

i18next + i18nexus = 🔥

Ever since I started using i18nexus, I haven’t used i18next without it. i18nexus allows us to store our app strings in the cloud and automatically translates them to as many languages as we want. Whenever you’re ready to hire professional translators, you simply invite them to the i18nexus project and you’re done.

In one word: AWESOME.

Go to i18nexus.com and sign up for a free account. After naming your project you’ll be directed to your language dashboard:

The first language tile is your base language — the language you’re translating from.

Click “Add Language” to select a language that you want your app to use. You can select as many as you want. I think I’ll select Spanish:

Next, let’s go to the page where we’ll be adding our strings. Click Open Project in the top right corner to be directed to the Strings Management page.

To add your first string, click Add String. I’m going to add a string that welcomes users to my app:

The key is how you’ll reference this string in your app.

The value is the text that will be displayed in your app.

The details field is optional. It is meant to provide any extra information about the context of your string for when you’re ready to bring in professional translators. You can even add an image here for more context!

After adding the string, you can expand the row to see the auto-translations:

Let’s connect to our app

Back in the Export tab, we can find an i18next configuration code snippet to connect our React app to our i18nexus translations. Make sure to copy from the React tab:

Let’s create a file called i18n.js in our src folder, and then paste in the code snippet:

*Learn more about i18next configuration options here.

This code is asynchronously fetching our strings from the i18nexus API. I’ve never had problems with load speed, but for production environments it is recommended to use the i18nexus CDN and implement browser caching. We won’t go over that in this tutorial, but you can learn more about that here.

I’m going to import the i18n.js file in index.js, and then use React’s Suspense component to prevent rendering until the request is complete.

My index.js file now looks like this:



import React, { Suspense } from "react";
import ReactDOM from "react-dom";
import "./index.css";
import App from "./App";
import * as serviceWorker from "./serviceWorker";
import "./i18n.js";

ReactDOM.render(
  <React.StrictMode>
    <Suspense fallback="loading">
      <App />
    </Suspense>
  </React.StrictMode>,
  document.getElementById("root")
);

serviceWorker.unregister();

Rendering our strings

When the app loads, it is fetching all of our strings from i18nexus. Right now, my app just has the default create-react-app page with hardcoded strings:

Let’s replace the text with our own strings!

useTranslation

To use our strings, we have to import the useTranslation hook from react-i18next. This hook returns a function named t that we can use to get a string by passing the key as the first argument.

Back in i18nexus, the string I added has the key “welcome_msg”. Let’s render it. My App.js file now looks like this:



import React from "react";
import logo from "./logo.svg";
import "./App.css";
import { useTranslation } from "react-i18next";

function App() {
  const { t } = useTranslation();

  return (
    <div className="App">
      <header className="App-header">
        <img src={logo} className="App-logo" alt="logo" />
        <p>{t("welcome_msg")}</p>
      </header>
    </div>
  );
}

export default App;

And here it is!

Since my personal browser language is set to English, i18next has automatically chosen to render the English version of the string. This is thanks to the i18next-browser-languagedetector library!

To let the user choose their language, you would simply create a dropdown that calls i18next.changeLanguage(<language_code>) on change. Of course you can read more about all the i18next functions in the i18next docs.

For now, if you want to preview what your app would look like in another language, add the lng query parameter to the URL. If I load the app with http://localhost:3000/?lng=es, i18next will use the Spanish translations:

AWESOME!

Interpolation

Let’s add another string to i18nexus that uses interpolation. (Learn more about i18next interpolation here)

In i18nexus, I’m going to create a string with the value “My name is {{name}}”. i18next uses double curly braces for interpolation:

Now let’s use the t function with interpolation:



import React from "react";
import logo from "./logo.svg";
import "./App.css";
import { useTranslation } from "react-i18next";

function App() {
  const { t } = useTranslation();
  const userName = "David";

  return (
    <div className="App">
      <header className="App-header">
        <img src={logo} className="App-logo" alt="logo" />
        <p>{t("welcome_msg")}</p>
        <p>{t("my_name", { name: userName })}</p>
      </header>
    </div>
  );
}

export default App;

And now we see the interpolated value:

Your app has access to all strings and translations immediately after you add them to i18nexus. I love it.

Now I’m going to add German to my project in the i18nexus dashboard:

When you add another language to your i18nexus project, remember to update the supportedLngs parameter in your i18n.js file by adding the new language code to the array.

Alternatively, you can copy/paste the code snippet from the Export tab again. I’m just going to manually add “de” to my supportedLngs:



i18next
  .use(HttpBackend)
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: "en",

    ns: ["default"],
    defaultNS: "default",

    supportedLngs: ["en", "es", "de"],

    backend: {
      loadPath: loadPath
    }
  });

Now let’s visit http://localhost:3000/?lng=de to see our app in German:

Awesome! (Or should I say “das ist fantastisch!”)

To sum it up

i18next and i18nexus are an amazing duo for scalable localization in React. We have only scratched the surface with the customization available in both i18next and i18nexus, but hopefully this was enough to get you up and going! Feel free to ask any questions in the comments.