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 para os desenvolvedores web criar aplicações que possam atender a utilizadores de diferentes países e culturas. Uma das formas chave de conseguir 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 server side rendering. TL;DR: Veja o exemplo completo aqui.

Este guia é para aplicações Next.js que utilizam o App Router.
Se estiver a usar o Pages Router, veja antes este guia.

Passo 1: Instalar uma biblioteca i18n

Para implementar a internacionalização na sua aplicação Next.js, primeiro escolheremos 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 utilizando 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 já instalou o módulo, é altura de criar a sua conta TacoTranslate, um projeto de tradução e as respetivas chaves API. Crie uma conta aqui. É grátis, e não é necessário adicionar um cartão de crédito.

Dentro da interface da aplicação TacoTranslate, crie um projeto e navegue até ao separador das chaves API. Crie uma chave read, e uma chave 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 divulgar a chave secreta da API read/write em ambientes de produção no lado do cliente.

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

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

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

Passo 3: Configurar o TacoTranslate

Para integrar o TacoTranslate com a sua aplicação, precisará de criar um cliente utilizando as chaves API mencionadas anteriormente. Por exemplo, crie um ficheiro 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;

Vamos definir automaticamente TACOTRANSLATE_API_KEY e TACOTRANSLATE_PROJECT_LOCALE em breve.

Criar o cliente num ficheiro separado facilita a sua reutilização posteriormente. 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 fornecedor 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'; que indica que este é um componente cliente.

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 utilizar o nosso parâmetro Dynamic Route [locale] para buscar traduções para essa língua. Adicionalmente, generateStaticParams está a garantir que todos os códigos de localização que ativou para o seu projeto sejam pré-renderizados.

Agora, vamos construir 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: Implementação da renderização no lado do servidor

O TacoTranslate suporta renderização do lado do servidor. Isto melhora significativamente a experiência do utilizador ao mostrar o conteúdo traduzido imediatamente, em vez de um breve instante com conteúdo não traduzido. Além disso, 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, precisarás 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: Faça o deploy e teste!

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

Certifique-se 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, e teremos todo o prazer em ajudar.

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