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

À medida que o mundo se torna mais globalizado, torna-se cada vez mais importante que os desenvolvedores web criem aplicações capazes de satisfazer utilizadores de diferentes países e culturas. Uma das principais formas de conseguir isto é através da internacionalização (i18n), que lhe 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 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, consulte 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, porém, 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 na TacoTranslate

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

Na interface da aplicação TacoTranslate, crie um projeto e navegue até ao separador de chaves API. Crie uma chave read e uma chave read/write. Vamos guardá‑las como variáveis de ambiente. A chave read é aquilo que chamamos 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 de API secreta read/write em ambientes de produção do 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 locale predefinido a usar como fallback. 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 site. Leia mais sobre origens aqui.

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

Passo 3: Configurar o TacoTranslate

Para integrar o TacoTranslate na sua aplicação, precisará de criar um cliente usando as chaves da API indicadas 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 mais tarde. getLocales é apenas uma função utilitária com algum tratamento de erros integrado. 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>
	);
}

Repare na 'use client'; que indica que este é um componente cliente.

Com o provedor de contexto agora pronto, crie um ficheiro chamado /app/[locale]/layout.tsx, o layout raiz na 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 as traduções desse idioma. Além disso, generateStaticParams garante que todos os códigos de localidade que ativou no 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!" />
	);
}

Repare na 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: Implementação da renderização no lado do servidor

TacoTranslate suporta renderização no lado do servidor. Isto melhora significativamente a experiência do utilizador ao apresentar imediatamente o conteúdo traduzido, em vez de primeiro mostrar um breve lampejo de 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};
};

Ajuste a verificação isProduction conforme a sua configuração. Se true, o TacoTranslate irá expor a chave API pública. Se estivermos num ambiente local, de teste ou de staging (isProduction is false), usaremos a chave API secreta read/write para garantir que novas strings sejam enviadas para tradução.

Para garantir que o roteamento e o redireccionamento funcionem como esperado, teremos de criar um ficheiro chamado /middleware.ts. Usando Middleware, podemos redireccionar 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 lado do cliente, pode alterar o cookie locale para definir a língua preferida do utilizador. Veja o código de exemplo completo para ideias sobre como o fazer!

Passo 5: Implantar e testar!

Terminámos! A sua aplicação React será agora traduzida automaticamente quando adicionar quaisquer cadeias de texto a um componente Translate. Tenha em atenção que apenas ambientes com permissões read/write na chave da API poderão criar novas cadeias a serem traduzidas. Recomendamos ter um ambiente de pré-produção fechado e seguro onde possa testar a sua aplicação de produção com uma chave de API desse tipo, adicionando novas cadeias antes de entrar em produção. Isto impedirá que qualquer pessoa qualquer pessoa roube a sua chave de API secreta e, potencialmente, sobrecarregue o seu projeto de tradução ao adicionar novas cadeias 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!