Como fazer traduções no Magento 2
Tags: php, magento2, tutorial, braziliandevs
Published: 2023-05-08 12:24:12

## 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**.

```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**.

```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**. 

```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}')`.

```jsx
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.

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

<aside>
⚠️ 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.

</aside>

### 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`

```xml
"{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.

```bash
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
```