Como fazer traduções no Magento 2

Contextualizando

O que é i18n?

i18n é um acrônimo que origina-se do inglês "internationalization", onde 18 é o número de letras entre o primeiro "*i" e o último "n"*. I18n é a prática de desenvolvimento de software de forma a torná-lo capaz de ser adaptado para diferentes idiomas e localidades sem necessidade de alteração do código-fonte. Isso é feito através da separação das strings de texto presentes no código em arquivos de idioma separados, que podem ser facilmente alterados sem afetar o código em si.

Como o Magento 2 trabalha com traduções?

O Magento 2 permite que a localidade (idioma) seja alterada para a loja, e através da localidade selecionada o Magento busca e aplica as traduções através dos dicionarios na seguinte sequência:

1. Traduções através do banco de dados (traduções localizadas no banco de dados possuem preferência e substituem as traduções armazenadas em outros locais;
2. Traduções através do tema:
   1. Tema pai (app/design/{area}/{ParentTheme});
   2. Tema atual (app/design/{area}/{CurrentTheme});
3. Traduções através do pacote de linguagem (app/i18n);
4. Traduções através do módulo (app/code/{Vendor}/{Module}/i18n ou vendor/{vendor}/module-{module}/i18n).

Código para tradução

String em arquivos PHP

Para garantir que uma string seja adicionada ao dicionário e traduzida, deve ser utilizado o método __('{string content}') ao gerar uma string em um arquivo phtml ou PHP.

<?= __('{Custom string}') ?>
<?= __('{Custom string with %1}', $var) ?>

É recomendado, mas não obrigatório, que não coloque variáveis dentro das strings que irão nas funções __() ou Phrase(). O scanner que coleta as frases do código não pode interpretar e coletar o valor da variável quando está nesses locais. Em vez disso, você deve colocar o texto completo na função __() ou Phrase(). Se você precisar especificar uma variável nesses casos, certifique-se de que ela seja traduzida corretamente sempre que for definida como uma string literal.

String em arquivos XML

Para garantir que uma string seja adicionada ao dicionário e traduzida, deve ser utilizado o atributo translate=true ao gerar uma string em um arquivo XML.

<tag name="{tag_name}" xsi:type="string" translate="true">{Custom string}</item>

As strings traduzidas que se originam de arquivos XML não serão renderizadas, a menos que sejam chamadas com um método __(${var}) em arquivos PHP.

__($this->{paramName}->getData('{tag_name}'))

String em arquivos JS

Para garantir que uma string seja adicionada ao dicionário e traduzida, deve ser importada a biblioteca mage/translate no arquivo JS e usar a função $.mage.__('{string}') ou $t('{string}').

define ([
    'jquery',
    'mage/translate'
], function ($, $t) {
    $.mage.__('{Custom string}');
    $t('{Custom string}');
    $.mage.__('{Custom string with %1}').replace('%1', {var});
    $t('{Custom string with %1}').replace('%1', {var});
});

String em arquivos de email

Caso seja necessário traduzir strings em templates de e-mail personalizados, basta adicionar as strings de no arquivo de dicionário do idioma, use a diretiva {{trans}} para idicar que é uma string a ser traduzida.

{{trans "{Custom string}"}}
{{trans "{Custom string with %var" var="{variable value}"}}

⚠️ Os templates de e-mail personalizados adicionados através do painel de admintrador não são armazenados no sistema de arquivos e suas strings não são adicionadas ao dicionário. Neste tópico está sendo abordados os arquivos criados via código.

Arquivo CSV

O Magento 2 utiliza arquivos de idioma para armazenar as strings de texto que são exibidas para os usuários. Para isso é necessário criar um arquivo CSV para cada idioma suportado que contêm o texto original e a tradução.

Um dicionário de tradução é um arquivo de valores separados por vírgula (csv) com pelo menos duas colunas: a frase original na localidade en_US e uma tradução dessa frase em outra localidade. A nome do arquivo para a localidade usada em lojas com o português brasileiro deve ser pt_BR.csv

"{Custom string}","{Custom string translated}"
"{Custom string with %1}","{Custom string with %1 translated}"

Finalizando

Valores entre chaves ({test}) devem ser alterados na implementação do código.

Habilitando as alterações

Execute o comando PHP para limpar todos os caches de armazenamento em cache do processos.

php bin/magento cache:clean
php bin/magento cache:flush

Diretórios e Arquivos

Segue a a lista de diretórios e arquivos que devem ser criados para a criaçãod e tradução em um módulo.

- app/
  - code/
    - {Vendor}/
        - {Module}/
          - etc/
            - module.xml
          - i18n/
              - pt_BR.csv
          - registration.php
          - composer.json