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 /utilities/tacotranslate.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 Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import tacoTranslate from '../utilities/tacotranslate';

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

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

	return (
		<TacoTranslate
			client={tacoTranslate}
			origin={origin}
			locale={locale}
			localizations={localizations}
		>
			<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 tacoTranslate = require('./utilities/tacotranslate');

module.exports = async () => {
	const locales = await tacoTranslate.getLocales();
	const isProduction =
		process.env.TACOTRANSLATE_ENV === 'production' ||
		process.env.VERCEL_ENV === 'production' ||
		(!(process.env.TACOTRANSLATE_ENV || process.env.VERCEL_ENV) &&
			process.env.NODE_ENV === 'production');

	const [projectLocale] = locales;

	return {
		env: {
			TACOTRANSLATE_ORIGIN: process.env.TACOTRANSLATE_ORIGIN,
			TACOTRANSLATE_API_KEY: isProduction
				? process.env.TACOTRANSLATE_PUBLIC_API_KEY
				: process.env.TACOTRANSLATE_SECRET_API_KEY,
			TACOTRANSLATE_DEFAULT_LOCALE: isProduction ? projectLocale : undefined,
		},
		i18n: {
			defaultLocale: projectLocale,
			locales,
		},
	};
};

There are a couple of things to take note of here. First, we’re fetching all the languages you have activated for your translation project. The first string in the response array is the locale code you’ve set for the project.

Now for the crucial part: Deciding whether or not we’re in a production environment. Modify the isProduction check to suit your setup. If we’re in a local, test, or staging environment, we should use the secret read/write API key to make sure new strings are sent for translation. If we‘re in a production environment, we should use the public read key.

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. First, create a new file /utilities/custom-get-static-props.ts.

import {type GetStaticPropsContext} from 'next';
import {type Origin} from 'tacotranslate';
import tacoTranslate from './tacotranslate';

export default async function customGetStaticProps(
	{
		locale = process.env.TACOTRANSLATE_DEFAULT_LOCALE,
		locales,
	}: GetStaticPropsContext,
	additionalOrigins: Origin[] = []
) {
	const origin = process.env.TACOTRANSLATE_ORIGIN;
	const origins = [origin, ...additionalOrigins];
	const localizations = await tacoTranslate.getLocalizations({locale, origins});

	return {
		props: {locale, locales, localizations, origin},
		revalidate: 60,
	};
}

This function takes two arguments: One Next.js Static Props Context object, and an optional array of additional origins to fetch translations from, if you’re using more than one within your app. Also, note the revalidate property on the return statement, which tells Next.js to re-build the page after 60 seconds. This will keep the server side rendered translations up-to-date.

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

import {Translate} from 'tacotranslate/react';
import customGetStaticProps from '../utilities/custom-get-static-props';

export async function getStaticProps(context) {
	return customGetStaticProps(context);
}

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 any language. Get started today!