Já lhe aconteceu fazer o download de um tema que seria perfeito para o blog ou site que estava planejando, mas descobre que ele só dá em Inglês? Você tenta fazer tudo para o colocar em Português, mesmo criando o  ficheiro a partir do PoEdit, mas mesmo assim existem muitas strings que não estão a traduzir?

Pois bem, isso acontece-me por vezes e sei que a muitos usuários do WordPress também. É frustrante, principalmente quando você paga por um tema que acaba por não o servir.

Neste tutorial iremos ensinar-lhe como poderá rapidamente preparar cada parte do seu tema para ser traduzível, apresentando-lhe as funções em PHP que efetuam as traduções e maneiras rápidas e simples de o fazer. No final do artigo tem disponível uma QuickList com todas as funções, para que servem e um exemplo de aplicação para cada uma delas.

Este tutorial extende o artigo anteriormente publicado Como traduzir um Template WordPress para Português.

PORQUÊ PREPARAR UM TEMA PARA TRADUÇÃO?

O WordPress já não é apenas um sistema de gestão de conteúdos para blogues, atualmente é uma autentica framework para criação de websites de todo o tipo. Os autores de Temas WordPress devem ter sempre em mente que preparar um tema para tradução já não é apenas um benefício, é um requisito mesmo! Possibilita não só os usuários poderem usar o seu tema em qualquer lingua como também poderem fazê-lo sem ter que editar nenhum ficheiro do tema.

ANATOMIA DA TRADUÇÃO EM WORDPRESS

O sistema de tradução de texto (chamado também de string) do WordPress é baseado no famoso sistema de internacionalização Gettext. Este sistema é amplamente usado em vários outros programas tanto na Web como em Desktop. O conceito é muito simples e para que este funcione pressupõem-se que:

  1. todas as strings estáticas dentro do programa estejam preparadas para ser traduzidas, isto é, sejam parâmetros da função gettext(‘string-a-traduzir’);
  2. exista um ficheiro com uma tabela que contenha como entradas na primeira coluna as strings para serem traduzidas e na segunda o seu equivalente na língua que estamos a traduzir;

No WordPress, a principal função responsável para tradução é _e(‘string-a-traduzir’). Ela irá procurar pela string fornecida dentro do ficheiro .mo e irá imprimir a tradução dessa string.

Para se compreender melhor esta anatomia, o diagrama de baixo tenta demonstrar como é que o WordPress traduz strings passadas a esta função:

  1. A função _e() procura pela string fornecida na primeira coluna do ficheiro .mo;
  2. Se existir, retorna a string traduzida, a que se encontra imediatamente à direita, e imprime-a na tela;

Além da função _e() existem outras que nos ajudam a traduzir casos mais dificeis. Iremos falar delas mais adiante.

COMO PREPARAR O TEMA PARA TRADUÇÃO

É muito simples preparar o tema que tem consigo para ser traduzível. Basta procurar entre os templates pelo texto “solto”. Como exemplo, imagine que no seu novo tema aparece o seguinte trecho de HTML num template:

<h1>This is a title</h1>

Neste momento, se você colocar o seu site em Português, este trecho apresentará o texto This is a title e nunca a tradução, mesmo que você o tenha criado o seu ficheiro .mo.

Imprimir uma string usando a função _e()

O que você deve fazer aqui é colocar essa string como parâmetro da função _e() modificando o trecho de código para:

<h1><?php _e( 'This is a title' ); ?></h1>

A  existência da função de tradução é o primeiro passo para a tradução dos seus templates, no entanto vai-se deparar com situações mais complicadas em que este função só não resolve a situação.

Retornar uma string para uma variável usando a função __()

Esta função em vez de imprimir a string irá retorná-la para uma variável. É muito útil caso haja necessidade de traduzir algo que não deve ser apresentado naquele momento. A expressão seguinte é equivalente à anterior, no entanto a string traduzida é guardada numa variável. Essa variável seguidamente é impressa na tela através da função PHP nativa echo:

<?php $variavel = __( 'This is a title' ); ?>
<h1><?php echo $variavel; ?></h1>

Imprimir texto de acordo com o número de comentários

Existem casos em que o texto a apresentar depende do valor que obtivermos antes ou depois, como por exemplo, o número de comentários feitos a um post.
No caso de haver apenas um comentário queremos que apareça o texto 1 comentário e nos outros casos que apareça n comentário.

Este é um caso de desambiguação por singular ou plural, podendo ser usado este snippet:

<?php printf( _n( 'One Comment', '%s Comments', get_comments_number() ), get_comments_number() ); ?>

A função _n() aceita como parâmetros:

  1. String a apresentar quando é singular (apenas um comentário)
  2. String a apresentar quando é plural zero ou mais de um comentário)
  3. Um número inteiro (neste caso o número de comentários ao post)

A função printf() é nativa do PHP e formata uma string substituindo %s pela string dada no segundo parâmetro, mas não é requisito. Neste exemplo é apenas usada como forma de apresentar o número diretamente no template através da substituição na string.

ACRESCENTAR UM DOMÍNIO PARA TRADUÇÃO

Um domínio de tradução é uma string identificadora de uma tabela de traduções .mo, e é responsável por identificar a que ficheiro é que o Gettext deve ir buscar a tradução. Ela existe de forma a desambiguar casos em que dois ficheiros diferentes contêm a mesma string e traduções diferentes. Assim, ela vai buscar a tradução que corresponde à string associada ao identificador fornecido.

Para poder carregar o seu ficheiro .mo, é necessário escolher o seu identificador e colocar o seguinte código no functions.php (não se esqueça de alterar o identificador):

add_action( 'after_setup_theme', 'meu_blog_traducao_init' );
function meu_blog_traducao_init() {
    load_theme_textdomain( 'meu-identificador', TEMPLATEPATH . '/languages' );
}

Agora, dentro de cada função, em vez de proceder apenas colocando a string, terá também que incluir o seu identificador como último parâmetro. Seguem alguns exemplos para o ajudar a perceber:

<h3><?php _e( 'A title', 'meu-identificador' ); ?></h3>
<?php $variavel = __( 'Something', 'meu-identificador' ); ?>
<?php echo _n( 'One', 'More', $numero, 'meu-identificador' ); ?>

Se tiver acesso a uma consola do seu sevidor, poderá sempre automatizar este processo usando uma ferramenta fornecida pelo pessoal do WordPress que adiciona o identificador às funções por si. O ficheiro encontra-se aqui e o comando a passar na consola é:

php add-textdomain.php -i identificador phpfile phpfile ...

Se quiser saber mais sobre o sistema de tradução, poderá encontrar mais informações detalhadas (em Inglês) aqui.

QUICKLIST PARA AJUDAR NA TRADUÇÃO

Em baixo temos uma Cheatsheet que o vai ajudar a lembrar-se das funções mais comuns e do snippet de código que terá que colocar no ficheiro functions.php de modo que o tema seja traduzível.

Fazer download da versão em PDF

Gostou do artigo? Ajudou-o de alguma forma? Não se esqueça: comente em baixo! :)

Um abraço e até breve,

Vitor Carvalho