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 os desenvolvedores web construam aplicações que possam 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 a diferentes idiomas, moedas e formatos de data.

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

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

Passo 1: Instale uma biblioteca i18n

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

O TacoTranslate traduz automaticamente suas strings para qualquer idioma usando IA de ponta, e libera você da gestão tediosa dos 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 TacoTranslate, um projeto de tradução e as chaves API associadas. Crie uma conta aqui. É grátis e não requer que você adicione um cartão de crédito.

Dentro da interface do aplicativo TacoTranslate, crie um projeto e navegue até a aba de chaves 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 vazar a chave secreta read/write da API para os ambientes de produção do lado do cliente.

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

• TACOTRANSLATE_DEFAULT_LOCALE: O código do locale 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 origins aqui.

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

Passo 3: Configurando o 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_IS_PRODUCTION === 'true'
			? process.env.TACOTRANSLATE_PROJECT_LOCALE
			: undefined,
});

module.exports = tacoTranslate;

Nós estaremos definindo automaticamente TACOTRANSLATE_API_KEY e TACOTRANSLATE_PROJECT_LOCALE em breve.

Criar o cliente em um arquivo separado facilita o uso novamente mais tarde. getLocales é apenas uma função utilitária com algum 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>
	);
}

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

Com o provedor de contexto agora pronto para uso, crie um arquivo chamado /app/[locale]/layout.tsx, o layout raiz em nossa aplicação. Note que esse caminho possui 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 está garantindo que todos os códigos de localidade que você ativou para o seu projeto sejam pré-renderizados.

Agora, vamos construir 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 informa ao Next.js para reconstruir a página após 60 segundos e manter suas traduções atualizadas.

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

TacoTranslate suporta renderização no lado do servidor. Isso melhora muito a experiência do usuário, mostrando o conteúdo traduzido imediatamente, em vez de um breve flash de conteúdo não traduzido primeiro. Além disso, podemos pular as requisições de rede no cliente, porque já temos as traduções que precisamos 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 se adequar à sua configuração. Se true, o TacoTranslate exibirá a chave de API pública. Se estivermos em um ambiente local, de teste ou de preparo (isProduction is false), usaremos a chave de API do read/write secreto para garantir que novas cadeias de caracteres sejam enviadas para tradução.

Para garantir que o roteamento e o redirecionamento funcionem conforme o esperado, precisaremos criar um arquivo chamado /middleware.ts. Usando Middleware, podemos redirecionar os usuários para páginas apresentadas em seu idioma preferido.

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 cliente, você pode alterar o cookie locale para mudar qual é o idioma preferido do usuário. Por favor, veja o código completo de exemplo para ideias de como fazer isso!

Passo 5: Faça o deploy e teste!

Terminamos! Sua aplicação React agora será traduzida automaticamente quando você adicionar qualquer string a um componente Translate. Observe que somente ambientes com permissões read/write na chave da 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 API desse tipo, adicionando novas strings antes de entrar no ar. Isso evitará que alguém roube sua chave secreta da API e potencialmente infle seu projeto de tradução adicionando strings novas e não relacionadas.

Não deixe de ver o exemplo completo em nosso perfil no GitHub. Lá, você também encontrará um exemplo de como fazer isso usando o Pages Router ! Se você encontrar algum problema, fique à vontade para entrar em contato, e teremos muito prazer em ajudar.

O TacoTranslate permite que você localize automaticamente suas aplicações React rapidamente para qualquer idioma e vice-versa. Comece hoje mesmo!