.po vs .mo vs .pot: Arquivos de Tradução do WordPress Explicados

Você abre a pasta languages de um tema WordPress e encontra três arquivos que parecem quase idênticos: twentytwentyfour.pot, twentytwentyfour-de_DE.po e twentytwentyfour-de_DE.mo. Mesmo tema, mesma língua, três extensões diferentes. Qual deles você edita? Qual deles o WordPress realmente carrega? E por que editar o errado faz suas traduções desaparecerem silenciosamente?

Se você já se perguntou qual arquivo importa no debate arquivo .po vs .mo, você não está sozinho. Essas três extensões são a espinha dorsal de todo site WordPress traduzido, mas a diferença entre elas confunde tanto iniciantes quanto desenvolvedores experientes. Edite o arquivo errado e seus visitantes alemães ainda verão inglês. Edite o certo, mas pule uma etapa e nada mudará também.

Este guia explica exatamente o que são os arquivos .pot, .po e .mo, como eles se relacionam dentro do fluxo de trabalho do GNU Gettext, onde eles residem no WordPress e por que você nunca deve abrir um arquivo .mo em um editor de texto. Ao final, você saberá qual arquivo tocar e qual deixar em paz.

O Que São Arquivos .pot, .po e .mo?

Em resumo: um arquivo .pot é o modelo em branco, um arquivo .po é sua tradução editável e um arquivo .mo é o binário compilado que o WordPress lê em tempo de execução. Eles formam uma cadeia, e cada elo tem exatamente uma função.

Esses três formatos vêm todos do GNU Gettext, o sistema de localização no qual WordPress, Drupal e milhares de projetos PHP e C dependem. O Gettext separa as strings de origem que um desenvolvedor escreve das traduções que um tradutor fornece, para que a mesma base de código possa falar dezenas de idiomas sem tocar em uma única linha de PHP.

Pense nisso como um cartão de receita. O .pot é o cartão em branco com espaços para ingredientes, mas sem quantidades. O .po é o cartão preenchido para um prato específico. O .mo é a cópia plastificada e escaneável por máquina que a cozinha realmente usa durante o serviço. Você escreve no cartão de papel; você nunca rabisca no plastificado.

O Arquivo .pot: O Modelo Mestre

Um arquivo .pot (Portable Object Template) contém todas as strings traduzíveis em um tema ou plugin, com as traduções deixadas em branco. É a lista mestra que os desenvolvedores fornecem para que os tradutores saibam exatamente o que precisa ser traduzido. As linhas msgstr estão em branco porque nenhuma linguagem foi escolhida ainda.

#: includes/checkout.php:42
msgid "Add to Cart"
msgstr ""

#: includes/account.php:108
msgid "Your order has been shipped to %s"
msgstr ""

Observe o msgstr "" vazio. Um .pot é um modelo, não uma tradução. Você o copia uma vez por idioma e preenche os espaços em branco. Raramente você edita um .pot manualmente; ele é regenerado a partir do código-fonte sempre que as strings mudam.

O Arquivo .po: Sua Tradução Editável por Humanos

Um arquivo .po (Portable Object) é uma cópia do .pot com as linhas msgstr preenchidas para um idioma. Este é o arquivo que tradutores e desenvolvedores realmente editam. É texto simples, legível por humanos e amigável para controle de versão.

#: includes/checkout.php:42
msgid "Add to Cart"
msgstr "In den Warenkorb"

#: includes/account.php:108
msgid "Your order has been shipped to %s"
msgstr "Ihre Bestellung wurde an %s versandt"

O msgid é a string original em inglês e nunca deve mudar. O msgstr é sua tradução. O %s é um placeholder que deve permanecer intacto na tradução — removê-lo ou reordená-lo é a causa mais comum de layouts quebrados, o que abordamos em detalhes em como traduzir arquivos PO sem quebrar variáveis de código.

O Arquivo .mo: O Binário Compilado

Um arquivo .mo (Machine Object) é a versão compilada e binária do seu .po. O WordPress não consegue ler arquivos .po de forma eficiente em tempo de execução, então ele carrega o .mo pré-compilado. Abrir um .mo em um editor de texto mostra bytes ilegíveis — ele é feito para máquinas, não para pessoas.

Quando o WordPress chama load_textdomain() ou load_theme_textdomain(), ele procura um arquivo .mo, analisa sua tabela hash binária e troca cada msgid pela msgstr correspondente em tempo real. Este formato binário torna as pesquisas rápidas, mesmo em sites com milhares de strings.

Como os Três Arquivos se Relacionam no Fluxo de Trabalho do Gettext?

Eles formam um pipeline unidirecional: o código-fonte se torna um .pot, o .pot se torna um .po por idioma, e cada .po compila em um .mo. As traduções sempre fluem 'ladeira abaixo'.

Aqui está o ciclo de vida completo em ordem:

1. Um desenvolvedor envolve strings voltadas para o usuário em funções Gettext como __() e _e() dentro do código-fonte PHP.
2. Uma ferramenta de varredura lê o código-fonte e gera o modelo .pot contendo todas as strings envolvidas.
3. Um tradutor copia o .pot para um .po específico do idioma (por exemplo, de_DE.po) e preenche cada msgstr.
4. O .po finalizado é compilado em um .mo binário.
5. O WordPress carrega o .mo em tempo de execução e exibe o site traduzido.

Quando o desenvolvedor adiciona novas strings mais tarde, o .pot é regenerado, as novas entradas são mescladas em cada .po existente (mantendo as traduções antigas), o tradutor preenche as lacunas e o .po é recompilado para .mo. O ciclo se repete durante a vida útil do projeto.

A conclusão crucial: você edita o .po, depois compila para .mo. Você nunca edita o .mo diretamente, e nunca traduz dentro do .pot. Se você quiser uma visão mais aprofundada de ponta a ponta, o guia definitivo para localização no WordPress percorre todo o pipeline com exemplos.

Convenções de Nomenclatura e Onde os Arquivos Residem

O WordPress é rigoroso com os nomes dos arquivos. Erre na nomenclatura e seu .mo perfeitamente traduzido será simplesmente ignorado, porque o WordPress procura uma correspondência exata baseada no domínio de texto e no idioma.

O padrão de nomenclatura para traduções de temas e plugins é:

# Pattern: textdomain-locale.po / .mo
twentytwentyfour-de_DE.po      # German (Germany) translation
twentytwentyfour-de_DE.mo      # compiled binary WordPress loads
twentytwentyfour-fr_FR.po      # French (France)
twentytwentyfour.pot           # template, no locale suffix

O textdomain corresponde à string passada como segundo argumento para funções Gettext como __( 'Add to Cart', 'twentytwentyfour' ). O locale é um código de idioma do WordPress, como de_DE, fr_FR ou pt_BR. O modelo .pot não possui sufixo de idioma porque é neutro em relação ao idioma.

A localização importa tanto quanto a nomenclatura. O WordPress pesquisa alguns caminhos previsíveis:

• Traduções de temas são fornecidas na própria pasta wp-content/themes/your-theme/languages/ do tema.
• Traduções de plugins são fornecidas em wp-content/plugins/your-plugin/languages/.
• Traduções de translate.wordpress.org e substituições do usuário são armazenadas nos diretórios globais wp-content/languages/themes/ e wp-content/languages/plugins/, que têm prioridade e sobrevivem a atualizações.

Coloque um de_DE.mo com o nome correto na pasta certa e os visitantes alemães verão o alemão. Coloque-o uma pasta muito profunda, ou digite errado o domínio de texto, e o WordPress silenciosamente voltará para o inglês sem mensagem de erro. Se suas traduções não estão aparecendo, uma incompatibilidade de nome ou caminho é o culpado usual, e o guia de solução de problemas para traduções ausentes cobre todas as causas comuns.

Por Que Você Nunca Deve Editar um Arquivo .mo Diretamente

Como um .mo é um binário compilado, não há uma maneira segura de editá-lo manualmente — e qualquer alteração que você force será sobrescrita na próxima vez que o .po for recompilado. O .po é a fonte da verdade; o .mo é um artefato de compilação descartável.

Esta única regra explica uma grande parte dos chamados de suporte "minha tradução mudou, mas o site não atualizou". Alguém ajusta uma string, salva o .po e esquece de recompilar o .mo. O WordPress continua carregando o binário antigo, então a nova redação nunca aparece. A solução é sempre: edite o .po, recompile para .mo, recarregue.

Há uma segunda razão pela qual a regra importa: arquivos .mo não são amigáveis para 'diff' no controle de versão. Como são binários, uma pequena mudança na redação produz um 'blob' opaco no seu histórico Git que nenhum revisor pode ler. Manter o .po como a fonte da verdade rastreada e tratar o .mo como um artefato gerado mantém seu repositório revisável e suas traduções auditáveis.

Fazer isso manualmente em dezenas de idiomas é tedioso e propenso a erros. É aqui que um fluxo de trabalho em nuvem economiza tempo real. Ferramentas como o SimplePoTranslate traduzem suas strings .po e retornam um único ZIP contendo os .po e .mo correspondentes juntos — já compilados, nomeados corretamente, prontos para serem colocados em wp-content/languages/. Não há nada para compilar manualmente e nenhuma chance de um .mo desatualizado.

Ele também aplica o Bloqueio de Sintaxe, que congela cada placeholder como %s, %1$s e {name}, além das tags HTML, antes da tradução. Suas variáveis sobrevivem intactas, então você nunca envia um .mo que quebre um layout. E como ele roda inteiramente na nuvem, não há plugin extra sobrecarregando seu site — você faz o upload de um arquivo e baixa as traduções finalizadas e compiladas.

Unindo Tudo

Uma vez que a distinção arquivo .po vs .mo se torna clara, todo o sistema de tradução do WordPress deixa de parecer misterioso. O .pot é o modelo do desenvolvedor, o .po é a cópia de trabalho editável do tradutor, e o .mo é o binário compilado que o WordPress realmente serve aos visitantes. As traduções fluem em uma direção — modelo para .po para .mo — e você só edita manualmente o do meio.

Lembre-se das três regras que previnem noventa por cento das dores de cabeça de tradução: nunca traduza dentro de um .pot, sempre recompile o .mo depois de editar um .po, e combine exatamente a nomenclatura textdomain-locale. Siga-as e suas strings traduzidas aparecerão sempre.

Pronto para parar de lutar com a compilação e nomeação manual de arquivos de tradução? Experimente o SimplePoTranslate gratuitamente — não é necessário cartão de crédito. Faça upload do seu .po ou .pot e receba um pacote .po + .mo pronto para usar no nível gratuito em minutos.