Nesta lição, aprendemos como funciona a tradução (ou também conhecida como i18n) no WordPress e como fazer os ajustes necessários em nossos modelos. Também aprenderemos como configurar corretamente o PoEdit para criar um arquivo de tradução para o nosso tema, pronto para ser traduzido em diferentes idiomas.
Por que se preocupar em adicionar suporte à tradução?
Todos os temas, pelo menos aqueles que se tornam públicos para uso de outras pessoas que não o desenvolvedor, devem estar disponíveis para tradução. Isso é chamado de internacionalização (i18n em resumo) e permite que as pessoas traduzam os textos que você adiciona em seu tema para outro idioma.
A maneira como isso funciona é que você, como autor de temas ou desenvolvedor de plugins, envolve todos os seus textos (como “Leia mais", “Sem postagens”) em determinadas funções. Essas funções fazem com que o WordPress seja capaz de pegá-los e injetar uma tradução se ela existir. Dentro do seu tema (ou plugin) você pode adicionar arquivos de um determinado tipo de arquivo para cada idioma traduzido, ou certificar-se de que outras pessoas possam criar sua própria tradução em seu próprio idioma.
Isso é muito útil para pessoas que desejam usar o WordPress e seu tema (ou plugin) em um idioma diferente do idioma de origem em que foi escrito (que geralmente é o inglês). Mas também pode ser utilizado para alterar certos textos para algo diferente dentro do mesmo idioma.
Se você estiver interessado no assunto, o WordPress Codex tem um guia de documentação longo e bom sobre i18n para desenvolvedores.
Implementando i18n em nosso tema
Já fizemos a primeira parte na etapa anterior desta série de tutoriais de temas, onde adicionamos load_theme_textdomaina função de configuração do nosso tema. Caso você tenha esquecido, isso é o que adicionamos:
load_theme_textdomain('wptutorial', get_stylesheet_directory(). '/lang');O primeiro argumento é o handle, esta é uma string única que você usará para agrupar todos os textos que pertencem ao seu tema. Você repetirá essa alça toda vez que fizer um texto traduzível. O segundo argumento informa ao WordPress onde estão os arquivos de tradução. Nós os definimos para residir em uma subpasta ‘ lang‘ em nosso diretório de temas.
Não se preocupe se esta pasta não existir ou não contiver nenhum arquivo – nada irá travar. Se o WordPress não encontrar a pasta nem os arquivos de tradução corretos, o padrão voltará aos textos que temos no tema.
O próximo passo é passar por todo o nosso código e encontrar qualquer saída de texto que deva ser traduzível. É uma boa prática garantir que abrangemos absolutamente todos os textos. Nada é mais irritante do que usar um tema ou plugin onde o autor codifica textos impossibilitando a tradução ou alteração de qualquer forma.
Como tornar os textos traduzíveis
O que fazemos com todos os textos é colocá-los dentro de uma das funções gettext do WordPress, que mais comumente são _e()ou __(). O primeiro é um sublinhado com “e” que é usado quando você deseja ecoar o texto ao mesmo tempo. O segundo é dois sublinhados e é usado quando você não deseja ecoá-lo, mas armazená-lo ou usá-lo em uma variável.
O WordPress tem mais funções gettext que atendem a propósitos mais específicos, por exemplo esc_html__(), _n(), _x()e muito mais. No entanto, não entraremos em detalhes neste tutorial.
As funções gettext recebem dois parâmetros; primeiro o próprio texto e, em segundo lugar, o identificador que você definiu em load_theme_textdomain. Neste caso é ‘ wptutorial‘.
Por exemplo, se você tiver algo assim:
echo 'Read more';Você precisará substituí-lo por:
_e('Read more', 'wptutorial');E da mesma forma para armazenar em uma variável;
$myvariable = 'Read more';Ele precisa ser escrito assim:
$myvariable = __('Read more', 'wptutorial');Agora precisamos encontrar todos os textos em nossos modelos! Se você seguiu este tutorial a um “T” não são muitos. Temos algumas strings index.phpe algumas em single.php.
Adicionando suporte de tradução em nosso tema
Vamos começar index.phpe localizar a mensagem “Sem postagens, desculpe” que adicionamos se o loop não contivesse nenhuma postagem. Envolvemos esse texto _e()porque ainda queremos ecoá-lo. Então é isso que obtemos:
Como você usou _e(), não deve ver nenhuma alteração quando clicar em atualizar na página inicial ou no arquivo. Mas sob o capô, este texto agora é traduzível!
Temos este mesmo texto em nosso single.phpe page.php. Atualize-os da mesma maneira que fizemos no index.php. Adicionamos mais alguns textos em single.php, então aqui está como fica depois de tornar todos os textos traduzíveis:
A partir de agora, todos os textos que adicionarmos ao nosso tema, certifique-se de envolvê-los dentro __()ou _e().
Arquivos de tradução
Existem duas maneiras de fornecer arquivos de tradução para o seu tema;
- Forneça um
.pot-arquivo - ou forneça um par de arquivos
.poe ..mo
O .pot-file é recomendado para um tema que você vende ou dá para outros usuários, pois com este arquivo é muito fácil gerar um arquivo de tradução para um novo idioma. No entanto, não é fácil (ou gratuito) criar um desses arquivos. Se você estiver familiarizado com WP-CLI (linha de comando WordPress) ou Grunt, você pode seguir as diretrizes na documentação do WordPress aqui. Se não, a outra alternativa pode ser para você.
Os arquivos .poe .motrabalham juntos. WordPress requer um .mopara tradução de textos, mas este arquivo não é legível. Portanto, temos o .poarquivo que é legível para nós. Com o software certo, ele gera o .moarquivo sempre que você faz alterações.
A desvantagem dos arquivos .poe .moé que você precisa gerar um par para cada idioma e, uma vez traduzido para um idioma, não há uma maneira fácil de esvaziar todas as traduções para criar outro novo idioma.
Você precisa de um programa para editar .pote .poarquivos. O mais comum é o PoEdit. O PoEdit é gratuito e funciona tanto para iOS quanto para Windows. Mas alguns recursos avançados (como gerar um .pot-file) infelizmente requerem uma versão paga. Usaremos a versão gratuita para fazer um .poarquivo para o nosso tema.
Baixe e instale o PoEdit para seguir o resto do tutorial.
Criando um arquivo .po para nosso tema com PoEdit
Fazer um arquivo de tradução para o inglês geralmente não faz sentido quando todos os textos do nosso tema são em inglês, mas para os propósitos deste tutorial, farei um arquivo de tradução para o inglês.
1 Abra o PoEdit e clique em Arquivo > Novo…
2 Você será solicitado a escolher um idioma. Escolha o idioma desejado, por exemplo, inglês.
3 Pressione Salvar (Ctrl+S). Localize a pasta do seu tema e entre na /lang/subpasta. (Se você não o criou na última etapa, crie-o agora). O nome do seu arquivo é crítico. Para temas, ele deve ser nomeado apenas com o código do seu idioma. Para o inglês americano seria en_US, para o norueguês é nb_NO. Pesquise no Google ou consulte esta visão geral para encontrar o código do seu idioma. Vamos nomeá-lo en_US.po.
4 No menu, clique em Catálogo > Propriedades…
5 Na primeira aba você pode preencher algumas informações como o nome do seu projeto (tema), ou mudar o idioma – mas não é necessário. Eu recomendo que você mantenha o charset em UTF-8, pois é isso que escrevemos para o WordPress.
6 Clique na guia Caminhos de fontes. Aqui você precisará definir quais pastas o arquivo deve procurar para textos traduzíveis. Os caminhos são relativos, e como já salvamos em uma subpasta do nosso tema, sabemos que precisa subir um diretório. Clique no botão + abaixo da caixa Caminhos e escolha Adicionar pastas. Escolha o diretório do seu tema. Isso deve adicionar um elemento de caminho “.” (subir uma pasta). Verifique novamente se “caminho base” se refere ao diretório do seu tema raiz.
7 Clique na próxima guia, “Fontes de palavras-chave”. Aqui você precisa informar ao PoEdit quais funções você usou para textos traduzíveis (por exemplo __, _e, esc_html_ee assim por diante). Clique no botão + para adicionar cada função e escreva-as sem “()”. Cabe a você se você deseja cobrir todas as suas bases e adicionar todas as funções gettext do WordPress, mas neste tutorial sabemos que usamos apenas duas. Então adicionamos dois elementos; __()e _e(). Adicione as funções sem nenhum parêntese.
8 Pressione OK.
9 Tudo o que resta é dizer ao PoEdit para verificar os caminhos fornecidos para funções usando __()e _e()(ou o que você forneceu). Você faz isso pressionando o botão “Atualizar a partir do código”. (A versão do Windows tem o texto no botão, mas a versão do iOS não – então para iOS você precisa apertar o botão que normalmente é o último na barra de ferramentas; um ícone de arquivo com um ícone “refazer” na parte superior. Clique o botão “Atualizar do código” e você deverá ver todos os textos listados com uma interface para tradução:
Agradável!
Arquivos de tradução gerados
Agora você pode usar o PoEdit para traduzir cada string, mas não faremos isso aqui, pois não adianta traduzir inglês para inglês. Lembre-se de clicar em Salvar para atualizar e gerar um .moarquivo, e toda vez que você adicionar outro texto ao seu tema, você precisa clicar no botão “Atualizar do código” novamente. Em seguida, as novas alterações em seus modelos aparecerão.
Se você verificar a /langsubpasta na pasta do diretório do tema, deverá ver dois arquivos; o .poarquivo que acabamos de criar e um .moarquivo com o mesmo nome, gerado por nós salvando no PoEdit.
Você pode fazer uma cópia do en_US.poarquivo e renomeá-lo para um código de idioma diferente. Mas lembre-se que o PoEdit não oferece uma maneira simples de limpar todas as strings traduzidas; você teria que limpar um por um. Esta é a razão pela qual isso é péssimo para usuários que desejam traduzir seu tema em um idioma diferente. Portanto, se você tiver a possibilidade de criar um .potarquivo, deve fazê-lo.
O WordPress procurará o arquivo de tradução dependendo do idioma definido no menu de administração Configurações> Idioma do site. Se você adicionou um idioma diferente do inglês, poderá testá-lo trocando o idioma do site e ver se sua tradução aparece!