Como Traduzir um Plugin do WordPress (Passo a Passo)

Você encontrou o plugin perfeito do WordPress para o seu projeto. Ele faz exatamente o que você precisa, as avaliações são excelentes, e então você o ativa e percebe que cada botão, rótulo e mensagem de erro está em inglês. Seus visitantes alemães, franceses ou japoneses estão prestes a se deparar com uma parede de texto que não conseguem ler. A boa notícia é que a maioria dos plugins bem construídos estão prontos para tradução, o que significa que o desenvolvedor envolveu suas strings em funções Gettext especificamente para que pessoas como você possam traduzi-las. O desafio é saber onde os arquivos residem, como nomear sua tradução e onde colocá-la para que a próxima atualização do plugin não apague seu trabalho. Este guia mostra como traduzir um plugin do WordPress do início ao fim: encontrando o domínio de texto e a pasta de idiomas, obtendo ou gerando o template .pot, construindo arquivos .po e .mo com nomes corretos e colocando-os onde o WordPress irá carregá-los de forma confiável. Também abordaremos o único tipo de plugin que esta abordagem não consegue traduzir totalmente, para que você não perca horas lutando contra um caso impossível.

Como Encontrar os Arquivos de Tradução de um Plugin?

Antes de traduzir qualquer coisa, você precisa de duas informações do plugin: seu domínio de texto e sua pasta de idiomas. O domínio de texto é a string única que o plugin usa para identificar suas próprias traduções, e a pasta de idiomas é onde o template de origem reside.

Localizando a Pasta de Idiomas e o Domínio de Texto

Abra o diretório do plugin em wp-content/plugins/your-plugin/ e procure por uma subpasta /languages. Lá dentro, você geralmente encontrará um arquivo .pot, o template vazio contendo todas as strings traduzíveis. Para confirmar o domínio de texto, abra o arquivo PHP principal do plugin e observe seu bloco de cabeçalho:

/**
 * Plugin Name: Awesome Plugin
 * Text Domain: awesome-plugin
 * Domain Path: /languages
 */

Aqui o domínio de texto é awesome-plugin. Este valor é crítico, porque seus arquivos de tradução devem incluí-lo em seus nomes ou o WordPress nunca os associará ao plugin. Você também o verá em cada chamada de string em todo o código:

echo __( 'Settings saved successfully.', 'awesome-plugin' );

Esse segundo argumento, awesome-plugin, é novamente o domínio de texto. Toda string que o usa pode ser traduzida pelo seu catálogo. Se uma string na interface do plugin estiver faltando este wrapper, por exemplo, um desenvolvedor que codificou echo 'Save' sem __(), então essa string não é traduzível de forma alguma, e nenhum arquivo .po pode alcançá-la. A maioria dos plugins respeitáveis envolve tudo corretamente, mas se você notar uma ou duas strings teimosas que se recusam a traduzir, um wrapper Gettext ausente na fonte é um provável culpado. Uma maneira rápida de avaliar se um plugin está realmente pronto para tradução é verificar sua listagem no diretório WordPress.org, que mostra uma porcentagem de tradução e links para um template /languages. Um plugin com um projeto de tradução ativo é muito mais propenso a ter strings limpas e totalmente envolvidas do que um abandonado.

E Se o Plugin Não Tiver um Arquivo POT?

Alguns plugins são entregues sem um template .pot. Se a pasta /languages estiver vazia ou faltando, você precisará gerar o template por conta própria, escaneando o código-fonte em busca de strings traduzíveis. A ferramenta padrão para isso é o WP-CLI, que extrai cada chamada Gettext para um novo .pot.

wp i18n make-pot wp-content/plugins/awesome-plugin \
  wp-content/plugins/awesome-plugin/languages/awesome-plugin.pot

Este comando percorre os arquivos PHP e JavaScript do plugin, encontra cada __(), _e(), _n() e chamadas relacionadas, e escreve um template completo. Se você preferir uma rota gráfica, o Poedit Pro pode escanear o código-fonte da mesma forma. De qualquer maneira, o resultado é um .pot contendo todas as strings de origem com traduções vazias, pronto para ser transformado em um arquivo de idioma real. Gerar seu próprio template tem um benefício oculto: ele captura strings que o desenvolvedor original pode ter esquecido de incluir em um .pot enviado. Plugins evoluem rapidamente, e um template que veio com a versão 2.1 pode estar faltando strings adicionadas na 2.4. Regenerar a partir da fonte atual garante que seu catálogo reflita o que o plugin realmente exibe hoje, não o que ele exibia duas versões atrás. Se você mantém traduções para um plugin ao longo do tempo, executar make-pot novamente após cada atualização importante é um hábito confiável.

Criando os Arquivos PO e MO Com o Nome Correto

O erro mais comum ao traduzir um plugin é o nome do arquivo. O WordPress encontra as traduções de plugins combinando um padrão muito específico, e um caractere errado significa que sua tradução será ignorada completamente.

A Fórmula do Nome do Arquivo

Para traduções de plugins, o padrão é text-domain-locale. Assim, para o domínio de texto awesome-plugin traduzido para o alemão, os arquivos devem ser nomeados:

awesome-plugin-de_DE.po
awesome-plugin-de_DE.mo

O código do locale é o código de idioma do site WordPress: de_DE para alemão, fr_FR para francês, es_ES para espanhol, pt_BR para português do Brasil. Erre o locale e o WordPress ignorará seu arquivo silenciosamente. Você os cria a partir do template .pot em um editor como o Poedit, que compila o .mo binário automaticamente quando você salva. Se você é novo nesse editor, o guia completo do Poedit orienta na criação de uma tradução a partir de um template passo a passo.

Onde Colocar os Arquivos Para Que As Atualizações Não os Apaguem

Existem dois locais possíveis, e escolher o correto é importante.

# RISKY: inside the plugin — wiped on every plugin update
wp-content/plugins/awesome-plugin/languages/awesome-plugin-de_DE.mo

# SAFE: the global languages override folder — survives updates
wp-content/languages/plugins/awesome-plugin-de_DE.mo

Sempre use wp-content/languages/plugins/. O WordPress verifica este diretório de substituição primeiro, e como ele fica fora da pasta do plugin, a atualização do plugin nunca afeta suas traduções. Arquivos colocados dentro da própria pasta do plugin são sobrescritos no momento em que uma nova versão é instalada. Esse comportamento de substituição é uma das características mais úteis e menos conhecidas da localização do WordPress. Significa que você pode enviar traduções personalizadas ou corrigidas para qualquer plugin de terceiros sem nunca bifurcá-lo, e suas alterações estarão completamente seguras contra atualizações. Se você gerencia vários sites de clientes executando o mesmo plugin, pode até manter um único conjunto de arquivos .mo de substituição e implantá-los em todos eles, sabendo que cada site os pegará automaticamente, desde que o locale corresponda.

Como o WordPress Carrega Sua Tradução

Um plugin pronto para tradução informa ao WordPress para carregar seu catálogo chamando load_plugin_textdomain() durante a inicialização:

add_action( 'init', function() {
    load_plugin_textdomain(
        'awesome-plugin',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages'
    );
} );

Para a maioria dos plugins modernos no WordPress 4.6 e posterior, você não precisa mexer nisso. O WordPress carrega automaticamente as traduções de wp-content/languages/plugins/, desde que o nome do seu arquivo e o locale do site correspondam. Se sua tradução final ainda não aparecer, a causa é quase sempre uma incompatibilidade de nome de arquivo, um .mo desatualizado ou um idioma do site configurado para o locale errado. Nosso guia de solução de problemas para traduções que não aparecem aborda cada um desses pontos de falha.

Plugins Que Armazenam Strings no Banco de Dados

Aqui está a limitação importante. A abordagem Gettext traduz apenas strings que residem no código do plugin. Alguns plugins, especialmente construtores de formulários, construtores de páginas e extensões de e-commerce, permitem que você crie conteúdo (rótulos de formulário, atributos de produto, mensagens personalizadas) que é salvo no banco de dados do WordPress. Essas strings são dados gerados pelo usuário, não fazem parte do .pot, então um arquivo .po não pode alcançá-las. Para conteúdo de banco de dados, você precisa de um plugin multilíngue como WPML ou Polylang, ou do próprio recurso de tradução de strings do plugin. Sempre teste se uma determinada string reside no código ou no banco de dados antes de assumir que um arquivo .po pode corrigi-la. Um teste simples informa com qual tipo de string você está lidando. Se o texto é algo que você digitou em um campo de configurações, um rótulo de formulário que você criou, uma mensagem de agradecimento personalizada, um nome de produto, é conteúdo do banco de dados e um .po não pode tocá-lo. Se o texto faz parte da interface embutida do plugin, rótulos de botões, erros de validação, avisos de administração que vêm com o próprio plugin, ele reside no código e um arquivo .po é a ferramenta certa. Traçar essa linha cedo economiza horas de frustração, porque nenhuma quantidade de edição perfeita de .po jamais traduzirá uma string que o plugin puxa do banco de dados em tempo de execução.

Traduzindo em Escala Sem o Trabalho Manual

Traduzir um plugin para um idioma manualmente é gerenciável. Traduzi-lo para dez idiomas, ou traduzir um conjunto completo de plugins para um site de cliente, transforma-se em dias de trabalho repetitivo, e cada edição manual corre o risco de estragar um placeholder como %s ou %1$s e quebrar a saída. É aqui que um fluxo de trabalho na nuvem muda a equação. Faça upload do .po ou .pot do plugin para o SimplePoTranslate, escolha seus idiomas de destino, e a IA sensível ao contexto traduz todo o catálogo enquanto o Bloqueio de Sintaxe congela cada placeholder, tag HTML e token de código para que nada se quebre. O Processamento Inteligente em Lotes lida com catálogos grandes em uma única passagem, e você baixa um ZIP contendo .po, .mo, .json, .php e .xliff juntos, formatados corretamente e prontos para serem inseridos em wp-content/languages/plugins/. Ele funciona inteiramente na nuvem, então não há instalação de desktop nem inchaço no seu site. Note que traduzir um plugin difere de traduzir um tema, que usa uma convenção de pasta e função de carregamento ligeiramente diferentes. Se um tema é seu objetivo, siga nosso guia dedicado sobre como localizar qualquer tema do WordPress, mesmo que você não seja um desenvolvedor em vez disso. Use o caminho manual quando você tem um plugin e um idioma. Use a nuvem quando precisar de muitos idiomas, rapidamente, sem sacrificar a segurança dos placeholders.

Pronto para traduzir seu plugin do WordPress para todos os idiomas que seu público fala sem quebrar uma única variável? Experimente o SimplePoTranslate gratuitamente — não é necessário cartão de crédito. O nível gratuito permite que você traduza seu primeiro arquivo .po de plugin em minutos, com Bloqueio de Sintaxe em cada string.