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

Não há nada mais frustrante no desenvolvimento do 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 o cache.

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

Nenhuma mensagem de erro, nenhuma 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 não são carregadas no WordPress e como corrigi-los.

1. Você Está Nomeando o Arquivo Errado

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

O formato padrão é: {text-domain}-{locale}.mo

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

Erros Comuns:

• Nomear o arquivo apenas como 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 é tão importante quanto o nome que você dá a ele. O WordPress procura em diretórios específicos em uma ordem específica.

• A Pasta de Sistema "Segura": /wp-content/languages/plugins/ ou /wp-content/languages/themes/.
  • Prós: Isso está seguro contra atualizações de plugins.
  • Contras: Você deve nomear o arquivo como 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 é completamente limpa. Suas traduções desaparecerão.

Melhores Práticas: Sempre coloque seus arquivos .mo personalizados no diretório global /wp-content/languages/ para evitar a 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 genéricas de tradução de IA.

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

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

• Exemplo: Falta uma aspa de fechamento ".
• Exemplo: Quebrar uma variável (alterar %s para % s).
• Exemplo: Bagunçar a contagem de msgid_plural.

Quando o WordPress encontra uma entrada quebrada no arquivo .mo, ele geralmente a ignora ou para de ler o arquivo completamente, revertendo 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 (Objeto Portátil).
• .mo = Legível por máquinas (Objeto de Máquina).

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

5. Caching (O Suspeito Usual)

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ê enviar a tradução.

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

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

A solução de problemas de caminhos e nomes de arquivos é fácil. A solução de problemas de sintaxe corrompida (Motivo nº 3) é um pesadelo.

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

É por isso que construímos o SimplePoTranslate.

• Bloqueio 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 são compilados em arquivos .mo funcionando 100% das vezes.
• Nenhum Plugin Necessário: Você baixa o arquivo e sabe que ele funciona. Você só precisa enviá-lo para a pasta certa.
• Plugin WordPress: Prefere pular o upload manual completamente? Nosso plugin SimplePoTranslate WordPress oficial detecta automaticamente seus arquivos .pot de tema e plugin, os traduz na nuvem e implanta o resultado no diretório correto com o nome de arquivo correto. Chega de arquivos com nomes errados, chega de caminhos de pasta errados — os dois motivos mais comuns pelos quais as traduções não aparecem.

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

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