Como internacionalizar seu site WordPress

Em 30 de setembro de 2017, a comunidade internacional do WordPress se uniu por 24 horas para traduzir o ecossistema WordPress. Pela terceira vez, o #WPTranslationDay fundiu uma maratona de tradução de um dia inteiro com eventos digitais e do dia do colaborador, projetados para promover o valor de criar experiências acessíveis para usuários globais, mais conhecido como "localização".

Como uma comunidade de código aberto, todos devemos nos esforçar para localizar nossas contribuições de código aberto. Antes de transcrever seus ativos digitais, você precisa internacionalizar sua base de código.

Os termos “internacionalização” e “localização” são frequentemente usados ​​de forma intercambiável, embora representem tecnicamente dois aspectos diferentes do processo de tradução.

• Internacionalização (I18N) é o processo de internacionalização ou adaptação do seu tema ou plugin para traduzi-lo em qualquer idioma do mundo.
• Localização (L10N) é o processo subsequente de localização ou tradução de suas ferramentas internacionalizadas para um determinado idioma.

Atualmente, o WordPress está totalmente localizado para mais de 65 idiomas e oferece traduções parciais para mais 95 localidades. O uso internacional continua a aumentar à medida que mais localizações são introduzidas.

Os usuários do WordPress que não falam inglês superaram os usuários que falam inglês em 2014 e, inadvertidamente, continuam a diluir a porcentagem de torta dos usuários ingleses em 2017, à medida que esforços como #WPTranslateDay crescem.

À medida que o WordPress se torna cada vez mais acessível linguisticamente, o conhecimento de I18N e L10N é essencial para que desenvolvedores de plugins e temas prosperem na economia global do WordPress. Para expandir os negócios, essas habilidades de desenvolvimento podem abrir portas para mercados estrangeiros. A acessibilidade da Web, incluindo acessibilidade de idioma, é boa para os negócios e melhor para as pessoas.

Como continuação do #WPTranslationDay , aqui está um guia atualizado para internacionalizar seus plugins e temas do WordPress.

Aqui está uma breve visão geral do processo que vamos explorar hoje.

• Descoberta
  • Conheça os arquivos de tradução
    • Arquivo POT
    • Arquivo PO
    • Arquivo MO
  • GlotPress e pacotes de idiomas
  • Faça backup e prepare seu ambiente
• Plugin I18N
  • Cabeçalho do plug-in
  • Carregar domínio de texto
  • Auditoria de Strings
  • Gerar arquivo POT
• Tema I18N
  • Cabeçalho do Tema
  • Carregar domínio de texto
  • Auditoria de Strings
  • Gerar arquivo POT
• JavaScript I18N
• Recursos adicionais

Descoberta

Conheça os arquivos de tradução

O WordPress usa a biblioteca GNU gettext para facilitar o I18N.

Primeiro, vamos nos familiarizar com os arquivos de tradução gettext gerados ao longo do processo.

Arquivo de modelo de objeto portátil (POT)

Durante o processo I18N, usaremos uma ferramenta para encontrar strings internacionalizadas e gerar um arquivo POT contendo todo o texto traduzível em seus plugins e tema.

Arquivo de Objeto Portátil (PO)

Na aparência, não há diferenças notáveis ​​entre um arquivo POT e um arquivo PO . Eles são sintaticamente iguais e diferenciados apenas por seus propósitos pretendidos.

Depois de gerar um arquivo POT, as strings de texto devem ser interpretadas por um tradutor em seu idioma preferido. O arquivo PO conterá eventualmente strings de texto em seu idioma nativo, bem como as traduções apropriadas.

Arquivo de Objeto de Máquina (MO)

Finalmente, o arquivo PO é convertido em um documento legível por máquina ou arquivo de objeto de máquina. Este arquivo ficará em seu diretório de temas ou plugins para o WordPress chamar quando for a hora de servir uma versão traduzida.

Faça backup e prepare seu ambiente

Antes de modificar qualquer marcação, faça um backup do seu plugin, tema ou site inteiro (o que quer que você esteja internacionalizando!) e coloque seus ambientes de desenvolvimento em ordem.

Certifique-se de fazer uma auditoria rápida do plug-in se você planeja localizar seu site. Exclua ou desative qualquer plug-in que você não esteja mais usando ativamente. Essa auditoria rápida economizará seu tempo a longo prazo.

Internacionalize seus plugins

CABEÇALHO DE PLUGIN

Primeiro, vamos atualizar o cabeçalho do plugin. Especificamente, o domínio do texto e o caminho do domínio .

Cabeçalho de plug-in de exemplo

 /* Plugin Name: My Rad Plugin Plugin URI: https://myradplugin.com Description: Custom Plugin That Makes My Site Rad Author: Rad Plugin Creator Version: 1.0 Author URI: https://radplugincreator.com Text Domain: rad-plugin Domain Path: /languages/ */

Domínio de texto

O domínio de texto é um identificador exclusivo para o WordPress reconhecer todo o texto pertencente a um plug-in e deve corresponder ao slug do plug-in .

Isso é especialmente importante se seu plugin estiver hospedado no WordPress.org; eles precisam corresponder para que o GlotPress importe corretamente as traduções para o seu plug-in.

Em nosso exemplo, o arquivo de plug-in é denominado rad-plugin.php e o domínio de texto é rad-plugin

Você já pode ter um domínio de texto definido. Caso contrário, lembre-se de usar hífens, não sublinhados.

Caminho do domínio

O caminho do domínio é a pasta na qual os arquivos de tradução finalizados ficarão. Você deve criar uma nova pasta no diretório do plug-in, como /languages/ , e atualizar o caminho do domínio, para que o WordPress saiba exatamente onde procurar os arquivos de tradução.

CARREGAR DOMÍNIO DO TEXTO

Em seguida, vamos carregar o domínio de texto adicionando a seguinte função ao nosso código.

load_plugin_textdomain()

 load_plugin_textdomain( $domain, $abs_rel_path, $plugin_rel_path );

Se um arquivo de tradução estiver disponível para o idioma do usuário, a função carregar domínio de texto informará ao WordPress para entregá-lo.

Parâmetros

• $domain — domínio de texto (obrigatório)
• $abs_rel_path — false (opcional, obsoleto)
• $plugin_rel_path — /languages/ (opcional, este é o caminho relativo para o diretório que contém seus arquivos de tradução. Em nosso exemplo, /languages/. A partir da versão 4.6, o WordPress procurará esses arquivos no diretório /languages/ do plugin, se isso não é especificado.)

Exemplo de plug-in Rad

Para carregar o domínio de texto, usaremos a ação 'plugins_loaded'.

 add_action( 'plugins_loaded', 'rad_plugin_load_text_domain' ); function rad_plugin_load_text_domain() { load_plugin_textdomain( 'rad-plugin', false, dirname( plugin_basename( __FILE__ ) ) . '/languages/' ); }

AUDITORIA DE STRINGS

O próximo passo é envolver todas as strings de texto do plugin em funções de tradução.

As funções de tradução mais comuns são __() para retornar uma string traduzida e _e() para ecoar uma string traduzida.

Exemplo de plug-in Rad

 __() $text = __( 'Super Rad!', 'rad-plugin' );

Esta função funcionará para traduções simples. Leva em consideração dois parâmetros; a string de texto e o domínio de texto .

 _e( 'Super Rad!', 'rad-plugin' );

Esta função simplesmente ecoa o valor. Caso contrário, funciona exatamente como a função anterior.

Há uma série de funções de tradução adicionais que também devem ser usadas quando apropriado.

Outras funções básicas

 __() _e() _x() _ex() _n() _nx() _n_noop() _nx_noop() translate_nooped_plural()

Funções de data e número

 number_format_i18n() date_i18n()

Funções de escape

Não se esqueça de escapar quaisquer dados que estão sendo emitidos usando as seguintes funções de escape.

 esc_html__() esc_html__() esc_html_x() esc_attr__() esc_attr_e() esc_attr_x()

Em nosso exemplo Rad, podemos ter uma linha de código de plugin que se parece com isso:

 function create_section() { esc_html_e( 'Below are your settings for Rad Plugin', 'rad-plugin' ); }

CRIAR UM ARQUIVO DE POTE

A etapa final é criar um arquivo POT. Existem algumas ferramentas diferentes disponíveis para gerar esse tipo de arquivo, mas para este tutorial, seguiremos as recomendações do codex do WordPress e usaremos o Poedit, uma GUI fácil de usar para gerenciar traduções.

Nota : Se o seu plugin ou tema já estiver no repositório WordPress.org, você pode pular este processo e gerar um arquivo POT na página de administração. Neste caso, não é necessário gerar um arquivo .po para cada idioma. A introdução do GlotPress e dos pacotes de idiomas em 2015 simplificou o processo de tradução; tudo o que é necessário para o GlotPress é o arquivo .pot, que será importado pelo WordPress.org e servido aos tradutores através do painel translate.wordpress.org. Colaboradores de todo o mundo usarão este painel para fornecer traduções no #WPTranslateDay.

Baixar Poedit

Configurando o Poedit

Propriedades de tradução

Comece indo em Arquivo > Novo . Em seguida, selecione o idioma nativo do seu plug-in e clique em OK .

Em seguida, selecione Catálogo > Novo . Insira o nome do projeto, versão, contato e idioma.

Caminhos

Selecione a guia Caminhos de Fontes a seguir. Se este for um arquivo novo, você terá que salvar o arquivo primeiro.

Seguindo nosso exemplo, selecionaríamos File > Save As para salvar como um arquivo .po no diretório /languages/ dentro do rad-plugin. Novamente, o nome do arquivo deve corresponder ao slug do seu plugin.

 rad-plugin.po

Depois de salvar, insira o caminho relativo para o diretório onde seus arquivos de tradução ficarão. Neste cenário, os idiomas .

Palavras-chave

Selecione a guia Palavras-chave de fontes . Clique no ícone + para adicionar os nomes de função apropriados.

Folha de dicas

 __ _e _x _ex _n _nx _n_noop _nx_noop translate_nooped_plural number_format_i18n date_i18n esc_html__ esc_html__ esc_html_x esc_attr__ esc_attr_e esc_attr_x

Depois, você pode clicar em OK e depois em Arquivo > Salvar .

O Poedit salvará um arquivo .mo e um arquivo .po. Você pode criar o arquivo .pot copiando o arquivo .po e adicionando uma extensão .pot. Os usuários internacionais podem usar o arquivo de modelo .pot para traduzir as strings para seu idioma.

Internacionalize seu tema

O processo de internacionalização do seu tema é praticamente idêntico ao do I18N para plugins. Começaremos verificando o cabeçalho do tema e terminaremos gerando outro arquivo POT.

CABEÇALHO DO TEMA

Verifique novamente o cabeçalho do seu tema para certificar-se de que o domínio do texto e o caminho do domínio estão definidos.

Cabeçalho de tema de exemplo

 /* Theme Name: Rad Theme Author: Rad Theme Author Text Domain: rad-theme Domain Path: /languages/ */

CARREGAR DOMÍNIO DO TEXTO

O próximo passo é carregar um domínio de texto no arquivo functions.php do seu tema desta vez.

load_theme_textdomain()

 load_theme_textdomain( 'radtheme', get_template_directory() . '/languages' );

Para que esses arquivos sejam carregados, você deve registrá-los com a ação after_setup_theme.

 add_action( 'after_setup_theme', 'rad_theme_setup' ); function rad_theme_setup() { load_theme_textdomain( 'radtheme', get_template_directory() . '/languages' ); }

AUDITORIA DE STRINGS

Hora de outra auditoria de cordas! Você deve estar familiarizado com as funções básicas de tradução neste momento.

Vamos dar uma olhada em algumas traduções mais complicadas.

Espaços reservados

Variáveis ​​PHP como o exemplo abaixo não serão traduzidas corretamente sem o uso de espaços reservados.

 echo "We added $count rad points.";

printf() & sprintf()

Essas funções usam espaços reservados como %s ou %d para inteiros, para interpolar uma string de texto com conteúdo dinâmico.

Exemplo de tema Rad

 /* Translators: %d is the number of rad points added */ printf( esc_html__( 'We added %d rad points.', 'rad-plugin' ), $count );

Plurais

A função _n() pode lidar com traduções de strings mais complexas como plurais, mas não é recomendada devido às suas limitações no software de tradução. Em vez disso, você pode escrever uma instrução if simples para distinguir entre palavras no singular e no plural.

Exemplo de plug-in Rad

 If ( 1 === $rad_points_found ) { $message = __( '1 rad point', 'rad-plugin' ); } else { /* Translators: %s is the number of rad points found */ $message = sprintf( __( '%s rad points' , 'rad-plugin' ) , $rad_points_found ); }

GERAR ARQUIVO DE POTE

O processo para gerar arquivos POT de tema é o mesmo que gerar arquivos POT de plug-in. Explore alguns métodos abaixo.

Linha de comando

Com o WordPress Trunk e o pacote gettext GNU instalados, você pode passar rapidamente por esta etapa executando o script makepot.php na linha de comando.

Abra a linha de comando e navegue até o diretório de ferramentas I18N.

 cd wpdev/tools/i18n/

O script deve ficar mais ou menos assim:

 php path/to/makepot.php wp-theme path/to/rad-theme rad-theme.pot

O script fará seu trabalho e o arquivo finalizado, rad-theme.pot , terminará no diretório atual.

Tarefas Grunt

Outro método para criar um arquivo POT é executar tarefas Grunt usando grunt-wp-i18n ou grunt-pot. Executores de tarefas como o Grunt podem automatizar muitas tarefas tediosas, como gerar arquivos POT.

Para criar seu arquivo POT, certifique-se de ter o node.js instalado primeiro. Em seguida, instale o Grunt em seu diretório de idioma através da linha de comando e pronto. Agora, você pode executar rapidamente esses comandos I18N e fazer seu arquivo de tradução sem sair do conforto da linha de comando.

JavaScript I18N

Se você é um desenvolvedor moderno de temas ou plugins, é provável que use JavaScript para lidar com algum componente do seu projeto. wp_localize_script é uma função eficaz para extrair dados PHP para fornecer aos seus scripts, e é a única maneira de traduzir JavaScript dentro do WordPress.

WP_LOCALIZE_SCRIPT()

Esta função nos permitirá localizar strings do lado do servidor em PHP e fornecer strings de texto como um objeto JavaScript para o script.

 wp_localize_script( $handle, $name, $data );

PARÂMETROS

• $handle — identificador do script para o qual os dados precisam estar disponíveis (obrigatório — precisa corresponder ao identificador do script para o qual esses dados se destinam, veja o exemplo abaixo)
• $name — nome do objeto para conter os dados (obrigatório — deve ser único)
• $data — uma matriz de dados para passar para o script (obrigatório) .

EXEMPLO DE PLUGIN RAD

 add_action( 'wp_enqueue_scripts', 'rad_theme_scripts' ); function rad_theme_scripts() { wp_enqueue_script( 'rad-theme-script', get_template_directory_url() . '/js/rad-theme-script.js' ); wp_localize_script( 'rad-theme-script', 'rad-I18n', array( 'message' => __( 'Super Rad!', 'rad-theme' ), ) ); }

ACESSAR DADOS EM JAVASCRIPT

O snippet de código simples abaixo é um exemplo de como acessar esses dados em seu arquivo JavaScript.

 alert( rad-I18n.message );

Recursos adicionais

• I18N para desenvolvedores WordPress
• Manual do Tema WordPress: Internacionalização
• Manual do plugin WordPress: Internacionalização
• WordPress.tv: I18N

Embrulhando-o

Parabéns! Você acabou de internacionalizar seu tema e/ou plugin, tornando-o acessível para pessoas de todos os idiomas nativos. Quer seu projeto seja distribuído por meio do repositório do WordPress ou desenvolvido sob medida para o site da sua organização, há apenas uma vantagem em internacionalizar seus arquivos desde o início.

• Torne suas contribuições de código aberto acessíveis globalmente.
• Crie conversas com novos clientes em mercados estrangeiros.
• Economize tempo e reduza as atualizações trabalhosas no futuro.

Sempre internacionalize.