Funções de Internacionalização do WordPress

O que é internacionalização?

Internacionalização é o processo de desenvolver seu projeto/tema/plugin de forma que ele possa ser traduzido para outros idiomas. Portanto, a internacionalização do código é algo muito importante, e neste post você verá exemplos de como fazer uso das funções de internacionalização do WordPress para que seu código seja traduzível, por exemplo, por plugins como o WPML.

Internationalization é comumente escrito como i18n, porque entre o i e o n existem 18 letras. Ou seja, é uma forma mais rápida e fácil de fazer referência à palavra Internationalization.

Portanto, daqui em diante, quando eu escrever i18n estarei querendo dizer internationalization ou internacionalização.

O que usar para internacionalizar meu código?

Para deixar seu projeto “traduzível”, durante a escrita de seu código é necessário fazer uso das funções de i18n.

Existem 12 funções disponíveis:

Exemplos sobre como usar as funções de internacionalização

Veja abaixo uma explicação rápida sobre cada uma das funções acima e exemplos.

1. __($text, $domain)

Retorna a string. É usada quando não há necessidade de nenhuma das outras abaixo. Exemplos:

echo __('Welcome!', 'text-domain'); // Imprime "Welcome!" na tela.

$welcome = __('Welcome!', 'text-domain'); // Armazena "Wecolme!" numa variável.

2. _e($text, $domain)

Imprime a string. Quando se quer imprimir ao invés de retornar usa-se esta aqui. Útil para economizar algumas linhas de código, quando possível. Exemplo:

_e('Welcome', 'text-domain'); // Imprime "Welcome" na tela.

3. _n($single, $plural, $number, $domain)

Retorna a string. Quando uma palavra depende do valor de um número para saber se será usada no plural ou singular, usa-se esta aqui. Exemplos:

// Obtendo o número de comentários.
$count_comments = count($comments_number);

// Se $count_comments é igual 1, então, na tela veremos "1 comentário".
// Caso contrário, veremos "0 comentários" ou "2 comentários" e assim por diante.
echo _n("$count_comments comentário", "$count_comments comentários", $count_comments, 'text-domain');

// Outra forma mais elegante de usar a função:
printf(_n('%s comentário', '%s comentários', count($comments_number), 'text-domain'), count($comments_number));

4. _x($text, $context, $domain)

Retorna a string. Essa função é idêntica a __() com exceção do fato de que aqui podemos usar um contexto.
Imagine que você quer deixar a palavra “meia” traduzível. Sabemos que “meia” em português pode significar muitas coisas. Então, o contexto te ajuda a identificar qual “meia” é qual. Veja o exemplo:

// No momento em que você está traduzindo, será possível traduzir a palavra "meia" duas vezes,
// e o software te mostrará o contexto para que você traduza os textos dentro do contexto.
echo _x('meia', 'meia entrada', 'text-domain');

echo _x('meia', 'meia do pé', 'text-domain');

Usando um software como o Poedit, por exemplo, é possível ver o contexto de cada palavra/frase. Ou seja, o programa ajuda você a se localizar e a se organizar.

5. _ex($text, $context, $domain)

Imprime a string. Idêntica à função _x(). Mas, ao invés de retornar, essa aqui imprime. Exemplo:

_ex( 'meia', 'meia entrada', 'text-domain' ); // Imprime "meia" na tela.

6. _nx($single, $plural, $number, $context, $domain)

Retorna a string. Essa função é uma junção de _n() e _x(). Ou seja, é possível passar um contexto, o singular e o plural.

7. esc_attr__($text, $domain)

Retorna a string. Essa função é uma junção de esc_attr() e __().

8. esc_attr_e($text, $domain)

Imprime a string. Essa função é uma junção de esc_attr() e _e().

9. esc_attr_x($text, $context, $domain)

Retorna a string. Essa função é uma junção de esc_attr() e _x().

10. esc_html__($text, $domain)

Retorna a string. Essa função é uma junção de esc_html() e __().

11. esc_html_e($text, $domain)

Imprime a string. Essa função é uma junção de esc_html() e _e().

12. esc_html_x($text, $context, $domain)

Retorna a string. Essa função é uma junção de esc_html() e _x().

Como traduzir meu projeto internacionalizado para outra língua?

Agora que você já sabe o que é i18n e como usar as funções de i18n, o próximo passo é saber como criar um arquivo .pot (portable object template) para que você ou outras pessoas possam traduzir seu tema/plugin para outros idiomas. Em breve postarei um novo artigo falando sobre isso.