Entenda melhor a tradução no Magento

Arquivos Mage_Catalog.csv com traduções pt_BR

Explicaremos nesse post as principais opções de traduções do magento e seu funcionamento. Abaixo os tipos de traduções da plataforma, seguindo por maior prioridade para menor prioridade:

  1. Tradução no Banco de Dados (tabela core_translate)
  2. Traduções do Tema (app/design/frontend/default/your-theme/locale/**/translate.csv)
  3. Arquivo de tradução específica do módulo (app/locale/**/*.csv)

Como o array de tradução é construído?

Primeiramente, os arquivos na pasta app/locale/*/*.csv são referenciados em cada módulo ativo nas suas respectivas pastas em etc/config.xml. Segue uma breve explicação de como o Magento carrega a tradução do módulo:
Assumimos que o Magento encontrou a seguinte configuração no arquivo config.xml:

<!-- extraído de app/code/core/Mage/Catalog/etc/config.xml -->
<frontend>
<translate>
<modules>
<Mage_Catalog>
<files>
<default>Mage_Catalog.csv</default>
</files>
</Mage_Catalog>
</modules>
</translate>
</frontend>

E no arquivo Mage_Catalog.csv, vamos supor que a seguinte tradução é especificada de acordo com idioma configurado para a view store (por exemplo: app/locale/pt_BR/Mage_Catalog.csv), contendo a seguinte linha:

"AAA","BBB"

Considerando essas informações, o Magento cria o seguinte registro no array de tradução:

array(
"AAA" => "BBB",
"Mage_Catalog::AAA" => "BBB"
)

O segundo item do array é conhecido como Module Scope Translation (tradução do escopo do módulo). O prefixo com o nome do módulo é o mesmo nomeado no node, criado no config XML do módulo, que declara o arquivo de tradução (<Mage_Catalog/>).

Se o mesmo termo de tradução é especificado em um segundo arquivo de tradução, por ex.: Some_Module.csv com o conteúdo "AAA","CCC", ele NÃO SOBRESCREVERÁ o termo "AAA". Na verdade, irá apenas adicionar um novo registro de tradução com o escopo do módulo: "Some_Module::AAA" => "CCC".

Se o modo developer estiver habilitado, o magento irá remover o registro de "AAA" se encontrar mais de uma versão para este mesmo termo. Isso facilita na hora de detectar conflitos de tradução durante o desenvolvimento.

As traduções carregadas do arquivo translate.csv (dentro do seu tema app/design/frontend/your-theme/name/locale/pt_BR/), simplesmente substituem (ou adicionam) os registros no array de tradução. Então, continuando com o mesmo exemplo, um registro "AAA","DDD" no arquivo translate.csv deve gerar os seguintes dados no array de tradução:

array(
"AAA" => "DDD", // Item substituído pelo translate.csv
"Mage_Catalog::AAA" => "BBB",
"Some_Module::AAA" => "CCC"
)

E, claro, novos termos no arquivo translate.csv são apenas adicionados no array de tradução.

Traduções existentes na tabela core_translate são basicamente mergeadas no array de tradução, semelhante as traduções do tema. Termos existentes dos módulos (module escope) e temas, são sobrescritos pelos registros existentes do banco de dados e novos termos são adicionados ao array de tradução. Os registros de traduções da tabela core_translate são adicionados pela opção de Tradução Inline (Translation Inline) do magento, para habilitá-la você pode ir pelo caminho Admin -> System -> Configuration -> Developer -> Translate Inline ou pelo n98-magerun com o seguinte comando:

./n98-magerun.phar dev:translate:shop
Habilitar a tradução inline no admin (core_translate)

Como o termo de tradução é chamado?

Quando o método __() é chamado no Magento, primeiramente, ele busca o termo no array de tradução utilizando como prefixo o nome do módulo atual de chamada. O módulo atual de chamada é determinado pelo nome da classe onde o método __() é chamado. Por exemplo, nas classes blocks o método responsável possui a seguinte lógica:

// Encontrado em Mage/Core/Block/Abstract.php
public function getModuleName()
{
$module = $this->getData('module_name');
if (is_null($module)) {
$class = get_class($this);
$module = substr($class, 0, strpos($class, '_Block'));
$this->setData('module_name', $module);
}
return $module;
}

Os métodos correspondentes para as classes Helpers e Controllers funcionam de forma semelhante.

Exemplo para a chamada de um termo de tradução

Digamos que a chamada $this->__('AAA') é realizado no arquivo de template. Se o block associado a este template possui o tipo de block da classe Mage_Core_Block_Template, o magento irá primeiro verificar se há o termo de tradução para Mage_Core::AAA. Se não o encontrar, o fallback de tradução irá buscar pela chave de tradução AAA, diretamente. No exemplo do cenário de tradução que criamos, o resultado da tradução seria DDD (que foi registrado pelo arquivo translate.csv).

Em um cenário diferente no qual o block associado ao template possa ser a classe Mage_Catalog_Block_Product_View. Nesse caso, o magento buscaria primeiramente pelo registro de tradução Mage_Catalog::AAA, e provavelmente encontraria a tradução BBB.

Para resumir, a tradução de module scope possui uma prioridade maior do que as traduções genéricas. De qual tradução de module scope o Magento buscará, depende de qual módulo a classe que está chamando o método __() pertence.

O que verificar se a tradução não funcionar?

Se a tradução no seu arquivo translate.csv não está sendo utilizado, verifique os seguintes itens:

  1. O cache de tradução está desabilitado ou atualizado? (Solução: limpe os caches)
  2. O arquivo translate.csv está realmente no fallback de chamada da sua loja? (Solução: resolva a configuração do tema)
  3. Há conflito de termos traduzidos na tabela core_translate do banco de dados? (Solução: remova o termo conflitante da tabela core_translate)
  4. Se os itens anteriores não surtiram efeito para solucionar o problema, você deve estar com conflito de tradução dos módulos. (Solução: veja abaixo)

Solução para conflito com tradução Module Scope

Se todas as tentativas de solucionar o conflito de tradução não funcionaram, simplesmente adicione o termo de tradução no arquivo translate.csv com a declaração do nome dos módulos (module scope). Nesse exemplo, se você quiser que o termo AAA seja sempre traduzido para DDD pela tradução do tema, você deve adicionar as seguintes linhas no arquivo translate.csv:

"AAA","DDD"
"Mage_Catalog::AAA","DDD"
"Some_Module::AAA","DDD"

Na prática, utilize essa solução apenas se você não conseguiu resolver de nenhuma outra forma, conforme sugerido. Evite essa opção a qualquer custo.

Informações adicionais

A tradução inline é uma funcionalidade do Magento que permite você realizar as traduções de forma mais fácil via interface, que serão inseridas diretamente na tabela core_translate, e que registrará sempre com o prefixo do nome da classe (module scope).

Tradução Inline Magento

A prioridade do tema de traduções costumava ser maior do que as traduções de banco de dados até o Magento versão 1.3.

O Magento, algumas vezes, utiliza o argumento translate="" nos arquivos config.xml, system.xml e layout XML para traduzir os valores dos nodes filho das respectivas configurações. Uma classe helper pode ser especificada para traduzir o termo, nesse caso, utilizando o argumento module="" para especificar module scope que será utilizado. Se nenhum argumento module é especificado no XML, o helper core/data é utilizado para traduzir os valores dos nodes filho.

<catalog translate="label" module="catalog">
<label>Catalog</label><!-- O termo "Catalog" será traduzido pelo helper catalog/data -->
</catalog>

Caso seja especificado no arquivo de configuração a tag module="aliashelper" e esse mesmo alias não for declarado no módulo como helper, o magento irá gerar o erro (página em branco) gerando o seguinte log:

PHP Fatal error: Class ‘Mage_Aliashelper_Helper_Data’ not found in ../app/Mage.php on line 555

Dentro de um Model, por exemplo, caso você queira forçar a tradução de algum termo para um Module Scope específico, você pode chamar a tradução direta pelo helper, dessa forma: Mage::helper('catalog')->__("AAA").

Finalizando…

Para resumir um pouco as informações desse post não entramos muito em méritos técnicos ou diferentes tópicos que podem ser abordados, como:

  • Maiores detalhes técnicos sobre como o array de tradução é construído
  • A possibilidade de usar arquivos de traduções adicionais dos módulos
  • Escopo de Store view para os registros na tabela core_translate
  • Prós e contras das diferentes opções de traduções da plataforma

Qualquer dúvida ou sugestão, deixe seu comentário. Abordaremos novos tópicos sobre as traduções nas próximas publicações. Até mais.

trezoteam

Blog destinado a artigos criados pela equipe #TrezoTeam

André Felipe T. da Luz

Written by

I'm developer, analyst and consultant in e-commerce, certified magento developer

trezoteam

trezoteam

Blog destinado a artigos criados pela equipe #TrezoTeam

More From Medium

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade