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 que os desenvolvedores web criem aplicações capazes de servir utilizadores de diferentes países e culturas. Uma das formas principais de conseguir isso é 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 no 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 vamos escolher uma biblioteca i18n. Existem várias bibliotecas populares, incluindo next-intl. No entanto, neste exemplo, vamos usar TacoTranslate.

TacoTranslate traduz automaticamente as suas strings 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 tem o módulo instalado, é altura de criar a sua conta TacoTranslate, um projeto de tradução e as chaves API associadas. Crie uma conta aqui. É gratuito e não exige que adicione um cartão de crédito.

Na interface da aplicação TacoTranslate, crie um projeto e navegue até ao separador de chaves da API. Crie uma chave read e uma chave read/write. Iremos guardá-las como variáveis de ambiente. A chave read é aquilo 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 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 da localidade predefinida (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 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 facilita a sua reutilização mais tarde. Agora, usando um /pages/_app.tsx, vamos adicionar o provedor 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 e _app.tsx, por favor, estenda a definição com as propriedades e o código acima.

Passo 4: Implementação da renderização do lado do servidor

TacoTranslate permite a renderização do lado do servidor das suas traduções. Isto melhora significativamente a experiência do utilizador ao mostrar o conteúdo traduzido de imediato, em vez de, primeiro, apresentar um breve momento 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.

Vamos começar 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 de API pública. Se estivermos num ambiente local, de teste ou de staging (isProduction is false), usaremos a chave de API secreta read/write para garantir que novas strings sejam 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, irá usar ou getTacoTranslateStaticProps ou getTacoTranslateServerSideProps consoante as suas necessidades.

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

Deverá agora conseguir utilizar o Translate para traduzir cadeias de texto 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. 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 alguém roube a sua chave secreta da API e, potencialmente, sobrecarregue o seu projeto de traduções 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 App 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!