Como implementar 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 criarem aplicações que possam satisfazer utilizadores de diferentes países e culturas. Uma das formas principais de alcançar isto é através da internacionalização (i18n), que permite adaptar a sua aplicação a diferentes idiomas, moedas e formatos de data.

Neste artigo, iremos 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 utilizam o App Router.
Se estiver a usar o Pages Router, veja este guia em vez disso.

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 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, é altura de criar a sua conta TacoTranslate, um projeto de tradução e as respetivas chaves API. Crie uma conta aqui. É gratuito e não exige que insira um cartão de crédito.

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

Também iremos adicionar 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, será necessário criar um cliente utilizando as chaves API mencionadas anteriormente. Por exemplo, crie um ficheiro denominado /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 a 'use client'; indicando que este é um componente cliente.

Com o context provider 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 Dynamic Route [locale] para obter traduções para essa língua. Adicionalmente, generateStaticParams está a garantir que todos os códigos de localidade que ativou para o seu projeto são 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 e manter as suas traduções atualizadas.

Passo 4: Implementar a renderização do lado do servidor

TacoTranslate suporta renderização do lado do servidor. Isto melhora significativamente a experiência do utilizador ao mostrar conteúdo traduzido imediatamente, em vez de primeiro apresentar um breve flash de conteúdo não traduzido. Além disso, podemos evitar pedidos de rede no cliente, porque já dispomos das 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. Veja, por favor, o código completo do exemplo para obter ideias sobre como fazer isto!

Passo 5: Fazer deploy e testar!

Terminámos! A sua aplicação React será agora traduzida automaticamente quando adicionar quaisquer strings a um componente Translate. Note que apenas ambientes com permissões read/write na chave API poderão criar novas strings para serem traduzidas. 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 para produção. Isto evitará que alguém roube a sua chave API secreta e, potencialmente, sobrecarregue o seu projeto de tradução com novas strings irrelevantes.

Não se esqueça 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 que localize automaticamente as suas aplicações React rápida e facilmente para qualquer idioma e a partir de qualquer idioma. Comece hoje!