Como Compilar Ficheiros .po para .mo (4 Métodos)

Passou uma tarde a aperfeiçoar uma tradução para alemão. Cada cadeia de texto no seu ficheiro de_DE.po está perfeita, os placeholders estão intactos, os plurais estão corretos. Carrega-o para o seu site, muda o idioma para alemão e... nada. A página continua em inglês. Verifica novamente o nome do ficheiro, a pasta, o text domain. Tudo parece correto. Então, por que razão o WordPress não mostra a sua tradução?

Em nove de dez casos, a resposta é a mesma: editou o .po, mas nunca o compilou para .mo. O WordPress não lê ficheiros .po em tempo de execução — ele carrega o binário .mo compilado. Se quer que as suas traduções apareçam de facto, precisa de compilar .po para .mo sempre que alterar o texto. O .po é a sua fonte editável; o .mo é o que o site serve.

Este guia explica por que razão esse passo de compilação existe e depois apresenta quatro formas fiáveis de o fazer: WP-CLI, o clássico comando msgfmt, Poedit, e uma ferramenta na nuvem que produz o .mo para si automaticamente. Também abordaremos a armadilha mais comum — esquecer-se de recompilar — e o formato .l10n.php mais recente que o WordPress agora prefere para maior velocidade.

Por que razão o WordPress carrega .mo e não .po?

O WordPress carrega ficheiros .mo porque são binários compilados otimizados para pesquisas rápidas, enquanto os ficheiros .po são texto simples criados para os humanos lerem e editarem. Analisar texto em cada carregamento de página seria lento; ler uma tabela hash binária pré-construída é quase instantâneo.

Um ficheiro .po é baseado em linhas e amigável para humanos. Cada entrada emparelha um msgid de origem com um msgstr traduzido, mais comentários que indicam a origem da cadeia de texto. Isso é ótimo para edição, mas terrível para o desempenho — o servidor teria de reanalisar o ficheiro de texto completo em cada pedido.

#: includes/cart.php:88
msgid "Your cart is empty"
msgstr "Ihr Warenkorb ist leer"

Um ficheiro .mo agrupa esses mesmos pares de cadeias de texto num formato binário com uma tabela de pesquisa interna, para que o WordPress possa saltar diretamente para uma tradução sem analisar o texto. A desvantagem é que o .mo é ilegível para humanos e deve ser regenerado sempre que o .po é alterado. Se a distinção entre .po e .mo ainda não for clara, o nosso explicador sobre ficheiros .po vs .mo vs .pot detalha cada formato e como eles se relacionam.

Quatro Formas de Compilar .po para .mo

Não existe uma única ferramenta "correta" — a melhor escolha depende de como já trabalha. Abaixo estão quatro métodos fiáveis, desde um comando de uma linha a um fluxo de trabalho em nuvem totalmente automatizado. Todos os quatro produzem o idêntico binário .mo que o WordPress carrega em tempo de execução.

Método 1: WP-CLI

A abordagem moderna mais limpa é o WP-CLI, que pode compilar uma pasta inteira de ficheiros .po num único comando. Se já gere o WordPress a partir da linha de comando, isto encaixa naturalmente no seu fluxo de trabalho.

# Compile every .po file in the languages folder to .mo
wp i18n make-mo languages/

# Compile into a specific destination directory
wp i18n make-mo languages/ build/languages/

O comando make-mo analisa o diretório de destino, compila cada .po que encontra e escreve um .mo correspondente ao lado (ou no destino que especificar). Ele lida com lotes de forma elegante, o que o torna ideal quando mantém muitos idiomas de uma só vez. É a ferramenta recomendada para qualquer projeto que já utilize o WP-CLI.

Método 2: msgfmt

A utilidade Gettext original para esta tarefa é o msgfmt, parte do pacote GNU gettext. Ele compila um único .po num único .mo e está disponível em praticamente todos os sistemas Linux e macOS.

# Compile one file
msgfmt my-plugin-de_DE.po -o my-plugin-de_DE.mo

# Add statistics about translated, fuzzy, and untranslated strings
msgfmt --statistics my-plugin-de_DE.po -o my-plugin-de_DE.mo

# Install it first if missing
#   macOS:  brew install gettext
#   Debian: sudo apt-get install gettext

A flag -o nomeia o ficheiro de saída. A flag --statistics é realmente útil — ela informa quantas cadeias de texto estão traduzidas, difusas ou ainda vazias, para que detete uma tradução incompleta antes de a lançar. Para scripts de um ficheiro de cada vez, o msgfmt é a escolha fiável e sem complicações.

Como o msgfmt é uma ferramenta de linha de comando simples, ele encaixa-se perfeitamente na automação. Pode envolvê-lo num loop de shell para compilar uma pasta inteira, ou ligá-lo a um pipeline de CI para que cada commit que toque num .po produza um .mo novo automaticamente. Um padrão comum é for f in languages/*.po; do msgfmt "$f" -o "${f%.po}.mo"; done, que compila todos os idiomas numa única passagem. A flag --check adiciona validação, assinalando incompatibilidades de cadeias de formato entre msgid e msgstr antes que cheguem à produção — uma salvaguarda barata contra os bugs de placeholders quebrados que corrompem silenciosamente layouts traduzidos.

Método 3: Poedit (Compila ao Guardar)

Se edita traduções num editor gráfico, o Poedit compila para si automaticamente. Sempre que guarda um ficheiro .po, o Poedit escreve o .mo correspondente logo ao lado — sem comando separado, sem passo extra.

Esta é uma das razões pelas quais o Poedit continua popular entre os tradutores que não se sentem confortáveis com a linha de comando. Abre o .po, digita as suas traduções, clica em guardar, e ambos os ficheiros são atualizados em conjunto. Pode confirmar o comportamento nas preferências do Poedit, onde a compilação automática de .mo ao guardar está ativada por padrão. O Poedit e ferramentas de desktop semelhantes são analisados em top 5 ferramentas gratuitas para editar e traduzir ficheiros PO no Mac e Windows.

A desvantagem de um editor de desktop é que a compilação só acontece quando um humano abre o ficheiro e o guarda. Isso é bom para um projeto individual, mas não escala para uma dúzia de idiomas ou para uma equipa que troca ficheiros constantemente. Se alguém editar um .po noutra ferramenta e o copiar para o repositório sem abrir o Poedit, o .mo nunca é atualizado. Para projetos maiores ou colaborativos, um método automatizado — linha de comando ou nuvem — elimina essa dependência de se lembrar de premir guardar.

Método 4: Uma Ferramenta na Nuvem Que Gera o .mo para Si

A quarta opção remove completamente o passo de compilação: use um serviço na nuvem que devolve o .mo compilado juntamente com o .po traduzido. Nunca executa um comando ou guarda um ficheiro duas vezes — faz o upload, e ficheiros finalizados, com o nome correto, são devolvidos.

O SimplePoTranslate funciona exatamente desta forma. Carrega um .po ou .pot, ele traduz as cadeias de texto com IA Ciente do Contexto, e devolve um único ZIP contendo o .po e o .mo gerados lado a lado — já compilados, já nomeados para corresponder ao seu text domain e locale. Não há um passo de compilação separado e nenhuma hipótese de se esquecer de um.

Também lida com os detalhes que quebram fluxos de trabalho manuais. A Syntax Locking congela placeholders como %s, %1$s e {name} mais tags HTML antes da tradução, para que as suas variáveis sobrevivam no .mo intactas. O suporte total a plurais Gettext significa que formas plurais complexas também compilam corretamente — um tópico que vale a pena entender profundamente, e que abordamos em compreender os plurais Gettext. E como funciona na nuvem, não há plugin para instalar e nenhuma ferramenta de construção para manter.

A Armadilha Mais Comum: Esqueceu-se de Recompilar

A maior razão para as traduções não aparecerem é editar o .po, mas esquecer-se de recompilar o .mo. O WordPress continua a carregar o binário antigo, então a sua nova redação nunca aparece — e não há mensagem de erro para lhe dizer porquê.

O modelo mental a fixar: o .po é o seu rascunho, o .mo é o que é enviado. Qualquer alteração ao .po é invisível para o WordPress até que regenere o .mo. Torne a recompilação um reflexo após cada edição, ou use uma ferramenta que compila automaticamente para que o passo nunca seja ignorado.

Esta armadilha é especialmente sorrateira nas transferências de staging para produção. Um desenvolvedor edita e recompila localmente, vê a tradução a funcionar, depois implementa apenas o .po e esquece o .mo — então a produção mantém silenciosamente o texto antigo. Sempre que mover ficheiros de tradução entre ambientes, mova o .po e o .mo recém-compilado juntos, ou compile como parte do seu passo de implementação para que o binário seja sempre reconstruído a partir da fonte atual.

Se as suas traduções ainda se recusarem a aparecer após a recompilação, o problema é geralmente uma incompatibilidade de nome, uma pasta errada ou uma camada de cache a reter o ficheiro antigo. A lista de verificação completa encontra-se em por que as suas traduções não estão a aparecer no WordPress.

Uma Nota sobre o Novo Formato .l10n.php

Versões recentes do WordPress introduziram um terceiro formato de tempo de execução: .l10n.php. Em vez de um binário .mo, as traduções são armazenadas como um array PHP simples que a cache de opcode PHP pode manter na memória, tornando as pesquisas ainda mais rápidas do que os .mo em sites movimentados.

<?php
return [
	'domain'  => 'my-plugin',
	'messages' => [ 'Your cart is empty' => 'Ihr Warenkorb ist leer' ],
];

O WordPress gera ficheiros .l10n.php automaticamente quando tem o .mo correspondente disponível, por isso não precisa de os construir manualmente. Por enquanto, compilar um .mo correto continua a ser a base — o formato de desempenho é derivado dele.

Conclusão

Para compilar .po para .mo de forma fiável, escolha o método que se adapta à sua forma de trabalhar: WP-CLI para lotes na linha de comando, msgfmt para ficheiros únicos com estatísticas, Poedit para compilação automática ao guardar, ou uma ferramenta na nuvem que constrói o .mo para si para que o passo nunca seja ignorado. Todos os quatro produzem o mesmo binário que o WordPress precisa em tempo de execução.

Seja qual for o caminho que escolher, lembre-se da regra de ouro: edite o .po, depois compile para .mo — sempre. Esse hábito evita o bug de tradução mais frustrante no WordPress, aquele em que tudo parece correto, mas o site permanece teimosamente em inglês.

Pronto para saltar o passo de compilação manual de vez? Experimente o SimplePoTranslate gratuitamente — não é necessário cartão de crédito. Carregue o seu .po e descarregue um pacote .po + .mo pronto para implementação no nível gratuito em minutos.