Como implementar internacionalização em uma aplicação Next.js que está usando o Pages Router
Torne sua aplicação React mais acessível e alcance novos mercados com internacionalização (i18n).
À medida que o mundo se torna mais globalizado, é cada vez mais importante para os desenvolvedores web criar aplicações que possam atender usuários de diferentes países e culturas. Uma das principais formas de conseguir isso é através da internacionalização (i18n), que permite adaptar sua aplicação para diferentes idiomas, moedas e formatos de data.
Neste tutorial, exploraremos 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 usando o Pages Router.
Se você está usando o App Router, por favor veja este guia.
Passo 1: Instale uma biblioteca i18n
Para implementar 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.
O TacoTranslate traduz automaticamente suas strings para qualquer idioma usando IA de ponta, e o libera da gestão tediosa 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 API associadas. Crie uma conta aqui. É gratuito e não exige que você adicione um cartão de crédito.
Dentro da interface do aplicativo TacoTranslate, crie um projeto e navegue até a aba de chaves API. Crie uma chave read
, e uma chave read/write
. Nós as salvaremos como variáveis de ambiente. A chave read
é o que chamamos de public
e a chave read/write
é secret
. Por exemplo, você pode 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 vazar a chave API secreta 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 do locale padrão de fallback. Neste exemplo, vamos configurá-lo paraen
para inglês.TACOTRANSLATE_ORIGIN
: A “pasta” onde 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: Configurando o TacoTranslate
Para integrar o TacoTranslate com sua aplicação, você precisará criar um cliente usando as chaves de API mencionadas anteriormente. 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;
Definiremos automaticamente a TACOTRANSLATE_API_KEY
em breve.
Criar o cliente em um arquivo separado facilita o uso novamente mais tarde. Agora, usando um /pages/_app.tsx
personalizado, adicionaremos 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
personalizados e _app.tsx
, por favor estenda a definição com as propriedades e o código acima.
Passo 4: Implementando a renderização no 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 mostrar o conteúdo traduzido imediatamente, em vez de um flash de conteúdo não traduzido primeiro. Além disso, podemos pular as requisições de rede no cliente, porque já temos todas as traduções de que precisamos.
Vamos começar 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 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 de API do read/write
secreto para garantir que novas cadeias de caracteres sejam enviadas para tradução.
Até agora, configuramos a aplicação Next.js apenas com uma lista de idiomas suportados. A próxima coisa que faremos é buscar as traduções para todas as suas páginas. Para isso, você usará ou getTacoTranslateStaticProps
ou getTacoTranslateServerSideProps
com base nas suas necessidades.
Essas 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 o revalidate
em getTacoTranslateStaticProps
está definido para 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 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: Faça o deploy e teste!
Terminamos! Sua aplicação React agora será traduzida automaticamente quando você adicionar qualquer string 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 você possa testar sua aplicação de produção com uma chave de API desse tipo, adicionando novas strings antes de entrar no ar. Isso evitará que qualquer pessoa roube sua chave secreta da API e potencialmente infle seu projeto de tradução adicionando novas strings não relacionadas.
Não deixe de ver o exemplo completo em nosso perfil do GitHub. Lá, você também encontrará um exemplo de como fazer isso usando o App Router ! Se encontrar algum problema, sinta-se à vontade para entrar em contato, e teremos o maior prazer em ajudar.
TacoTranslate permite que você localize automaticamente suas aplicações React de forma rápida para qualquer idioma e vice-versa. Comece hoje mesmo!