Internacionalizando uma aplicação front end

English version

Fazer com que nosso produto atinja uma audiência além de nossos limites geográficos, e que esteja de acordo com culturas locais requer um processo conhecido como internacionalização, muitas vezes referenciado como i18n, uma forma de abreviar o termo “i + nternationalizatio + n”, ou “i (mais 18 letras, mais)n”.

Caso queira saber mais sobre o que é internacionalização, sugiro uma rápida leitura sobre o assunto antes de continuarmos.

No front end existem bibliotecas próprias para diferentes stacks como React, Angular, Vue, etc. Vou focar aqui em React mas os conceitos fundamentais podem ser aplicados a qualquer outra stack.

O que você vai encontrar neste artigo?

Resumidamente vamos completar os seguintes passos:

1. Criar uma aplicação simples com Create React App;
2. Instalar uma biblioteca de internacionalização;
3. Escrever arquivos de tradução;
4. Configurar nossa biblioteca de tradução para as nossas necessidades;
5. Configurar um React Provider para os componentes a serem internacionalizados;
6. Substituir textos hard coded por chaves de tradução;

Você também pode visualizar a aplicação rodando no heroku.

Visite também o repositório da aplicação no Github.

Começando

Passo 1. Criando uma aplicação com Create React App

Nosso primeiro passo será criar uma aplicação muito simples em React para que possamos aplicar os conceitos de internacionalização. Para isso vamos utilizar o Create React App para abstrair todo o processo de criação do App.

$ npx create-react-app react-i18next-example
$ cd react-i18next-example
$ npm start

Com o ambiente já configurado posso começar a desenvolver a aplicação. Esta etapa será omitida, pois não é o foco deste artigo. A aplicação já preparada, porém sem estar internacionalizada ainda, pode ser encontrada no repositório da aplicação na branch without-i18n.

Trata-se de uma SPA (Single Page App) turística sobre faróis.

Estrutura básica da aplicação

Vamos precisar internacionalizar os textos dentro de cada componente no diretório lighthouses, assim como no diretório Home.

Internacionalizando

Temos várias opções de bibliotecas de internacionalização (ou i18n) para aplicações em React. Dentre as mais populares estão a react-intl do yahoo e a i18next. Após uma rápida análise, esta última me pareceu mais simples de implementar, além de servir não apenas para React como também para vários outros frameworks e libraries como Angular, Vue, assim como JavaScript nativo e NodeJS. Algumas das várias features que a i18next oferece são: carregamento de traduções sob demanda via Ajax, cacheamento, plurals, namespacing e detecção de linguagem do browser.

Afim de facilitar nosso trabalho, vamos utilizar também uma extensão da library i18next, para React que é a react-i18next.

Passo 2: Instalando a i18next e a react-i18next

Em um terminal entre os comandos abaixo:

$ npm install i18next
$ npm install react-i18next

Também vamos instalar a extensão que detecta a linguagem padrão do browser (opcional).

$ npm install i18next-browser-languagedetector

Passo 3: Criando os arquivos de tradução

Agora que instalamos a nossa library de i18n vamos criar nossos arquivos de tradução. Vamos traduzir apenas para as linguagens “pt-BR” e “en” (português do Brasil e inglês).

Dentro de cada componente que contenha textos vamos criar uma pasta locales, onde colocaremos nossos arquivos json com as chaves de tradução. Começando pelo diretório src/components/home/.

Para as chaves em português vamos criar o arquivo default.json e para as chaves em inglês o arquivo default.en.json.

Componente Home com a pasta locales [ src/components/home/ ]

react-i18next-example/src/components/Home/locales/default.json

react-i18next-example/src/components/Home/locales/default.en.json

Faremos o mesmo para os diretórios abaixo: (esta etapa será omitida)

• src/components/lighthouses/Augustine/
• src/components/lighthouses/Hercules/
• src/components/lighthouses/Lindau/
• src/components/lighthouses/Peggys/

Passo 4: Criando o arquivo de configuração de i18n

Além dos arquivos de tradução, vamos precisar também de um arquivo de configuração de i18n que vai servir para gerenciar as features que queremos utilizar. Para isso criaremos uma pasta i18n no diretório src/, e dentro um arquivo index.js.

react-i18next-example/src/i18n/index.js

Na linha 2 importamos o módulo i18next-browser-languagedetector.

Na linha 3 importamos os arquivos de tradução.

Na linha 12 temos uma chave comentada porque não está sendo usada. Mas caso não estivéssemos usando a feature de detecção de linguagem automática, esta chave definiria qual a linguagem padrão a ser carregada. Este caso de uso está rodando na branch simplest-example. Para testar, mude para esta branch e troque o valor da chave de “pt” para “en”, e vice-versa.

Na linha 40 adicionamos um callback que será chamado quando disparmos uma ação para a troca de linguagem. Este callback está sendo chamado na linha 14 do componente Toolbar.

Nosso arquivo de configuração aceita um leque de opções, em nossa aplicação porém, só vamos utilizar algumas, são elas: interpolation { defaultValue }, debug, resources, fallbackLng, ns, defaultNS, react { wait, bindI18n, bindStore, nsMode }

interpolation
interpolation é um dos recursos mais utilizados em internacionalização. Este recurso nos permite carregar valores dinâmicos em nossas chaves. No nosso caso usando React, o valor escapeValue não precisa ser definido como true.

Resources
Resources define os arquivos de tradução a serem carregados. Também é possível definir as chaves de tradução inline nesta opção.

fallbackLng
Linguagem a ser carregada caso não seja encontrada a linguagem padrão do usuário.

ns
Namespace padrão a ser carregado.

react
Esta opção é um objeto que aceita opções relativas ao React.

Passo 5: Adicionando um provider de i18n na App

Qualse lá! Vamos utilizar a facilidade que a extensão react-i18next nos oferece adicionando um provider que vai nos permitir passar as traduções via react props em qualquer lugar da aplicação. Faremos isso no topo da nossa árvore de componentes, no arquivo src/App.js/.

react-i18next-example/src/App.js

Note que importamos o módulo I18nextProvider na linha 3, e também nosso arquivo de configuração de i18n na linha 4, o qual será passado como prop no nosso componente provider na linha 11. Toda nossa aplicação está agora encapsulada pelo provider de internacionalização.

Passo 6: Substituindo textos hard coded por chaves de tradução

Por último, mas não menos importante, vamos substituir as strings por chaves de tradução em nossos componentes.

react-i18next-example/src/components/Home/index.jsx antes da internacionalização

react-i18next-example/src/components/Home/index.jsx depois da internacionalização

Como podemos perceber na linha 5, o addon react-i18next nos fornece uma função t via react props advinda do nosso provider definido no arquivo src/App.js/ . Chamamos essa função nos locais de texto passando como argumento o caminho da chave de tradução que queremos invocar nos arquivos json.

Também nos arquivos onde queremos internacionalizar, devemos importar o módulo translate (linha 2), e exportar o nosso arquivo encapsulando no módulo translate com o namespace padrão que definimos em nosso arquivo de configuração i18n, no nosso caso (common) (linha 17).

Agora é só rodar a aplicação:

$ npm start

Para testar, basta clicar nas bandeirinhas no cabeçalho da aplicação.

Conclusões

Recapitulando o que vimos

1. Criamos um App com o Create React App
2. Instalamos a library i18next e sua extensão para React react-i18next
3. Criamos os arquivos de tradução
4. Criamos o arquivo de configuração i18n
5. Adicionamos um React Provider no topo da nossa árvore de componentes
6. Substituímos os textos hard coded pelas chaves de tradução

Este é um exemplo totalmente funcional de internacionalização no front end. Utilizamos uma library muito completa, porém, aplicamos apenas alguns de seus muitos recursos. Poderíamos ter criado um único arquivo json com todas as chaves, mas propositalmente separamos em diferentes arquivos, já que este é um padrão muito utilizado na prática. Poderíamos ainda não ter nenhum arquivo de tradução, escrevendo nossas chaves diretamente no arquivo de configuração de i18n na opção resources. Para ver o live demo acesse a aplicação rodando.