How to implement internationalization in a Next.js application that’s using the App 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 article, 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’s using the App Router.
If you are using the Pages Router, 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. In this example, however, 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_IS_PRODUCTION === 'true'
			? process.env.TACOTRANSLATE_PROJECT_LOCALE
			: undefined,
});

module.exports = tacoTranslate;

We’ll be automatically defining TACOTRANSLATE_API_KEY and TACOTRANSLATE_PROJECT_LOCALE shortly.

Creating the client in a separate file makes it easy to use again later. getLocales is just an utility function with some built-in error handling. Now, create a file named /components/tacotranslate.tsx, where we’ll implement the TacoTranslate provider.

'use client';

import React, {type ReactNode} from 'react';
import ImportedTacoTranslate, {
	type TranslationContextProperties,
} from 'tacotranslate/react';
import tacoTranslate from '@/utilities/tacotranslate';

export default function TacoTranslate({
	locale,
	origin,
	localizations,
	children,
}: TranslationContextProperties & {
	readonly children: ReactNode;
}) {
	return (
		<ImportedTacoTranslate
			client={tacoTranslate}
			locale={locale}
			origin={origin}
			localizations={localizations}
		>
			{children}
		</ImportedTacoTranslate>
	);
}

Note the 'use client'; indicating that this is a client component.

With the context provider now ready to go, create a file named /app/[locale]/layout.tsx, the root layout in our application. Note that this path has a folder utilizing Dynamic Routes, where [locale] is the dynamic parameter.

import React, {type ReactNode} from 'react';
import {isRightToLeftLocaleCode} from 'tacotranslate';
import './global.css';
import tacoTranslate from '@/utilities/tacotranslate';
import TacoTranslate from '@/components/tacotranslate';
import {customGenerateMetadata} from '@/utilities/generate-metadata';

export async function generateStaticParams() {
	const locales = await tacoTranslate.getLocales();
	return locales.map((locale) => ({locale}));
}

type RootLayoutParameters = {
	readonly params: {locale: string};
	readonly children: ReactNode;
};

export default async function RootLayout({
	params: {locale},
	children,
}: RootLayoutParameters) {
	const origins = [process.env.TACOTRANSLATE_ORIGIN];
	const direction = isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr';
	const localizations = await tacoTranslate.getLocalizations({locale, origins});

	return (
		<html lang={locale} dir={direction}>
			<body>
				<TacoTranslate
					locale={locale}
					origin={origin}
					localizations={localizations}
				>
					<div id="content">{children}</div>
				</TacoTranslate>
			</body>
		</html>
	);
}

The first thing to note here is that we’re using our Dynamic Route parameter [locale] to fetch translations for that language. Additionally, generateStaticParams is making sure all the locale codes you have activated for your project are pre-rendered.

Now, let’s build our first page! Create a file named /app/[locale]/page.tsx.

import React from 'react';
import {Translate} from 'tacotranslate/react';

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

Note the revalidate variable that tells Next.js to re-build the page after 60 seconds, and keep your translations up-to-date.

Step 4: Implementing server side rendering

TacoTranslate supports server side rendering. This vastly 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 the translations we need for the page the user is viewing.

To set up server side rendering, create or modify /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_PROJECT_LOCALE: projectLocale,
			TACOTRANSLATE_PROJECT_LOCALES: JSON.stringify(locales),
			TACOTRANSLATE_IS_PRODUCTION: String(isProduction),
		},
	};
};

There are a few things to note here. First, we’re fetching all the languages you have activated for your translation project. The first string in this response array will be the origin locale code you set for the project on creation.

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.

To ensure routing and redirection works as expected, we’ll need to create a file named /middleware.ts. Using Middleware, we can redirect users to pages presented in their preferred language.

import {type NextRequest} from 'next/server';
import {middleware as tacoTranslateMiddleware} from 'tacotranslate/next';
import tacoTranslate from '@/utilities/tacotranslate';

export const config = {
	matcher: ['/((?!api|_next|favicon.ico).*)'],
};

export async function middleware(request: NextRequest) {
	return tacoTranslateMiddleware(tacoTranslate, request);
}

Make sure to set up the matcher in accordance with Next.js Middleware documentation.

On the client, you can alter the locale cookie to change what the user’s preferred language is. Please see the complete example code for ideas on how to do this!

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 Pages 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!