Como Criar um Arquivo .pot para um Tema ou Plugin
Você acabou de finalizar um plugin WordPress que deseja compartilhar com o mundo. O código funciona, os recursos são sólidos e alguém na Alemanha envia um e-mail perguntando como traduzi-lo para o alemão. Você os direciona para a pasta languages e percebe que não há nada lá. Nenhum modelo, nenhuma string, nenhuma maneira para um tradutor saber o que precisa ser traduzido. Seu plugin é tecnicamente "pronto para tradução" apenas no nome.
Todo projeto WordPress traduzível começa com um arquivo: o modelo .pot. Antes que alguém possa produzir uma versão em alemão, francês ou japonês, você precisa criar um arquivo POT que liste todas as strings visíveis para o usuário em seu código. Pule esta etapa e os tradutores ficarão presos lendo seu código-fonte linha por linha, adivinhando quais strings deveriam ser visíveis.
Este guia aborda as duas partes do trabalho: preparar seu código-fonte para que as strings sejam detectáveis e, em seguida, gerar o próprio .pot com três ferramentas diferentes. Usaremos WP-CLI, Poedit e a abordagem legada makepot/grunt, com comandos reais que você pode copiar. Ao final, você terá um modelo limpo pronto para entregar a qualquer tradutor.
Passo Um: Marque Suas Strings como Traduzíveis
Antes de criar um arquivo POT, toda string que um usuário possa ver precisa ser encapsulada em uma função Gettext. Um scanner só pode extrair strings que ele reconhece, e ele as reconhece por essas chamadas de função — literais de string simples são invisíveis para ele.
O WordPress oferece uma família de funções de localização, cada uma para um contexto ligeiramente diferente:
// Return a translated string
$label = __( 'Add to Cart', 'my-plugin' );
// Echo a translated string directly
_e( 'Your cart is empty', 'my-plugin' );
// Translate with context to disambiguate identical words
$verb = _x( 'Post', 'verb: to publish', 'my-plugin' );
// Translate AND escape for safe HTML output
echo esc_html__( 'Welcome back', 'my-plugin' );
O segundo argumento em cada chamada — 'my-plugin' — é o domínio de texto. Ele agrupa todas as strings de um plugin ou tema sob um único namespace para que o WordPress saiba qual arquivo .mo carregar para elas. Cada string traduzível em seu projeto deve compartilhar exatamente o mesmo domínio de texto, ou algumas strings nunca serão traduzidas.
Use _x() sempre que uma palavra for ambígua. O termo em inglês "Post" pode ser um substantivo ou um verbo, e muitas línguas os traduzem de forma diferente. Strings de contexto permitem que os tradutores os diferenciem. E recorra às variantes esc_html__() e esc_attr__() sempre que a string traduzida for impressa em HTML, para que você permaneça seguro e localizado ao mesmo tempo.
Existem alguns hábitos que mantêm suas strings extraíveis. Sempre passe um literal de string simples como o primeiro argumento — nunca uma variável ou uma concatenação como __( 'Hello ' . $name, 'my-plugin' ), porque o scanner lê o texto-fonte estaticamente e não consegue resolver valores em tempo de execução. Para frases com um número, use _n() para que as formas plurais sejam capturadas corretamente, e para frases com um valor dinâmico, use sprintf() em torno de um placeholder como %s em vez de juntar strings. A consistência aqui é o que faz com que a próxima etapa — a geração do modelo — produza um resultado completo e utilizável.
Passo Dois: Declare o Domínio de Texto no Seu Cabeçalho
O WordPress precisa de dois campos no cabeçalho para saber onde suas traduções residem: o Text Domain (Domínio de Texto) e o Domain Path (Caminho do Domínio). Defina-os no arquivo principal do seu plugin ou no style.css do seu tema, e o WordPress carregará automaticamente o .mo correto em tempo de execução.
<?php
/**
* Plugin Name: My Plugin
* Description: A perfectly localized WordPress plugin.
* Version: 1.0.0
* Requires at least: 6.4
* Text Domain: my-plugin
* Domain Path: /languages
*/
O Text Domain deve corresponder à string que você passou para cada chamada __() e _e() — my-plugin aqui. O Domain Path informa ao WordPress qual subpasta contém os arquivos de tradução, em relação à raiz do plugin ou tema. A convenção é /languages, e é exatamente onde seu .pot gerado deve residir.
Com as strings encapsuladas e o cabeçalho declarado, seu código está pronto para ser escaneado. O panorama mais amplo da preparação de um projeto para tradução — incluindo temas que não são seus — é abordado em como localizar qualquer tema WordPress mesmo que você não seja um desenvolvedor.
Como Gerar o Arquivo .pot? Três Métodos
Você gera um .pot executando um scanner em seu código-fonte que encontra cada chamada Gettext e escreve as strings em um modelo. Aqui estão três maneiras confiáveis de fazer isso, desde o padrão moderno até a abordagem legada.
Método 1: WP-CLI (Recomendado)
A maneira oficial e moderna de criar um arquivo POT é usando o WP-CLI com o comando i18n. Ele é fornecido como parte das ferramentas do núcleo do WordPress, entende strings PHP e JavaScript, e produz um modelo compatível com padrões em uma única linha.
# Run from your plugin or theme root directory
wp i18n make-pot . languages/my-plugin.pot
# Add a text domain explicitly if auto-detection misses it
wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin
# Scan only specific paths and exclude vendor folders
wp i18n make-pot . languages/my-plugin.pot --exclude=vendor,node_modules
O primeiro argumento é o diretório de origem (. para a pasta atual), e o segundo é o caminho de saída. O WP-CLI percorre seus arquivos, extrai cada string encapsulada, registra o arquivo de origem e o número da linha como um comentário, e escreve o .pot. É rápido, programável e a escolha certa para qualquer projeto sério.
O modelo gerado inclui metadados úteis que você pode ajustar com flags adicionais. Passe --headers para definir o nome do projeto, a versão e o endereço de contato dos tradutores, para que o bloco de cabeçalho do .pot seja preenchido corretamente em vez de ser deixado como placeholders. O WP-CLI também extrai strings JavaScript de chamadas wp_set_script_translations() automaticamente, o que é importante para temas de bloco modernos e plugins Gutenberg onde metade do texto visível para o usuário reside em JavaScript em vez de PHP. Um comando cobre ambos os mundos.
Método 2: Poedit (Gráfico)
Se você prefere um aplicativo de desktop, o Poedit pode escanear seu código-fonte e gerar o modelo através de sua interface. Abra o Poedit, escolha criar uma nova tradução a partir de POT ou escanear fontes diretamente, aponte-o para a pasta do seu projeto e configure as palavras-chave de origem (__, _e, _x, esc_html__) nas propriedades do catálogo.
Os recursos de escaneamento de código-fonte e geração de .pot do Poedit estão na sua edição Pro, mas o fluxo de trabalho é amigável para desenvolvedores que preferem clicar em vez de digitar comandos. É também um editor sólido para a fase de tradução que se segue. O Poedit e várias outras opções de desktop são comparados em as 5 melhores ferramentas gratuitas para editar e traduzir arquivos PO no Mac e Windows.
Método 3: makepot / grunt (Legado)
Antes do WP-CLI, a ferramenta padrão era o script makepot.php do repositório WordPress i18n-tools, muitas vezes integrado a uma tarefa de build do Grunt com grunt-wp-i18n. Você ainda o encontrará em plugins e temas mais antigos.
# Legacy makepot.php invocation
php makepot.php wp-plugin /path/to/my-plugin languages/my-plugin.pot
Funciona, mas não é mantido em comparação com o WP-CLI e é mais lento para configurar. Use-o apenas quando estiver mantendo um projeto legado que já depende dele; para qualquer coisa nova, prefira wp i18n make-pot.
Mantenha o Modelo Atualizado Conforme Seu Código Muda
Um .pot é um instantâneo de suas strings em um determinado momento. Toda vez que você adiciona um recurso, altera um rótulo ou corrige um erro de digitação em uma string visível, o modelo se torna obsoleto e os tradutores perdem a nova redação.
Torne a regeneração parte da sua rotina de lançamento. Execute novamente wp i18n make-pot antes de cada nova versão, e então mescle o modelo atualizado nas traduções existentes com wp i18n update-po ou msgmerge para que os tradutores mantenham seu trabalho concluído e vejam apenas as novas lacunas. Trate o .pot como um artefato de build que você regenera, não um arquivo que você edita manualmente.
Um modelo desatualizado causa uma falha sutil e frustrante: novas strings aparecem em inglês mesmo em um site "totalmente traduzido", porque nunca estiveram no .pot do qual o tradutor trabalhou. Evitar isso é tão simples quanto incluir a regeneração em seu processo de build, para que o modelo nunca fique desatualizado em relação ao código. Algumas equipes adicionam uma verificação de CI que falha o build se a regeneração do .pot produzir uma diferença, garantindo que o modelo commitado sempre corresponda ao código-fonte atual.
Assim que os tradutores retornam os arquivos .po finalizados, estes ainda precisam ser compilados para o .mo binário que o WordPress realmente carrega — e se você preferir pular todo o ciclo de download-traduzir-recompilar, uma ferramenta na nuvem pode lidar com isso de ponta a ponta. O SimplePoTranslate aceita seu .pot diretamente, o traduz com IA Sensível ao Contexto que entende o significado de cada string em sua interface, e retorna um único ZIP com os arquivos .po, .mo, e mais já construídos e nomeados. Seu Syntax Locking congela placeholders como %s e %1$s para que suas variáveis nunca quebrem na tradução.
Concluindo
Para criar um arquivo POT da maneira correta, primeiro torne seu código detectável — encapsule cada string visível em __(), _e(), _x(), ou uma variante de escape, todas compartilhando um único domínio de texto, e declare esse domínio mais o Domain Path em seu cabeçalho. Em seguida, gere o modelo com WP-CLI para novos projetos, Poedit se você preferir uma GUI, ou makepot apenas ao manter código legado.
Gere cedo, regenere frequentemente e nunca deixe seu modelo ficar desatualizado em relação ao seu código. Um .pot atual é a diferença entre um plugin que está genuinamente pronto para o mundo e um que apenas afirma estar.
Pronto para transformar seu modelo
.potem traduções finalizadas sem o trabalho manual de compilação? Experimente o SimplePoTranslate gratuitamente — não é necessário cartão de crédito. Carregue seu modelo no plano gratuito e baixe arquivos de tradução prontos para uso em minutos.