Como traduzir arquivos PO sem quebrar seu app

Arquivos PO parecem simples até que um %s traduzido, uma forma plural ausente ou um msgid alterado quebrem o app. Use este fluxo para traduzir as strings visíveis para humanos enquanto mantém a estrutura do gettext intacta.

Não cole o arquivo inteiro em um tradutor de texto comum. Um arquivo PO é quase código-fonte: as palavras são traduzíveis, mas a estrutura do arquivo, os placeholders, os comentários e os índices plurais precisam sobreviver sem mudanças.

Método 1: use um tradutor de arquivos PO

Escolha este método quando quiser o rascunho inicial mais rápido e seguro, sem editar os pares msgid / msgstr manualmente.

1. Faça backup do arquivo .po original. Guarde uma cópia limpa no repositório antes de enviar qualquer coisa para tradução. Se o arquivo traduzido quebrar, você precisa de uma versão conhecida e boa para comparar.

2. Abra um tradutor que entenda PO. Use uma ferramenta feita para arquivos gettext, como o OpenL PO Translator, uma ferramenta de tradução de documentos paga por uso. Uma ferramenta que entende PO deve traduzir as strings-alvo enquanto mantém strings de origem, comentários, placeholders e estrutura do arquivo intactos. Se ainda estiver escolhendo ferramenta, compare opções no nosso guia do melhor tradutor PO.

3. Envie o arquivo .po. Use o arquivo de idioma que contém entradas msgid e msgstr. Se você só tiver um modelo .pot, crie primeiro um arquivo .po do idioma-alvo e depois envie o .po.

4. Escolha o idioma de origem e o idioma de destino. Combine o idioma de origem com o texto dentro de msgid, não com o idioma da interface de administração. Por exemplo, se o arquivo contém msgid em inglês e você precisa de saída em espanhol, escolha inglês para espanhol.

5. Baixe o arquivo traduzido. Salve-o com a convenção de nome de locale esperada pelo seu framework. Plugins do WordPress geralmente usam um padrão de text-domain + locale, enquanto o Django costuma armazenar arquivos em locale/<language>/LC_MESSAGES/.

6. Revise primeiro as strings de risco. Pesquise no arquivo traduzido por %, {, }, <, >, msgid_plural, msgctxt e #, fuzzy. Essas são as entradas com maior chance de afetar o comportamento em tempo de execução.

7. Teste o arquivo traduzido no seu app. Carregue o idioma localmente e clique nas telas que usam as strings traduzidas. Um arquivo PO não termina quando é traduzido; termina quando o app ainda renderiza corretamente.

Método 2: traduza arquivos PO no Poedit

Escolha este método quando precisar de revisão humana, compatibilidade com WordPress ou um fluxo cuidadoso entrada por entrada.

1. Abra o arquivo no Poedit. O Poedit é um editor dedicado a PO e outros formatos de localização; o editor básico é gratuito, com recursos Pro pagos para fluxos mais pesados. Para WordPress, o handbook oficial de Polyglots explica que o Poedit pode criar arquivos .po e .mo a partir de um arquivo POT e suporta formas plurais e UTF-8.

2. Atualize a partir do modelo POT se o texto de origem mudou. Se os desenvolvedores alteraram o texto do app, atualize o .po a partir do .pot mais recente antes de traduzir. Isso mantém novas strings, strings removidas e strings fuzzy visíveis em vez de enviar silenciosamente UI antiga.

3. Traduza apenas o campo msgstr. O msgid é a string de origem que o app usa para procurar a tradução. Em fluxos normais de gettext, o tradutor deve editar msgstr, não msgid.

4. Mantenha os placeholders exatamente iguais. Não traduza nem reespacie variáveis como %s, %d, %1$s, {name}, %(count)s, :name ou tags HTML. Se a ordem das palavras precisar mudar, mova o placeholder como uma unidade.

5. Trate formas plurais como traduções separadas. Uma entrada plural pode conter msgid, msgid_plural e vários valores msgstr[n]. Preencha cada slot plural exigido pelo idioma de destino em vez de copiar a mesma frase em todos.

6. Salve e compile o arquivo .mo se o app precisar dele. Alguns sistemas leem .po diretamente durante o desenvolvimento, mas WordPress e muitos setups gettext usam arquivos .mo compilados em tempo de execução. O Poedit pode compilar .mo ao salvar; o Django pode compilar mensagens com django-admin compilemessages.

7. Resolva os avisos antes do upload. No Poedit, ícones de aviso costumam apontar para placeholders quebrados, variáveis ausentes ou incompatibilidade de plural. Corrija isso antes de importar a tradução para WordPress, Django, Drupal ou para a branch de release.

Método 3: use uma plataforma de localização

Escolha este método quando vários tradutores, revisores ou gerentes de release precisarem trabalhar nos mesmos arquivos PO.

1. Impor­te o arquivo PO para uma plataforma que suporte gettext. Weblate e plataformas semelhantes suportam fluxos PO. Plataformas de localização em equipe costumam ser produtos pagos, embora o Weblate também tenha uma opção open source auto-hospedada. O tratamento de comentários, cabeçalhos, strings fuzzy e placeholders varia, então verifique as configurações de formato antes de enviar arquivos de produção.

2. Ative verificações de placeholders e tags. Ligue regras de QA para placeholders no estilo printf, variáveis nomeadas, tags HTML/XML e formas plurais. Essas verificações pegam erros que um corretor ortográfico comum não vê.

3. Mantenha os comentários do desenvolvedor visíveis. Comentários em PO podem trazer contexto como referências de origem, notas extraídas do desenvolvedor, flags e strings de origem anteriores. Os tradutores precisam dessas notas quando um rótulo curto como “Open” pode ser verbo, adjetivo ou comando de menu.

4. Use memória de tradução com revisão. A memória de tradução é útil para strings repetidas da interface, mas pode copiar uma tradução antiga para um contexto novo. Revise strings reaproveitadas quando msgctxt, referências de origem ou UI ao redor mudarem.

5. Exporte os arquivos PO e rode verificações locais. Não confie cegamente na exportação. Coloque o arquivo traduzido de volta no app, compile se necessário e teste as telas antes de fazer merge.

Regras do arquivo PO que você nunca deve quebrar

Item do PO	Traduzir?	Exemplo seguro	Por que importa
msgid	Não	msgid "Save changes"	Em muitos fluxos gettext, o app usa essa string de origem como chave de busca.
msgstr	Sim	msgstr "Guardar alterações"	É o texto no idioma de destino que o usuário vê.
msgctxt	Não	msgctxt "button"	O contexto desambigua strings de origem idênticas.
%s, %d, %1$s	Não	Hello, %s -> Olá, %s	O runtime substitui esses placeholders por valores reais.
{name}, %(count)s, :name	Não	Welcome, {name}	Variáveis nomeadas precisam continuar batendo com o código do app.
Tags HTML	Normalmente não	<strong>Warning</strong>	Traduza o texto, não a sintaxe das tags.
msgid_plural	Não	msgid_plural "%d files"	O plural de origem pertence ao caminho de código original.
msgstr[0], msgstr[1]	Sim, com cuidado	msgstr[0] "%d arquivo"	Cada idioma de destino tem suas próprias regras de plural.
#, fuzzy	Revise primeiro	#, fuzzy	Fuzzy significa que a tradução pode estar desatualizada ou não confirmada.
#. comentários do desenvolvedor	Normalmente não	#. Button label	Essas notas ajudam o tradutor a entender o contexto.

Exemplo rápido: tradução segura vs. quebrada de PO

Aqui está uma entrada normal de gettext:

#. %s is the user's display name.
#, c-format
msgid "Welcome back, %s"
msgstr ""

Uma tradução segura para o espanhol mantém %s intacto:

#. %s is the user's display name.
#, c-format
msgid "Welcome back, %s"
msgstr "Bienvenido de nuevo, %s"

Uma tradução quebrada altera o placeholder:

msgid "Welcome back, %s"
msgstr "Bienvenido de nuevo, % s"

Esse pequeno espaço pode importar. O msgfmt --check-format do GNU foi criado para detectar incompatibilidades de string formatada, como placeholders % errados, e o Poedit também avisa sobre problemas comuns de placeholder. Para uma lista mais ampla de strings que devem ficar intocadas, use nosso guia sobre o que não traduzir.

Como verificar um arquivo PO traduzido

1. Execute a validação do gettext se ele estiver instalado.

msgfmt --check --check-format -o /tmp/messages.mo path/to/messages.po

Isso verifica sintaxe, cabeçalhos e strings de formato, depois escreve um catálogo compilado temporário se o arquivo for válido.

2. Compile o arquivo do jeito que o seu framework espera.

django-admin compilemessages

Para projetos Django, compilemessages compila arquivos .po criados por makemessages em arquivos .mo para suporte gettext.

3. Procure traduções vazias.

grep -n 'msgstr ""' path/to/messages.po

Campos msgstr vazios podem ser intencionais para entradas ainda não traduzidas, mas não devem te surpreender no release.

4. Procure strings fuzzy.

grep -n '#, fuzzy' path/to/messages.po

Strings fuzzy devem ser revisadas por uma pessoa antes do release. Por padrão, msgfmt não usa traduções fuzzy a menos que você compile com --use-fuzzy, então uma entrada fuzzy pode se comportar como string não traduzida no catálogo final.

5. Teste a UI real. Abra as telas que contêm formulários, contagens plurais, mensagens de erro, menus da conta e fluxos de pagamento. A validação do PO encontra problemas de arquivo; só o teste da UI encontra redação estranha, estouro e falta de contexto.

Qual método você deve usar?

Situação	Melhor método	Por quê
Você precisa de um rascunho rápido de um arquivo PO	Tradutor de arquivo PO	Caminho mais rápido com preservação de estrutura
Você mantém um plugin ou tema WordPress	Poedit	Fluxo familiar do WordPress com compilação .mo
Você mantém um app Django	Tradutor PO ou Poedit, depois compilemessages	A tradução pode ser rápida, mas a compilação do framework ainda é necessária
Você tem muitos idiomas e revisores	Plataforma de localização	Melhor atribuição, histórico, QA e controle de revisão
Você está traduzindo strings voltadas para desenvolvedores	Revisão humana após tradução automática	Termos de código, placeholders e contexto importam mais
Você também está localizando JSON ou arquivos i18n de frontend	Use um fluxo específico por formato	As regras de PO nem sempre se aplicam a JSON, YAML ou mensagens ICU

Se o seu projeto mistura arquivos PO gettext com arquivos locale JSON, traduza cada formato com uma ferramenta que entenda a estrutura dele. Os arquivos PO giram em torno de msgid e msgstr; a localização em JSON gira em torno de chaves e valores. Para esse fluxo, veja nosso guia dos melhores tradutores JSON em 2026.

FAQ

Posso traduzir arquivos PO com o Google Translate?

Você pode copiar valores individuais de msgstr para um tradutor comum, mas enviar ou colar o arquivo PO inteiro em um tradutor de texto comum é arriscado. Tradutores genéricos podem alterar msgid, comentários, escape de aspas, índices plurais ou placeholders. Use um tradutor PO-aware, o Poedit ou uma plataforma de localização.

Qual é a diferença entre .po, .pot e .mo?

.pot é o modelo extraído do código-fonte. Normalmente contém strings originais, mas não traduções completas. .po é o arquivo editável de tradução de um idioma-alvo. .mo é o catálogo binário compilado que muitos apps baseados em gettext carregam em tempo de execução.

Devo traduzir msgid?

Não, no fluxo normal. Traduza msgstr. O manual do GNU gettext descreve msgid como a string original não traduzida e msgstr como a tradução; as strings msgid são produzidas e gerenciadas pelas ferramentas gettext.

Como verifico se um arquivo PO é válido?

Execute msgfmt --check --check-format se o gettext estiver disponível, abra o arquivo no Poedit ou use as verificações de QA da sua plataforma de localização. Depois compile e teste o arquivo dentro do app. A validação é necessária, mas não substitui o teste da interface.

O que acontece se eu quebrar um placeholder?

No melhor caso, o app mostra uma string estranha. No pior, o formatador em tempo de execução gera erro porque a string traduzida não corresponde mais às variáveis passadas pelo código. Os placeholders devem ser movidos apenas como tokens completos, nunca traduzidos ou editados parcialmente.

O OpenL consegue traduzir arquivos PO?

Sim. O OpenL PO Translator foi criado para arquivos .po do gettext e diz manter placeholders e variáveis intactos enquanto traduz em mais de 100 idiomas. Ele usa um fluxo de tradução de documentos pago por uso, então é útil para um rascunho inicial rápido quando preservar a estrutura PO importa mais do que fazer tudo manualmente. Se você só tiver um modelo .pot, crie primeiro um .po do idioma-alvo antes de usar o OpenL.

Sources

• GNU gettext manual: PO Files — Official gettext explanation of the PO file format.
• GNU gettext manual: PO File Entries — Source for msgid, msgstr, comments, flags, and entry structure.
• GNU gettext manual: Entries with Plural Forms — Source for plural-form entry structure.
• GNU gettext manual: msgfmt Invocation — Source for msgfmt --check and format-string validation.
• OpenL PO Translator — OpenL product page for translating .po files while preserving placeholders and variables.
• Poedit — Official Poedit site for the PO translation editor and Pro offering.
• WordPress Polyglots Handbook: Poedit — WordPress guidance on using Poedit, POT files, PO files, MO compilation, and placeholder warnings.
• Django documentation: Translation — Django workflow for message files and translation.
• Django documentation: compilemessages — Django command reference for compiling .po files into .mo files.
• Drupal documentation: PO and POT files — Drupal explanation of .po, .pot, context, plural forms, comments, and variables.
• Weblate documentation: GNU gettext PO — Localization-platform notes on PO headers, previous source strings, obsolete strings, and generated MO files.