A melhor solução para internacionalização (i18n) em aplicativos Next.js

Como funciona

À medida que o mundo se torna mais globalizado, torna-se cada vez mais importante que desenvolvedores web criem aplicações que atendam usuários de diferentes países e culturas. Uma das principais formas de conseguir isso é por meio da internacionalização (i18n), que permite adaptar sua aplicação a diferentes idiomas, 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 é para aplicações Next.js que usam o Pages Router.
Se você estiver usando o App Router, consulte este guia em vez disso.

Passo 1: Instale uma biblioteca de i18n

Para implementar a internacionalização em sua aplicação Next.js, primeiro escolheremos uma biblioteca i18n. Existem várias bibliotecas populares, incluindo next-intl. No entanto, neste exemplo, usaremos TacoTranslate.

TacoTranslate traduz automaticamente suas strings para qualquer idioma usando IA de ponta e libera você da tediosa gestão de arquivos JSON.

Vamos instalá-lo usando npm no seu terminal:

npm install tacotranslate

Passo 2: Crie uma conta gratuita no TacoTranslate

Agora que você instalou o módulo, é hora de criar sua conta TacoTranslate, um projeto de tradução e as chaves de API associadas. Crie uma conta aqui. É gratuito e não exige que você adicione um cartão de crédito.

Na interface do aplicativo TacoTranslate, crie um projeto e navegue até a aba de chaves de API. Crie uma chave read e uma read/write . Vamos salvá‑las como variáveis de ambiente. A read key é o que chamamos de public e a read/write key é secret. Por exemplo, você poderia adicioná‑las a um arquivo .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 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 de localidade padrão de fallback. Neste exemplo, vamos defini-lo como en para Inglês.
• TACOTRANSLATE_ORIGIN: A "pasta" onde 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

Etapa 3: Configurando o TacoTranslate

Para integrar o TacoTranslate à sua aplicação, você precisará criar um cliente usando as chaves de API mencionadas acima. 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;

Em breve, definiremos automaticamente TACOTRANSLATE_API_KEY.

Criar o cliente em um arquivo separado facilita reutilizá‑lo mais tarde. Agora, usando um /pages/_app.tsx personalizado, 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 você já possui pageProps e _app.tsx personalizados, por favor, estenda a definição com as propriedades e o código acima.

Etapa 4: Implementando a renderização do lado do servidor

TacoTranslate permite a renderização do lado do servidor das suas traduções. Isso melhora muito a experiência do usuário ao exibir o conteúdo traduzido imediatamente, em vez de um breve piscar de conteúdo não traduzido primeiro. Além disso, podemos evitar solicitações de rede no cliente, pois já temos todas as traduções de que precisamos.

Começaremos criando ou modificando /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 adequá-la à sua configuração. Se true, o TacoTranslate exibirá a chave pública da API. Se estivermos em um ambiente local, de teste ou de homologação (isProduction is false), usaremos a chave secreta da API read/write para garantir que novas strings sejam enviadas para tradução.

Até agora, configuramos a aplicação Next.js apenas com uma lista de idiomas suportados. O próximo passo é buscar as traduções de todas as suas páginas. Para isso, você usará ou getTacoTranslateStaticProps ou getTacoTranslateServerSideProps de acordo com suas necessidades.

Essas funções recebem três argumentos: um objeto Next.js Static Props Context, a configuração do TacoTranslate e propriedades opcionais do Next.js. Observe que revalidate em getTacoTranslateStaticProps está definido como 60 por padrão, para que suas traduções permaneçam atualizadas.

Para usar qualquer uma das funções em uma página, vamos supor que você tenha um arquivo 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 você deve ser capaz de usar o Translate componente 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!

Terminamos! Sua aplicação Next.js agora será traduzida automaticamente quando você adicionar quaisquer strings a um componente Translate. Observe que somente ambientes com permissões read/write na chave de API poderão criar novas strings para serem traduzidas. Recomendamos ter um ambiente de pré-produção fechado e seguro onde você possa testar sua aplicação de produção com uma chave de API como essa, adicionando novas strings antes de ir ao ar. Isso evitará que qualquer pessoa qualquer pessoa roube sua chave de API secreta e, potencialmente, inflar seu projeto de tradução ao adicionar novas strings 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!