How to implement internationalization in a Next.js application that’s using the Pages Router

As the world becomes more globalized, it's increasingly important for web developers to build applications that can cater to users from different countries and cultures. One of the key ways to achieve this is through internationalization (i18n), which allows you to adapt your application to different languages, currencies, and date formats.

In this tutorial, we'll explore how to add internationalization to your React Next.js application, with server side rendering. TL;DR: See the full example here.

This guide is for Next.js applications that are using the Pages Router.
If you are using the App Router, please see this guide instead.

Step 1: Install a i18n library

To implement internationalization in your Next.js application, we’ll first choose an i18n library. There are several popular libraries, including next-intl. However, in this example, we'll be using TacoTranslate.

TacoTranslate automatically translates your strings to any language using cutting-edge AI, and frees you from the tedious management of JSON files.

Let’s install it using npm in your terminal:

npm install tacotranslate

Step 2: Create a free TacoTranslate account

Now that you’ve got the module installed, it’s time to create your TacoTranslate account, a translation project, and associated API keys. Create an account here. It’s free, and doesn’t require you to add a credit card.

Within the TacoTranslate application UI, create a project, and navigate to its API keys tab. Create one read key, and one read/write key. We’ll save them as environment variables. The read key is what we call public and the read/write key is secret. For example, you could add them to a .env file in the root of your project.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Be sure to never leak the secret read/write API key to client side production environments.

We’ll also add two more environment variables: TACOTRANSLATE_DEFAULT_LOCALE and TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: The default fallback locale code. In this example, we’ll set it to en for English.
• TACOTRANSLATE_ORIGIN: The “folder” where your strings will be stored, such as the URL of your website. Read more about origins here.

TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com

Step 3: Setting up TacoTranslate

To integrate TacoTranslate with your application, you’ll need to create a client using the API keys from earlier. For example, create a file named /tacotranslate-client.js.

const {default: createTacoTranslateClient} = require('tacotranslate');

const tacoTranslate = createTacoTranslateClient({
	apiKey:
		process.env.TACOTRANSLATE_SECRET_API_KEY ??
		process.env.TACOTRANSLATE_PUBLIC_API_KEY ??
		process.env.TACOTRANSLATE_API_KEY ??
		'',
	projectLocale: process.env.TACOTRANSLATE_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

We’ll be automatically defining TACOTRANSLATE_API_KEY shortly.

Creating the client in a separate file makes it easier to use again later. Now, using a custom /pages/_app.tsx, we’ll add the TacoTranslate provider.

import React from 'react';
import {type AppProps} from 'next/app';
import {type Origin, type Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import TacoTranslateHead from 'tacotranslate/next/head';
import tacoTranslate from '../tacotranslate-client';

type PageProperties = {
	origin: Origin;
	locale: Locale;
	locales: Locale[];
	localizations: Localizations;
};

export default function App({Component, pageProps}: AppProps<PageProperties>) {
	const {origin, locale, locales, localizations} = pageProps;

	return (
		<TacoTranslate
			client={tacoTranslate}
			origin={origin}
			locale={locale}
			localizations={localizations}
		>
			<TacoTranslateHead rootUrl="https://your-website.com" locales={locales} />
			<Component {...pageProps} />
		</TacoTranslate>
	);
}

If you already have custom pageProps and _app.tsx, please extend the definition with the properties and code from above.

Step 4: Implementing server side rendering

TacoTranslate allows for server side rendering of your translations. This greatly improves the user experience by showing translated content immediately, instead of a flash of untranslated content first. Additionally, we can skip network requests on the client, because we already have all the translations we need.

We’ll start by creating or modifying /next.config.js.

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = {};

	return withTacoTranslate(config, {
		client: tacoTranslateClient,
		isProduction:
			process.env.TACOTRANSLATE_ENV === 'production' ||
			process.env.VERCEL_ENV === 'production' ||
			(!(process.env.TACOTRANSLATE_ENV || process.env.VERCEL_ENV) &&
				process.env.NODE_ENV === 'production'),
	});
};

Modify the isProduction check to suit your setup. If true, TacoTranslate will surface the public API key. If we’re in a local, test, or staging environment (isProduction is false), we’ll use the secret read/write API key to make sure new strings are sent for translation.

Up until now, we’ve only set the Next.js application up with a list of supported languages. The next thing we’ll do is fetch translations for all your pages. To do that, you’ll use either getTacoTranslateStaticProps or getTacoTranslateServerSideProps based on your requirements.

These functions take three arguments: One Next.js Static Props Context object, configuration for TacoTranslate, and optional Next.js properties. Note that revalidate on getTacoTranslateStaticProps is set to 60 by default, so that your translations stay up-to-date.

To use either function in a page, let’s assume you’ve got a page file like /pages/hello-world.tsx.

import {Translate} from 'tacotranslate/react';
import getTacoTranslateStaticProps from 'tacotranslate/next/get-static-props';
import tacoTranslateClient from '../tacotranslate-client';

export async function getStaticProps(context) {
	return getTacoTranslateStaticProps(context, {client: tacoTranslateClient});
}

export default function Page() {
	return <Translate string="Hello, world!"/>;
}

You should now be able to use the Translate component to translate strings within all of your React components.

import {Translate} from 'tacotranslate/react';

function Component() {
	return <Translate string="Hello, world!"/>
}

Step 5: Deploy and test!

We’re done! Your React application will now be translated automatically when you add any strings to a Translate component. Note that only environments with read/write permissions on the API key will be able to create new strings to be translated. We recommend having a closed and secured staging environment where you can test your production application with an API key like that, adding new strings before going live. This will prevent anyone anyone from stealing your secret API key, and potentially bloating your translation project by adding new, unrelated strings.

Be sure to check out the complete example over at our GitHub profile. There, you’ll also find an example of how to do this using the App Router! If you encounter any problems, feel free to reach out, and we’ll be more than happy to help.

TacoTranslate lets you automatically localize your React applications quickly to and from over 75 languages. Get started today!