Como implementar internacionalização em uma aplicação Next.js que está usando o App Router

À medida que o mundo se torna mais globalizado, é cada vez mais importante que desenvolvedores web construam aplicações capazes de atender usuários de diferentes países e culturas. Uma das principais maneiras de conseguir isso é por meio da internacionalização (i18n), que permite adaptar sua aplicação para diferentes idiomas, moedas e formatos de data.

Neste artigo, vamos explorar como adicionar internacionalização à sua aplicação React Next.js, com renderização do lado do servidor. TL;DR: Veja o exemplo completo aqui.

Este guia é para aplicações Next.js que estão usando o App Router.
Se você estiver usando o Pages Router, consulte este guia em vez disso.

Passo 1: Instale uma biblioteca i18n

Para implementar internacionalização em sua aplicação Next.js, primeiro escolheremos uma biblioteca i18n. Há várias bibliotecas populares, incluindo next-intl. Neste exemplo, no entanto, usaremos TacoTranslate.

TacoTranslate traduz automaticamente suas strings para qualquer idioma usando IA de ponta e o libera do tedioso gerenciamento de arquivos JSON.

Vamos instalá-lo usando npm no seu terminal:

npm install tacotranslate

Passo 2: Crie uma conta gratuita no TacoTranslate

Agora que você instalou o módulo, é hora de criar sua conta no TacoTranslate, um projeto de tradução e as chaves de API associadas. Crie uma conta aqui. É gratuito e não é necessário adicionar um cartão de crédito.

Na interface do aplicativo TacoTranslate, crie um projeto e navegue até a aba de chaves de API. Crie uma chave read e uma chave read/write. Vamos salvá-las como variáveis de ambiente. A chave read é o que chamamos de public, e a chave read/write é secret. Por exemplo, você pode adicioná-las a um arquivo .env na raiz do seu projeto.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Certifique-se de nunca expor a chave de API secreta read/write em ambientes de produção no lado do cliente.

Também vamos adicionar mais duas variáveis de ambiente: TACOTRANSLATE_DEFAULT_LOCALE e TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: O código de localidade padrão de fallback. Neste exemplo, vamos defini-lo como en para inglês.
• TACOTRANSLATE_ORIGIN: A “pasta” onde suas strings serão armazenadas, como a URL do seu site. Leia mais sobre origens aqui.

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

Passo 3: Configurando o TacoTranslate

Para integrar o TacoTranslate ao seu aplicativo, você precisará criar um cliente usando as chaves de API mencionadas anteriormente. Por exemplo, crie um arquivo chamado /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_IS_PRODUCTION === 'true'
			? process.env.TACOTRANSLATE_PROJECT_LOCALE
			: undefined,
});

module.exports = tacoTranslate;

Em breve definiremos automaticamente TACOTRANSLATE_API_KEY e TACOTRANSLATE_PROJECT_LOCALE.

Criar o cliente em um arquivo separado facilita reutilizá-lo mais tarde. getLocales é apenas uma função utilitária com tratamento de erros embutido. Agora, crie um arquivo chamado /app/[locale]/tacotranslate.tsx, onde implementaremos o provedor TacoTranslate.

'use client';

import React, {type ReactNode} from 'react';
import {
	type TranslationContextProperties,
	TacoTranslate as ImportedTacoTranslate,
} from 'tacotranslate/react';
import tacoTranslateClient from '@/tacotranslate-client';

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

Observe o 'use client'; indicando que este é um componente do cliente.

Com o provedor de contexto pronto, crie um arquivo chamado /app/[locale]/layout.tsx, o layout raiz da nossa aplicação. Observe que esse caminho contém uma pasta que utiliza Dynamic Routes, onde [locale] é o parâmetro dinâmico.

import React, {type ReactNode} from 'react';
import {type Locale, isRightToLeftLocaleCode} from 'tacotranslate';
import './global.css';
import tacoTranslateClient from '@/tacotranslate-client';
import TacoTranslate from './tacotranslate';

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

type RootLayoutParameters = {
	readonly params: Promise<{locale: Locale}>;
	readonly children: ReactNode;
};

export default async function RootLayout({params, children}: RootLayoutParameters) {
	const {locale} = await params;
	const origin = process.env.TACOTRANSLATE_ORIGIN;
	const localizations = await tacoTranslateClient.getLocalizations({
		locale,
		origins: [origin /* , other origins to fetch */],
	});

	return (
		<html lang={locale} dir={isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr'}>
			<body>
				<TacoTranslate
					locale={locale}
					origin={origin}
					localizations={localizations}
				>
					{children}
				</TacoTranslate>
			</body>
		</html>
	);
}

A primeira coisa a notar aqui é que estamos usando nosso parâmetro Dynamic Route [locale] para buscar traduções para esse idioma. Além disso, generateStaticParams garante que todos os códigos de locale que você ativou no seu projeto sejam pré-renderizados.

Agora, vamos criar nossa primeira página! Crie um arquivo chamado /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!" />
	);
}

Observe a variável revalidate que instrui o Next.js a reconstruir a página após 60 segundos, mantendo suas traduções atualizadas.

Passo 4: Implementando renderização do lado do servidor

TacoTranslate oferece suporte à renderização do lado do servidor. Isso melhora muito a experiência do usuário ao mostrar o conteúdo traduzido imediatamente, em vez de primeiro exibir um breve flash de conteúdo não traduzido. Além disso, podemos evitar requisições de rede no cliente, pois já temos as traduções necessárias para a página que o usuário está visualizando.

Para configurar a renderização do lado do servidor, crie ou modifique /next.config.js:

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

module.exports = async () => {
	const config = await withTacoTranslate(
		{},
		{
			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'),
		}
	);

	// NOTE: Remove i18n from config when using the app router
	return {...config, i18n: undefined};
};

Modifique a verificação isProduction para adequá-la à sua configuração. Se true, o TacoTranslate disponibilizará a chave de API pública. Se estivermos em um ambiente local, de teste ou de staging (isProduction is false), usaremos a chave de API secreta read/write para garantir que novas strings sejam enviadas para tradução.

Para garantir que o roteamento e o redirecionamento funcionem como esperado, precisaremos criar um arquivo chamado /middleware.ts. Usando Middleware, podemos redirecionar os usuários para páginas apresentadas no idioma de sua preferência.

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

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

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

Certifique-se de configurar o matcher de acordo com a documentação do Middleware do Next.js.

No lado do cliente, você pode alterar o cookie locale para mudar qual é o idioma preferido do usuário. Veja o código de exemplo completo para ideias de como fazer isso!

Passo 5: Implantar e testar!

Terminamos! Sua aplicação React agora será traduzida automaticamente quando você adicionar quaisquer strings a um componente Translate. Observe que apenas ambientes com permissões read/write na chave de API poderão criar novas strings para serem traduzidas. Recomendamos ter um ambiente de staging fechado e seguro onde você possa testar sua aplicação de produção com uma chave de API como essa, adicionando novas strings antes de ir ao ar. Isso impedirá que qualquer pessoa qualquer pessoa roube sua chave de API secreta e evitará potencialmente que seu projeto de tradução seja inflado pela adição de novas strings não relacionadas.

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 over 75 languages. Get started today!