Por Que Suas Traduções Não Estão Aparecendo no WordPress (Guia de Solução de Problemas)

Não há nada mais frustrante no desenvolvimento WordPress do que a "Falha Silenciosa".

Você fez tudo certo. Você traduziu o arquivo .po. Você o compilou em um arquivo .mo. Você o carregou para o seu servidor via FTP. Você limpou seu cache.

Você atualiza a página, esperando ver espanhol, francês ou alemão. Em vez disso, você vê... inglês.

Sem mensagem de erro, sem tela branca — apenas texto teimoso e não traduzido. Antes de arrancar os cabelos, leia este guia. Aqui estão os 5 motivos mais comuns pelos quais as traduções falham ao carregar no WordPress e como corrigi-los.

1. Você Está Nomeando o Arquivo Errado

O WordPress é incrivelmente rigoroso com a nomenclatura de arquivos. Se você perder um caractere, ele não carregará o arquivo.

O formato padrão é: {domínio-texto}-{locale}.mo

• O Domínio de Texto (Text Domain): Este é o ID exclusivo do tema ou plugin (por exemplo, woocommerce, twentytwentyfour, my-custom-plugin).
• O Locale: O código de locale WP (por exemplo, es_ES para espanhol da Espanha, fr_FR para francês).

Erros Comuns:

• Nomear o arquivo apenas es_ES.mo (Isso só funciona para arquivos globais do núcleo do WordPress, não para plugins).
• Usar o traço errado: my_plugin_es_ES.mo (Sublinhado) em vez de my-plugin-es_ES.mo (Hífen).
• Adivinhar o domínio de texto. Você deve verificar o código do plugin (cabeçalho style.css ou função load_plugin_textdomain) para encontrar o slug exato.

2. Você Colocou o Arquivo na Pasta Errada

Onde você carrega o arquivo importa tanto quanto como você o nomeia. O WordPress procura em diretórios específicos em uma ordem específica.

• A Pasta do Sistema "Segura": /wp-content/languages/plugins/ ou /wp-content/languages/themes/.
  • Prós: Isso é seguro contra atualizações de plugins.
  • Contras: Você deve nomear o arquivo textdomain-locale.mo.
• A Pasta do Autor: /wp-content/plugins/plugin-name/languages/.
  • Prós: Fácil de encontrar.
  • Contras: PERIGO. Quando você atualiza o plugin, esta pasta é limpa. Suas traduções desaparecerão.

Melhor Prática: Coloque sempre seus arquivos .mo personalizados no diretório global /wp-content/languages/ para evitar perda de dados durante as atualizações.

3. O "Assassino Silencioso": Sintaxe Corrompida no Arquivo .po

Este é o problema mais difícil de depurar, e acontece frequentemente com ferramentas de tradução de IA genéricas.

O WordPress lê arquivos binários .mo, que são compilados a partir de arquivos de texto .po. Se o seu arquivo .po contém erros de sintaxe, o arquivo .mo pode ser gerado, mas estará "quebrado" internamente.

Como isso acontece? Se um tradutor (humano ou IA) atrapalhar a formatação Gettext, a string se torna inválida.

• Exemplo: Aspas de fechamento " faltando.
• Exemplo: Quebrar uma variável (mudar %s para % s).
• Exemplo: Atrapalhar a contagem msgid_plural.

Quando o WordPress encontra uma entrada quebrada no arquivo .mo, ele frequentemente a pula ou para de ler o arquivo completamente, voltando para o inglês original.

4. Você Esqueceu de Compilar (.po vs .mo)

O WordPress não pode ler arquivos .po diretamente. É um equívoco comum.

• .po = Legível por humanos (Portable Object).
• .mo = Legível por máquinas (Machine Object).

Se você carregar um arquivo my-theme-es_ES.po mas esquecer de gerar o arquivo .mo correspondente, nada acontecerá. Você deve compilá-lo.

5. Cache (O Suspeito Habitual)

Se você estiver usando plugins de cache (WP Rocket, LiteSpeed) ou cache do lado do servidor (Varnish, Redis), seu site pode estar servindo uma versão HTML em cache de antes de você carregar a tradução.

Correção: limpe todos os caches, incluindo o cache do navegador e o cache de objetos.

A Solução Definitiva: Arquivos Válidos desde o Início

Solucionar problemas de caminhos e nomes de arquivos é fácil. Solucionar sintaxe corrompida (Motivo #3) é um pesadelo.

Se você usar uma ferramenta que quebra suas variáveis de código ou corrompe a estrutura Gettext, passará horas se perguntando por que o arquivo não está funcionando, sem perceber que o arquivo em si está "envenenado".

É por isso que construímos SimplePoTranslate.

• Bloqueo de Sintaxe: Garantimos que cada string seja sintaticamente válida antes de você baixá-la. Bloqueamos variáveis como %s para que não possam ser quebradas.
• Formatação Perfeita: Geramos arquivos .po limpos e padrão que compilam em arquivos .mo funcionais 100% do tempo.
• Sem Plugins Necessários: Você baixa o arquivo, e sabe que funciona. Você só precisa carregá-lo na pasta certa.

Pare de adivinhar por que suas traduções são invisíveis. Comece com um arquivo em que você pode confiar.

Pronto para traduzir sem dor de cabeça? Comece gratuitamente em SimplePoTranslate.com