Como Corrigir Traduções Imprecisas em Arquivos .po do WordPress

Você traduziu todas as strings. Você salvou o arquivo, enviou o .mo e atualizou seu site. E, no entanto, algumas etiquetas ainda estão teimosamente em inglês. Você abre o arquivo .po, encontra a string, e lá está ela, perfeitamente traduzida. Então, por que o WordPress a está ignorando?

A resposta é quase sempre um pequeno sinalizador escondido acima da entrada: #, fuzzy. Uma tradução imprecisa (fuzzy) é a forma do gettext dizer "esta tradução pode estar errada, então não confie nela ainda." E, crucialmente, o WordPress se recusa a exibir strings fuzzy no site ativo, voltando para o inglês original. Esta é uma das causas mais incompreendidas do problema "minha tradução não está aparecendo".

Este guia explica exatamente o que significa o sinalizador de tradução imprecisa (fuzzy), por que ele continua aparecendo em seus catálogos e como encontrar e remover strings fuzzy no Poedit, na linha de comando e em grande escala em todo um backlog. Assim que você entender o mecanismo, o mistério das traduções ausentes desaparecerá.

O Que o Sinalizador Fuzzy Realmente Significa?

O sinalizador fuzzy é um marcador que o gettext adiciona a uma entrada de tradução para indicar que a tradução é incerta e precisa de revisão humana. No arquivo .po bruto, ele aparece como um comentário especial diretamente acima da string.

#: includes/cart.php:88
#, fuzzy
msgid "Add to cart"
msgstr "Im Warenkorb"

Essa linha #, fuzzy informa a todas as ferramentas compatíveis com gettext, incluindo o WordPress, que o msgstr abaixo dela é provisório. A tradução existe, mas o gettext não a considera confirmada.

Por Que o WordPress Ignora Strings Fuzzy

Aqui está o comportamento que pega todos de surpresa. Quando o WordPress compila ou lê um arquivo .mo, ele trata as entradas fuzzy como não traduzidas. A string está tecnicamente presente no arquivo, mas o WordPress a ignora deliberadamente e mostra o msgid original.

Assim, da sua perspectiva, a tradução está "feita", está lá no arquivo. Mas da perspectiva do WordPress, essa string não tem uma tradução confiável, então ele renderiza a fonte em inglês. É precisamente por isso que um catálogo com aparência finalizada ainda pode exibir texto não traduzido no frontend.

Este design é intencional e, com justiça, sensato. O objetivo principal do sinalizador fuzzy é evitar que traduções não verificadas e potencialmente erradas entrem em produção silenciosamente. Imagine uma string que originalmente dizia "Delete account" e foi posteriormente alterada para "Deactivate account". Se o gettext mantivesse cegamente a tradução antiga, seus usuários poderiam ver um botão rotulado "Delete account" que na verdade apenas desativa, uma incompatibilidade perigosa. Ao ocultar strings fuzzy, o gettext força um humano a confirmar se a tradução ainda corresponde ao novo significado antes que ela chegue a qualquer pessoa. O sinalizador é um mecanismo de segurança, não um bug.

Por Que os Sinalizadores Fuzzy Continuam Aparecendo?

Os sinalizadores fuzzy não são aleatórios. Eles são gerados automaticamente por ferramentas gettext em duas situações principais, e entender ambas lhe dirá como preveni-los.

A String Original Mudou

A causa mais comum é uma atualização da fonte. Imagine que o desenvolvedor muda uma string na próxima versão do plugin de "Add to cart" para "Add to basket". Quando você mescla o novo template em sua tradução existente, o gettext percebe que a fonte não corresponde mais ao que você traduziu originalmente. Em vez de descartar sua tradução antiga, ele a mantém, mas a marca como fuzzy, essencialmente dizendo: "o inglês mudou, então, por favor, verifique novamente se sua tradução ainda se encaixa."

Correspondência Automática por Memória de Tradução e msgmerge

A segunda causa é a correspondência fuzzy durante uma mesclagem. A ferramenta msgmerge atualiza um arquivo de tradução antigo em relação a um novo template, e quando encontra uma string de origem que é semelhante, mas não idêntica a uma anterior, ela copia a tradução antiga e a sinaliza como fuzzy.

# Merge a new template into an existing translation.
# Similar-but-changed strings get marked #, fuzzy automatically.
msgmerge --update awesome-plugin-de_DE.po awesome-plugin.pot

A Memória de Tradução em editores de desktop se comporta da mesma forma: quando preenche automaticamente uma sugestão de uma correspondência próxima, ela marca o resultado como fuzzy para que você se lembre de verificá-lo. Em ambos os casos, o sinalizador está cumprindo sua função. O problema é apenas que as entradas fuzzy ficam sem revisão, e o WordPress as oculta silenciosamente.

Há uma terceira fonte, mais sorrateira, que vale a pena conhecer: ferramentas de copiar e colar e de importação em massa. Algumas plataformas de tradução e scripts de importação marcam cada entrada como fuzzy por padrão, como uma medida conservadora, esperando que um humano confirme cada uma delas depois. Se você importar um catálogo de outro sistema e descobrir que todas as strings estão subitamente fuzzy, geralmente é por isso. As traduções podem estar perfeitamente bem, mas até que os sinalizadores sejam removidos, nenhuma delas aparecerá em seu site. Conhecer a origem dos sinalizadores informa se você realmente precisa revisar cada entrada ou se uma remoção em massa confiante é segura.

Como Encontrar e Corrigir Strings Fuzzy?

Remover strings fuzzy significa revisar cada uma delas e, uma vez confirmada a tradução correta, remover o sinalizador. Existem três maneiras práticas de fazer isso, dependendo do tamanho da tarefa.

Corrigindo Strings Fuzzy no Poedit

O Poedit facilita isso. Abra o arquivo .po e use os controles de busca e filtro para mostrar apenas as entradas fuzzy; elas são codificadas por cores (geralmente laranja) para se destacarem imediatamente. Clique em cada uma, confirme ou corrija a tradução e, em seguida, desative o estado fuzzy com o atalho de teclado (Editar e depois "A tradução está imprecisa", ou o atalho mostrado no menu). Ao salvar, o Poedit recompila um .mo limpo e as strings agora confirmadas serão exibidas em seu site. Se você é novo nesse editor, o guia completo do Poedit aborda o fluxo de trabalho de filtro e revisão em detalhes.

Corrigindo Strings Fuzzy na Linha de Comando

Para automação ou catálogos grandes, a linha de comando é mais rápida. Você pode contar as entradas fuzzy e, depois de verificá-las em massa, remover os sinalizadores para que o WordPress as carregue.

# Count how many fuzzy strings remain
msgattrib --only-fuzzy --no-obsolete awesome-plugin-de_DE.po | grep -c "msgid"

# Clear all fuzzy flags (only after you trust the translations)
msgattrib --clear-fuzzy --empty awesome-plugin-de_DE.po \
  --output-file=awesome-plugin-de_DE.po

Tenha cuidado com a remoção em massa. Remover sinalizadores fuzzy sem revisar as traduções anula o propósito do sinalizador e pode enviar texto genuinamente errado aos seus usuários. Use a abordagem de linha de comando quando você confia na origem das traduções e a rota manual do Poedit quando não confia.

Um meio-termo seguro é exportar as strings fuzzy para um arquivo separado, revisar apenas elas e depois mesclá-las de volta. Isso mantém suas traduções confirmadas intocadas enquanto você se concentra apenas nas entradas que realmente precisam de atenção.

# Extract only the fuzzy entries for focused review
msgattrib --only-fuzzy --no-obsolete awesome-plugin-de_DE.po \
  --output-file=fuzzy-only.po

Revisar cinquenta strings isoladas é muito menos propenso a erros do que rolar um catálogo de mil linhas procurando por linhas laranja, e lhe dá um registro limpo do que exatamente mudou na última atualização.

Após remover os sinalizadores, sempre salve ou recompile novamente o arquivo .mo. O estado fuzzy reside no .po, mas o WordPress lê o .mo binário, então, até que você o regenere, seu frontend continuará mostrando inglês, mesmo que o .po pareça limpo. O Poedit recompila automaticamente ao salvar; na linha de comando você executa msgfmt awesome-plugin-de_DE.po -o awesome-plugin-de_DE.mo. Esquecer este passo final de compilação é uma das razões mais comuns para um catálogo recém-desfuzificado ainda não aparecer; a tradução é confirmada no arquivo de origem, mas o binário que o site realmente carrega está desatualizado.

Note que as entradas fuzzy frequentemente aparecem junto com strings plurais, onde um msgid_plural alterado pode marcar todo o bloco plural como fuzzy. Se seu backlog fuzzy for pesado em contagens e quantidades, nosso guia sobre Plurais do Gettext e pluralização complexa explica por que essas entradas são especialmente frágeis durante as mesclagens.

Removendo o Backlog Fuzzy em Escala

Uma única string fuzzy é uma correção de trinta segundos. Um catálogo com quatrocentas strings fuzzy após uma grande atualização de plugin é um problema diferente, e em uma dúzia de idiomas se torna um verdadeiro gargalo. A tentação de remover em massa os sinalizadores sem revisão é exatamente como traduções quebradas chegam à produção.

Uma solução mais limpa é retraduzir as entradas fuzzy do zero, em vez de apenas carimbar correspondências antigas. Ao processar um catálogo através do SimplePoTranslate, a IA com reconhecimento de contexto produz uma tradução atual e confirmada para cada string alterada, então você não está apenas removendo um sinalizador de aviso, mas substituindo correspondências incertas por traduções reais. O Bloqueio de Sintaxe mantém cada %s, %1$s, {count} e tag HTML intactos durante o processo, e o Processamento Inteligente em Lotes processa grandes catálogos pós-atualização de uma só vez. Você recebe de volta um ZIP limpo com .po, .mo, .json, .php e .xliff, sem backlog fuzzy remanescente, pronto para ser implantado da nuvem.

Vale a pena distinguir isso da questão mais ampla de por que as traduções não aparecem de forma alguma. Os sinalizadores fuzzy são uma causa específica, mas arquivos .mo ausentes, nomes de arquivo incorretos e incompatibilidades de localidade causam o mesmo sintoma. Para a lista de verificação diagnóstica completa, consulte nosso guia de solução de problemas para traduções que não aparecem no WordPress, que trata as strings fuzzy como um item em uma lista maior.

Pronto para limpar um backlog fuzzy inteiro e fazer com que todas as strings apareçam em seu site? Experimente o SimplePoTranslate gratuitamente — não é necessário cartão de crédito. O plano gratuito retraduz seu arquivo .po do zero, substituindo correspondências fuzzy incertas por traduções limpas e confirmadas.