Como implementar a internacionalização numa aplicação Next.js que está a usar o Pages Router

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

Neste tutorial, 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 destina-se a aplicações Next.js que utilizam o Pages Router.
Se estiver a utilizar o App 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 de i18n. Existem várias bibliotecas populares, incluindo next-intl. No entanto, neste exemplo, iremos usar TacoTranslate.

O TacoTranslate traduz automaticamente as suas cadeias de texto para qualquer língua 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 de API associadas. Crie uma conta aqui. É gratuito e não é necessário adicionar um cartão de crédito.

Na interface da aplicação TacoTranslate, crie um projeto e navegue até à aba de chaves da API. Crie uma chave read e uma chave read/write. Vamos guardá-las como variáveis de ambiente. A chave read é aquilo a 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 vamos adicionar mais duas variáveis de ambiente: TACOTRANSLATE_DEFAULT_LOCALE e TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: O código de locale de fallback predefinido. Neste exemplo, iremos 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, terá de criar um cliente usando as chaves de 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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

Vamos definir automaticamente TACOTRANSLATE_API_KEY em breve.

Criar o cliente num ficheiro separado torna mais fácil reutilizá‑lo mais tarde. Agora, usando um /pages/_app.tsx personalizado, vamos adicionar o provider do TacoTranslate.

import React from 'react';
import {type AppProps} from 'next/app';
import {type Origin, type Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import TacoTranslateHead from 'tacotranslate/next/head';
import tacoTranslate from '../tacotranslate-client';

type PageProperties = {
	origin: Origin;
	locale: Locale;
	locales: Locale[];
	localizations: Localizations;
};

export default function App({Component, pageProps}: AppProps<PageProperties>) {
	const {origin, locale, locales, localizations} = pageProps;

	return (
		<TacoTranslate
			client={tacoTranslate}
			origin={origin}
			locale={locale}
			localizations={localizations}
		>
			<TacoTranslateHead rootUrl="https://your-website.com" locales={locales} />
			<Component {...pageProps} />
		</TacoTranslate>
	);
}

Se já tiveres pageProps e _app.tsx personalizados, por favor estenda a definição com as propriedades e o código acima.

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

TacoTranslate permite a renderização do lado do servidor das suas traduções. Isto melhora bastante a experiência do utilizador ao apresentar o conteúdo traduzido imediatamente, em vez de primeiro um breve flash de conteúdo não traduzido. Além disso, podemos evitar pedidos de rede no cliente, porque já temos todas as traduções de que precisamos.

Começaremos por criar ou modificar /next.config.js.

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = {};

	return withTacoTranslate(config, {
		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'),
	});
};

Modifique a verificação isProduction para se adequar à sua configuração. Se true, o TacoTranslate irá expor a chave pública da API. Se estivermos num ambiente local, de teste ou de staging (isProduction is false), usaremos a chave secreta de API read/write para garantir que novas cadeias de texto são enviadas para tradução.

Até agora, apenas configurámos a aplicação Next.js com uma lista de idiomas suportados. O próximo passo é obter as traduções de todas as suas páginas. Para isso, deverá usar ou getTacoTranslateStaticProps ou getTacoTranslateServerSideProps consoante os seus requisitos.

Estas funções recebem três argumentos: um objeto Next.js Static Props Context, uma configuração para o TacoTranslate, e propriedades opcionais do Next.js. Note que revalidate em getTacoTranslateStaticProps está definido para 60 por omissão, para que as suas traduções se mantenham atualizadas.

Para usar qualquer uma das funções numa página, vamos supor que tem um ficheiro de página como /pages/hello-world.tsx.

import {Translate} from 'tacotranslate/react';
import getTacoTranslateStaticProps from 'tacotranslate/next/get-static-props';
import tacoTranslateClient from '../tacotranslate-client';

export async function getStaticProps(context) {
	return getTacoTranslateStaticProps(context, {client: tacoTranslateClient});
}

export default function Page() {
	return <Translate string="Hello, world!"/>;
}

Agora deverá conseguir usar o componente Translate para traduzir strings em todos os seus componentes React.

import {Translate} from 'tacotranslate/react';

function Component() {
	return <Translate string="Hello, world!"/>
}

Passo 5: Implantar e testar!

Já está! 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 da 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 da API desse tipo, adicionando novas strings antes de entrar em produção. Isto impedirá qualquer pessoa qualquer pessoa de roubar a sua chave API secreta, e potencialmente inflar o seu projeto de tradução ao adicionar novas strings não relacionadas.

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 App Router! Se encontrar algum problema, não hesite em entrar em contacto, e teremos todo o gosto em ajudar.

O TacoTranslate permite localizar automaticamente as suas aplicações React, de forma rápida, para e a partir de mais de 75 idiomas. Comece hoje!