Funções de Internacionalização do WordPress

Este post fala sobre as funções de internacionalizaçãointernationalization functions – disponíveis no WordPress.

O que é internacionalização?

Internacionalização é o processo de desenvolver seu projeto/tema/plugin de forma que o mesmo possa ser traduzido para outros idiomas.

Internacionalização é a tradução da palavra Internationalization. (Jura!?)

Internationalization é comunmente 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.

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:

Regular

Com contexto

Com escape para atributos

Com escape para HTML

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.

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

_e($text, $domain)

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


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

_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');

//Uma forma resumida de usar a função é esta:

printf(_n('%s comentário', '%s comentários', count($comments_number), 'text-domain'), count($comments_number));

_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 portugês pode significar
muitas coisas. Então, o contexto te ajuda a identifdicar 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 te ajuda a não se perder.

_ex($text, $context, $domain)

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


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

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

esc_attr__($text, $domain)

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

esc_attr_e($text, $domain)

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

esc_attr_x($text, $context, $domain)

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

esc_html__($text, $domain)

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

esc_html_e( $text, $domain )

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

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.

Comentários