Como eu havia comentado nesse post, eu estava com esse conteúdo na cabeça há algum tempo e finalmente encontrei tempo para tirá-lo do rascunho.

Tradução de temas e plugins ainda é algo relativamente complicado para quem está começando na área ou até mesmo para desenvolvedores mais avançados que não conhecem muito bem o WordPress.

Antes de começar a falar sobre tradução preciso explicar a diferença entre Internacionalização e Localização:

Internacionalização
É o processo de desenvolver seu plugin ou tema de uma forma que seja possível traduzi-lo facilmente.
É comum abreviar o termo como i18n (por que há 18 letras entre as letras i e n na palavra internacionalization).

 

Localização
Se refere a todos os processos de tradução do seu tema ou plugin.
Normalmente é abreviado como l10n (por que há 10 letras entre as letras l e n na palavra localization).

Resumindo: Para que um tema ou plugin seja traduzido (localizado) é preciso que ele esteja internacionalizado.

Nesse primeiro post falarei sobre…

Internacionalização

A pasta onde os arquivos com as traduções serão salvos pode ser alterada, mas a maioria dos desenvolvedores utiliza languages ou lang. Usarei languages nos exemplos abaixo.

Internacionalizando seu tema

Para tornar seu tema traduzível é necessário adicionar os seguintes comentários no arquivo style.css:

E o seguinte código no functions.php:

Internacionalizando seu plugin

Plugins e temas são coisas bem diferentes, mas o sistema de internacionalização é bem parecido.

Como o arquivo style.css não é obrigatório para plugins, você precisa inserir o seguinte código no arquivo apenas-um-exemplo.php:

Como escolher o textdomain do seu tema ou plugin

Não pode conter underscores, apenas hifens:

  • apenas-um-exemplo é válido
  • apenas_um_exemplo é inválido

O textdomain deve seguir o slug do seu tema ou plugin:

  • Se o seu tema ou plugin está salvo na pasta /apenas-um-exemplo o textdomain deve ser apenas-um-exemplo
  • Se o seu plugin é composto por apenas um arquivo por-exemplo.php , o textdomain deve ser por-exemplo

O slug (e o textdomain por consequência) deve ser único. Caso contrário isso pode gerar conflito com algum tema ou plugin que utilize o mesmo slug.

Inserindo textos nos arquivos

Agora que você já informou o seu textdomain no seu tema ou plugin, você pode começar a inserir textos no seu projeto. Vamos chamar esses textos de strings.

O WordPress utiliza a biblioteca gettext que adiciona funções que facilitam muito a vida dos desenvolvedores.

Imagine se você precisasse criar manualmente uma condição para checar o idioma que está sendo exibido e carregar a string correta. Imagine isso num projeto que é disponibilizado em dezenas de idiomas, que é o caso do WordPress.

Você precisaria criar dezenas de ifs para cada string

Que bom que o gettext existe 🙂

É recomendado que todas as strings no seu projeto sejam criadas em Inglês, isso torna mais fácil a comunicação entre os desenvolvedores e tradutores.

As funções do gettext mais utilizadas no WordPress são essas:

__( $string, $textdomain )

Torna a string traduzível, mas sem exibi-la.

Por não ter echo automático é muito boa para ser usada em variáveis.

_e( $string, $textdomain )

Tem a mesma função da __(), porém, com echo.

_x( $string, $context, $textdomain )

É a __() com contexto.

Muitas vezes a mesma palavra pode ter significados diferentes dependendo do seu contexto, porém, o tradutor não tem como saber onde a string está sendo usada. Essa função resolve esse problema!

Close pode ser um verbo (fechar) ou adjetivo (perto de). Sempre que necessário, informe o contexto da sua string e algum exemplo.

_ex( $string, $context, $textdomain )

É a _e() com contexto.

_n( $singular, $plural, $number, $textdomain )

Função usada para strings que tenham versões diferentes no singular e no plural mas que precisam ser inseridas no mesmo local.

Assim não é necessário escrever código extra só para checar a quantidade salva em $number.

_nx( $singular, $plural, $number, $context, $textdomain )

É a _n() com contexto.

No exemplo anterior o tradutor não tem como saber se a string table deve ser traduzida como mesa (mesas) ou tabela (tabelas). Mais uma vez precisamos informar o contexto.

Ainda existem outras funções úteis, mas agora que você já entendeu o funcionamento, basta ver a documentação de cada uma 😛

Caso você queira ler mais sobre i18n, você pode acessar o Codex do WP.

Gerando o arquivo .pot

É possível gerar o .pot usando o terminal do seu sistema operacional, mas você precisará ter o gettext e PHP instalados.

Basta rodar os seguintes comandos em seu tema:

E os seguintes em seu plugin:

Eu estava escrevendo um só post para falar de Internacionalização e Localização, mas achei melhor criar 2 posts distintos para melhorar a organização.

Publicarei a continuação em breve.

Leia a segunda parte desse tutorial em Como traduzir temas e plugins do WordPress.

Deixe uma resposta