Como inserir suporte a tradução em temas e plugins do WordPress

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:

/**
 * Theme Name: Apenas um exemplo
 * Author: Autor do tema
 * Text Domain: apenas-um-exemplo
 * Domain Path: /languages
 */

E o seguinte código no functions.php:

<?php
add_action( 'after_setup_theme', 'mytheme_load_textdomain' );

function mytheme_load_textdomain() {
    load_theme_textdomain( 'apenas-um-exemplo', get_template_directory() . '/languages');

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:

<?php
/**
 * Plugin Name: Apenas um exemplo
 * Author: Autor do plugin
 * Text Domain: apenas-um-exemplo
 * Domain Path: /languages
 */

add_action( 'plugins_loaded', 'myplugin_load_textdomain' );

function myplugin_load_textdomain() {
    load_plugin_textdomain( 'apenas-um-exemplo', false,dirname( plugin_basename( __FILE__ ) ) . '/languages' );
}

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:

• __()
• _e()
• _x()
• _ex()
• _n()
• _nx()

__( $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.

<?php
// Exemplo
__( 'This is my string.', 'apenas-um-exemplo' );

// Setando uma variável
$my_text = __( 'This is my string.', 'apenas-um-exemplo' ); 

// Exibindo no código
echo __( 'This is my string.', 'apenas-um-exemplo' );

_e( $string, $textdomain )

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

<?php
// Exemplo
echo __( 'This is my string.', 'apenas-um-exemplo' );
_e( 'This is my string.', 'apenas-um-exemplo' );

_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!

<?php
// Exemplo
_x( 'Close', 'verb: Close the door', 'apenas-um-exemplo' );

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.

<?php
// Exemplo
echo _x( 'Close', 'verb: Close the door', 'apenas-um-exemplo' );
_ex( 'Close', 'verb: Close the door', 'apenas-um-exemplo' );

_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.

<?php
// Exemplo
$number = '3';
$text = sprintf( _n( '%s table', '%s tables', $number, 'apenas-um-exemplo' ), $number );
echo $text; // 3 tables

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.

<?php
// Exemplo
$number = '3';
$text = sprintf( _nx( '%s table', '%s tables', $number, 'noum: a piece of furniture with a flat top and one or more legs', 'apenas-um-exemplo' ), $number );
echo $text; // 3 tables

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

• esc_html__()
• esc_html_e()
• esc_html_x()
• esc_attr__()
• esc_attr_e()
• esc_attr_x()
• _n_noop()
• _nx_noop()
• translate_nooped_plural()

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:

cd theme-name/languages
php path/to/makepot.php wp-theme path/to/your-theme-directory

E os seguintes em seu plugin:

cd plugin-name/languages
php path/to/makepot.php wp-plugin path/to/your-plugin-directory

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.