A melhor solução para internacionalização (i18n) em aplicações Next.js

Como funciona

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

Neste tutorial, iremos 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 estão a usar o Pages Router.
Se está a usar o App Router, consulte antes este guia.

Passo 1: Instalar uma biblioteca i18n

Para implementar a internacionalização na sua aplicação Next.js, primeiro vamos escolher uma biblioteca i18n. Existem várias bibliotecas populares, incluindo next-intl. Contudo, neste exemplo, 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 já tem o módulo instalado, é 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 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 suas chaves 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 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 API secreta 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 língua predefinida para 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 origins aqui.

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

Passo 3: Configurar o TacoTranslate

Para integrar o TacoTranslate ao seu aplicativo, você precisará criar um cliente usando as chaves de API anteriores. Por exemplo, crie um arquivo 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 a 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 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á tiver pageProps personalizados e _app.tsx, por favor estenda a definição com as propriedades e o código indicados acima.

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

O TacoTranslate permite a renderização do lado do servidor das suas traduções. Isto melhora muito a experiência do utilizador ao mostrar o conteúdo traduzido imediatamente, em vez de primeiro um flash de conteúdo por traduzir. Adicionalmente, podemos evitar pedidos de rede no cliente, porque já temos todas as traduções de que precisamos.

Começaremos por criar ou modificar o ficheiro /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 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.

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

Estas funções recebem três argumentos: um objeto Next.js Static Props Context, a configuração para o TacoTranslate, e propriedades opcionais do Next.js. Note que revalidate em getTacoTranslateStaticProps está definido para 60 por padrã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 deve 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!

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

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

O TacoTranslate permite-lhe localizar automaticamente as suas aplicações React rápida e eficazmente para qualquer língua e a partir dela. Comece hoje mesmo!