Internacionalizando um projeto React com a biblioteca react-i18next

Introdução

Com a expansão dos produtos para o mercado internacional, surge a necessidade de que eles estejam disponíveis em vários idiomas e com a RD Station não foi diferente. Estamos trabalhando diariamente para que todos os nossos produtos sejam internacionalizados.

A internacionalização (i18n) é o processo de adaptar um software para diferentes idiomas, isso significa basicamente extrair todos os textos que foram adicionados diretamente no código para arquivos que vão facilitar o processo de tradução em múltiplos idiomas.

Para internacionalização de um projeto, contamos com ferramentas de i18n para cada linguagem de programação ou framework que utilizamos. Essas ferramentas facilitam a configuração, organização e permitem a geração de chaves de tradução para cada texto a ser exibido em sua aplicação.

Neste artigo falaremos um pouco sobre como internacionalizar um projeto construído em React utilizando a biblioteca react-i18next. Esta biblioteca utiliza MIT License e está disponível para React e React Native, além disso, por ser baseada no i18next, existem outras versões similares para diversas linguagens e frameworks.

Mãos na massa

Para demonstrar como podemos internacionalizar projetos React, vamos fazer setup inicial de um projeto simples, assim você pode acompanhar do início ao fim da jornada. Queremos que nosso projeto detecte automaticamente o idioma do navegador da pessoa e assuma como o idioma da aplicação. Também será possível trocar o idioma selecionando um botão específico.

Pré-requisitos

• node
• npm
• editor de código (ex. VSCode, Sublime Text)

Passo a passo

Você pode pular para o passo 3 caso já tenha um projeto React criado.

Passo 1. Criação do projeto base.

1. Abra o terminal na pasta onde irá criar o seu projeto.
2. Rode o comando npx create-react-app my-app (você pode substituir my-app pelo nome que quiser dar para seu projeto)
3. Acesse a pasta do projeto com cd my-app
4. Abra o projeto no seu editor de código preferido, caso esteja utilizando o VSCode basta usar code .

Passo 2. Com o projeto criado, vamos adicionar uma página simples com alguns textos que vamos internacionalizar.

1. Vamos aproveitar os arquivos App.js e App.css que já estão criados e apenas substituir os códigos que já estão nesses arquivos pelos códigos abaixo.

Ao rodar npm start dentro da pasta do projeto, você poderá ver a página que acabamos de criar na URL http://localhost:3000. Note que temos um título, subtítulo e dois botões para alterar o idioma.

Passo 3. Instalação e configuração da biblioteca react-i18next

Agora que temos um projeto, vamos demonstrar como instalar e fazer a configuração da biblioteca react-i18next.

Primeiro faremos a instalação da biblioteca e suas dependências utilizando os seguintes comandos no terminal (dentro da pasta do projeto):

npm install react-i18next i18next
npm install i18next-browser-languagedetector i18next-http-backend

Para entender melhor cada uma das dependências instaladas:

1. react-i18next — biblioteca de internacionalização
2. i18next — necessário pois o react-i18next é baseado em i18next e o tem como dependência
3. i18next-browser-languagedetector — biblioteca utilizada para detectar o idioma do navegador automaticamente
4. i18next-http-backend — biblioteca utilizada para carregar os arquivos de tradução usando http, também pode ser utilizada para carregar os arquivos de uma aplicação externa. Ela possui muitas opções de configuração e vai depender da necessidade de seu projeto. Em nosso projeto estamos utilizando apenas para carregar os arquivos de tradução usando http, que se faz necessário pois usamos a detecção automática da linguagem do navegador.

Com as dependências instaladas, agora vamos criar um arquivo de configuração.

1. Dentro da pasta src, crie um arquivo chamado i18n.js. Nesse arquivo vamos adicionar as configurações do i18next e vincular a configuração com as demais bibliotecas que instalamos, essa configuração depende muito do escopo e arquitetura que você tem em seu projeto, você pode precisar adaptar ela para o funcionamento da sua aplicação, para por exemplo, ler de diferentes diretórios e idiomas diferentes, você pode ver as configurações suportadas na documentação e adaptar conforme necessidade. A configuração abaixo centraliza as traduções por linguagem e também detecta o idioma do navegador do usuário.

1. Agora você precisará ir no arquivo src/index.js e adicionar a importação do arquivo que acabamos de criar.

import './i18n';

Configuração feita! Agora é só adicionar as chaves de tradução e testar.

Passo 4. Gerando chaves de tradução

Com a aplicação configurada, vamos adicionar nossas primeiras chaves de tradução e ver como a aplicação se comporta. A configuração que fizemos lê as chaves de tradução do caminho public/locales, portanto, você precisará criar uma pasta chamada locales e as pastas de cada linguagem que sua aplicação irá suportar, exemplo pt-BR. Dentro da pasta de cada linguagem teremos um arquivo translation.json, vale ressaltar que esse nome translation é um nome padrão que a biblioteca reconhece. Veja na imagem abaixo como ficou.

Agora, para cada arquivo translation.json, vamos adicionar as chaves referentes aos textos que vamos traduzir. Note que temos uma estrutura de chave/valor, onde a chave será usada para ser referenciada no código, essa estrutura é especificada pela própria documentação oficial da biblioteca. Todos os arquivos de tradução devem ter as mesmas chaves, porém o valor será referente ao idioma que o arquivo está traduzindo.

Com as chaves criadas, agora basta adicioná-las no código.

1. Para usar a biblioteca dentro de nossos arquivos, vamos precisar adicionar a importação dela e como vamos utilizar o hook useTranslation, ele será importado diretamente, este hook pode ser utilizado dentro de componentes funcionais para acessar a função de tradução te a instância do i18n, caso nossa página fosse class-based, precisaríamos utilizar o withTranslation pra acessar as mesmas funções que mencionamos. No nosso caso, vamos adicionar a importação no arquivo App.js, que é onde estão os textos exibidos na aplicação.

import { useTranslation } from 'react-i18next';

1. Em seguida, vamos criar uma constante para utilizar a função t do hook useTranslation, que nos dará acesso aos valores das chaves de tradução e também vamos utilizar o i18n para chamar na função changeLanguage para mudar o idioma da página de acordo com o botão selecionado pelo usuário. Exemplo:

2. Para utilizar as chaves de tradução no código, basta chamar a função te passar o caminho para a chave que criamos no arquivo translation.json. Exemplo: Para utilizar a chave title faríamos t('app.title') no lugar do texto existente no código.

O arquivo final ficará assim:

Ao rodar a aplicação final (npm start), podemos observar que o idioma da página é inicialmente detectado de acordo com o do navegador e podemos mudar ele ao clicar nos botões de seleção.

Este foi um exemplo simples de utilização da biblioteca e espero que tenha sido proveitoso.

Se você gostou e deseja mais desafios, que tal dar uma olhada nas nossas vagas disponíveis?