Como implementar a internacionalização numa aplicação Next.js que utiliza o App Router

À medida que o mundo se torna mais globalizado, é cada vez mais importante que os desenvolvedores web criem aplicações que possam atender utilizadores de diferentes países e culturas. Uma das principais formas de alcançar isso é através da internacionalização (i18n), que permite adaptar a sua aplicação a diferentes idiomas, moedas e formatos de data.

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

Este guia é para aplicações Next.js que usam o App Router.
Se estiver a usar o Pages Router, veja este guia em vez disso.

Passo 1: Instale uma biblioteca i18n

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

O TacoTranslate traduz automaticamente as suas strings para qualquer idioma usando IA de ponta e liberta-o da gestão tediosa de ficheiros JSON.

Vamos instalá-lo usando npm no seu terminal:

npm install tacotranslate

Passo 2: Crie uma conta gratuita no TacoTranslate

Agora que instalou o módulo, é hora de criar a sua conta TacoTranslate, um projeto de tradução e as chaves API associadas. Crie uma conta aqui. É gratuito e não requer que adicione um cartão de crédito.

Dentro da interface da aplicação TacoTranslate, crie um projeto e navegue até ao separador das API keys. Crie uma chave read e outra read/write. Vamos guardá-las como variáveis de ambiente. A chave read é o que chamamos de public e a chave read/write é secret. Por exemplo, pode adicioná-las a um ficheiro .env na raiz do seu projeto.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Certifique-se de nunca expor a chave secreta read/write da API 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 do idioma predefinido de reserva. Neste exemplo, vamos defini-lo como en para Inglês.
• TACOTRANSLATE_ORIGIN: A “pasta” onde as suas strings serão armazenadas, como o URL do seu website. Leia mais sobre origens aqui.

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

Passo 3: Configurar 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;

Iremos definir automaticamente TACOTRANSLATE_API_KEY e TACOTRANSLATE_PROJECT_LOCALE em breve.

Criar o cliente num ficheiro separado torna fácil reutilizá-lo mais tarde. getLocales é apenas uma função utilitária com algum tratamento de erros incorporado. Agora, crie um ficheiro chamado /app/[locale]/tacotranslate.tsx, onde iremos implementar o provider 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 'use client'; indicando que este é um componente client.

Com o provider de contexto agora pronto, crie um ficheiro chamado /app/[locale]/layout.tsx, o layout raiz da nossa aplicação. Note que este caminho tem 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 a usar o nosso parâmetro de Dynamic Route [locale] para obter traduções para essa língua. Além disso, generateStaticParams está a garantir que todos os códigos de idioma que ativou para o seu projeto são pré-renderizados.

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

Note a variável revalidate que indica ao Next.js para reconstruir a página após 60 segundos, mantendo as suas traduções atualizadas.

Passo 4: Implementar renderização do lado servidor

O TacoTranslate suporta renderização no lado do servidor. Isto melhora bastante a experiência do utilizador ao mostrar o conteúdo traduzido imediatamente, em vez de primeiro um flash de conteúdo não traduzido. Adicionalmente, podemos evitar pedidos de rede no cliente, porque já temos as traduções necessárias para a página que o utilizador está a visualizar.

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 de 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 secreta read/write API para garantir que novas cadeias de caracteres sejam enviadas para tradução.

Para garantir que o encaminhamento e o redirecionamento funcionem conforme esperado, precisaremos criar um ficheiro chamado /middleware.ts. Usando Middleware, podemos redirecionar os utilizadores para páginas apresentadas na sua língua preferida.

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, pode alterar o cookie locale para mudar qual é a língua preferida do utilizador. Por favor, veja o código de exemplo completo para ideias sobre como fazer isto!

Passo 5: Fazer deploy e testar!

Terminámos! A sua aplicação React será agora traduzida automaticamente quando adicionar qualquer texto a um componente Translate. Note que apenas os ambientes com permissões read/write na chave API poderão criar novos textos para serem traduzidos. Recomendamos ter um ambiente de staging fechado e seguro onde possa testar a sua aplicação de produção com uma chave API deste tipo, adicionando novos textos antes de ir para produção. Isto evitará que alguém roube a sua chave API secreta e potencialmente sobrecarregue o seu projeto de tradução ao adicionar novos textos não relacionados.

Não deixe de consultar o exemplo completo no nosso perfil do GitHub. Lá, também encontrará um exemplo de como fazer isto usando o Pages Router ! Se encontrar algum problema, não hesite em contactar-nos, teremos todo o gosto em ajudar.

O TacoTranslate permite-lhe localizar automaticamente as suas aplicações React rápida e facilmente para qualquer idioma e a partir de qualquer idioma. Comece hoje mesmo!