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

À medida que o mundo se torna mais globalizado, é cada vez mais importante que os developers web construam aplicações que consigam atender utilizadores de diferentes países e culturas. Uma das formas chave para alcançar isto é através da internacionalização (i18n), que permite adaptar a 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 estão a usar o Pages Router.
Se estiver a usar o App Router, por favor veja este guia em vez disso.

Passo 1: Instalar uma biblioteca i18n

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

O TacoTranslate traduz automaticamente as suas strings para qualquer idioma utilizando IA de ponta, e liberta-o da gestão morosa dos ficheiros JSON.

Vamos instalá-lo usando npm no seu terminal:

npm install tacotranslate

Passo 2: Crie uma conta gratuita no TacoTranslate

Agora que já instalou o módulo, é hora de criar a sua conta TacoTranslate, um projeto de tradução e as respetivas chaves API. Crie uma conta aqui. É gratuito e não é necessário adicionar 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 é o 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 para ambientes de produção do 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 reserva. Neste exemplo, vamos defini-lo como en para Inglês.
• TACOTRANSLATE_ORIGIN: A “pasta” onde as suas strings serão armazenadas, como o URL do seu website. Leia mais sobre origins aqui.

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

Passo 3: Configurar o TacoTranslate

To integrate TacoTranslate with your application, you’ll need to create a client using the API keys from earlier. For example, create a file named /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 fornecedor 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 personalizados, por favor estenda a definição com as propriedades e o código acima.

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

O TacoTranslate permite a renderização do lado do servidor das suas traduções. Isso melhora muito a experiência do utilizador ao mostrar o conteúdo traduzido imediatamente, em vez de primeiro um breve flash de conteúdo por traduzir. Além disso, podemos evitar pedidos de rede no lado do 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 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, apenas definimos a aplicação Next.js com uma lista de idiomas suportados. A próxima coisa que faremos é buscar traduções para todas as suas páginas. Para fazer isso, você usará getTacoTranslateStaticProps ou getTacoTranslateServerSideProps com base em suas necessidades.

Essas funções usam três argumentos: Um objeto Next.js Static Props Context , configuração para TacoTranslate e propriedades Next.js opcionais. Observe que revalidate no getTacoTranslateStaticProps é definido como 60 por padrão, para que suas traduções permaneçam atualizadas.

Para usar qualquer função em uma página, vamos supor que você tenha um arquivo de paginação 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á 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: Desployar e testar!

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

Certifique-se 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 contactar-nos, e teremos todo o prazer em ajudar.

O TacoTranslate permite-lhe localizar automaticamente as suas aplicações React rapidamente para qualquer idioma e a partir de qualquer idioma. Comece hoje mesmo!