Internacionalização (i18n) de plugins e temas WordPress

Atualizado em 19/06/2026

Internacionalizar (i18n) é deixar o seu código pronto para ser traduzido sem ter de editá-lo — e essa é uma das marcas que separam um plugin amador de um profissional. O WordPress resolve o problema com a biblioteca gettext: você envolve cada texto visível ao usuário em uma função (__(), _e(), _n()…), informa um text domain que identifica o seu projeto, e a partir daí um tradutor pode produzir os arquivos de cada idioma sem nunca abrir o seu PHP. Parece simples, mas há nuances — text domain literal, placeholders numerados, comentários para tradutores — que, ignoradas, fazem strings "desaparecerem" do catálogo. Vamos a elas.

Por que internacionalizar (e por que cedo)

Mesmo que o seu público hoje seja só o Brasil, há motivos concretos para internacionalizar desde a primeira versão:

• Distribuição: para publicar no WordPress.org, a internacionalização é praticamente obrigatória — é o que permite à comunidade traduzir o seu plugin via translate.wordpress.org.
• Custo de retrofit: voltar a um plugin com centenas de strings cruas para envolvê-las uma a uma é caro e arriscado. Fazer no momento em que se escreve a string custa segundos.
• Consistência: o mesmo mecanismo serve para padronizar termos, ajustar plurais e dar contexto — qualidade que se reflete mesmo num site monolíngue.

A internacionalização é trabalho do desenvolvedor; a tradução em si (a localização, ou l10n) é feita depois, sobre os arquivos que você gera. Aqui tratamos da primeira metade — a que vive no código.

O text domain: a regra que mais gera bug

Toda string traduzível carrega um text domain: um identificador que diz a qual projeto aquela tradução pertence. É o segundo argumento das funções gettext. Três regras inegociáveis:

• O text domain deve ser idêntico ao slug do plugin — a pasta/arquivo registrado no .org. Se o plugin é minha-loja, o domain é minha-loja.
• Ele tem de ser uma string literal, escrita à mão em cada chamada. Nunca use uma variável, constante ou concatenação — o extrator de strings lê o código sem executá-lo e não conseguiria resolver o valor.
• O texto a traduzir também é literal, pela mesma razão. Não monte a frase com variáveis dentro de __().

Declarando o text domain e carregando as traduções

No cabeçalho do plugin, declare Text Domain (e, por convenção histórica, Domain Path). Em seguida, registre o carregamento dos arquivos .mo a partir de uma pasta /languages:

<?php
/**
 * Plugin Name: Minha Loja
 * Description: Exemplo de plugin internacionalizado.
 * Version:     1.0.0
 * Text Domain: minha-loja
 * Domain Path: /languages
 */

add_action( 'init', 'minha_loja_load_textdomain' );

function minha_loja_load_textdomain() {
    load_plugin_textdomain(
        'minha-loja',                          // text domain (= slug)
        false,                                  // parâmetro legado, sempre false
        dirname( plugin_basename( __FILE__ ) ) . '/languages'
    );
}

As funções gettext: traduzir, imprimir, escapar

Existe uma função para cada combinação de "retornar ou imprimir" e "escapar ou não". Memorize a lógica dos nomes — ela é consistente:

• __() (dois sublinhados) retorna a string traduzida.
• _e() imprime (ecoa) a string traduzida — é echo __().
• O prefixo esc_html_ ou esc_attr_ adiciona o escaping de saída no mesmo passo: esc_html__() traduz e retorna escapado para HTML; esc_attr_e() traduz e imprime escapado para atributo.
• _n() resolve plural; _x()/_ex() adicionam contexto para desambiguar.

<?php
// Retorna (para usar numa variável, num return, etc.)
$titulo = __( 'Configurações', 'minha-loja' );

// Imprime direto
_e( 'Salvar alterações', 'minha-loja' );

// Traduz E escapa na saída (a forma recomendada ao ecoar em HTML)
echo esc_html__( 'Bem-vindo à sua loja', 'minha-loja' );

// Dentro de um atributo:
printf( '<input type="submit" value="%s">', esc_attr__( 'Enviar', 'minha-loja' ) );

// Plural: _n( singular, plural, número, domain )
$n = count( $itens );
$texto = sprintf(
    _n( '%s item no carrinho', '%s itens no carrinho', $n, 'minha-loja' ),
    number_format_i18n( $n )
);

// Contexto com _x(): a MESMA palavra, sentidos diferentes
$rotulo_botao = _x( 'Post', 'verbo, publicar conteúdo', 'minha-loja' );
$rotulo_tipo  = _x( 'Post', 'substantivo, um artigo', 'minha-loja' );

Referência rápida das funções

Regra de bolso: ao ecoar texto em HTML, prefira sempre a variante esc_html_* ou esc_attr_*. Você ganha tradução e escaping de saída num único passo — duas boas práticas pelo preço de uma.

Variáveis em strings: sprintf e placeholders numerados

Aqui mora um dos erros mais comuns. Você nunca concatena uma variável dentro de __(), porque isso quebra a string em pedaços que o tradutor não consegue traduzir como uma frase. A forma correta é deixar a frase inteira como placeholder e injetar o valor com sprintf():

<?php
$nome  = 'Roger';
$total = 3;

// ERRADO: concatenação quebra a frase e impede a tradução
echo __( 'Olá, ', 'minha-loja' ) . $nome . __( '! Você tem ', 'minha-loja' ) . $total . __( ' pedidos.', 'minha-loja' );

// CERTO: frase inteira traduzível + sprintf com placeholders NUMERADOS
/* translators: 1: nome do cliente, 2: quantidade de pedidos */
echo sprintf(
    esc_html__( 'Olá, %1$s! Você tem %2$d pedidos.', 'minha-loja' ),
    esc_html( $nome ),
    (int) $total
);

Por que numerar (%1$s, %2$d) e não usar %s/%d simples? Porque a ordem das palavras varia entre idiomas. Com placeholders numerados, o tradutor pode escrever, por exemplo, "Você tem %2$d pedidos, %1$s!" — reordenando os argumentos sem tocar no seu PHP. Com placeholders sem número, a ordem fica presa à sequência dos argumentos passados ao sprintf(). Use a forma simples apenas quando houver um único placeholder.

O comentário para tradutores

Sempre que uma string tem placeholders ou é ambígua, deixe um comentário /* translators: ... */ na linha imediatamente acima da chamada gettext. O extrator anexa esse comentário à string no .pot, e é ele que diz ao tradutor o que cada %s significa:

<?php
/* translators: %s = título do produto */
$msg = sprintf( esc_html__( 'O produto "%s" foi adicionado ao carrinho.', 'minha-loja' ), esc_html( $titulo ) );

/* translators: 1: data do pedido, 2: valor total formatado */
$resumo = sprintf(
    esc_html__( 'Pedido feito em %1$s, total de %2$s.', 'minha-loja' ),
    esc_html( $data ),
    esc_html( $valor )
);

Gerando o catálogo: o fluxo .pot → .po → .mo

Com o código internacionalizado, o próximo passo é gerar o template de tradução (.pot), que lista todas as strings extraídas. A ferramenta oficial é o WP-CLI:

# Na raiz do plugin, gera languages/minha-loja.pot
wp i18n make-pot . languages/minha-loja.pot --domain=minha-loja

# (opcional) gerar os .json para as traduções de JavaScript
wp i18n make-json languages/ --no-purge

O ciclo completo de arquivos é:

1. .pot (Portable Object Template): o catálogo-mestre, sem traduções, gerado do seu código. É o que você distribui para os tradutores.
2. .po (Portable Object): uma cópia do .pot preenchida com as traduções de um idioma (ex.: minha-loja-pt_BR.po). Editável em ferramentas como o Poedit ou no GlotPress.
3. .mo (Machine Object): a versão binária e compilada do .po, que é o que o WordPress realmente lê em tempo de execução. Gerada a partir do .po (o Poedit faz ao salvar; o WP-CLI faz com wp i18n make-mo).

A convenção de nomes dos arquivos importa: para plugins, o padrão é {textdomain}-{locale}.mo — por exemplo, minha-loja-pt_BR.mo. Errar o locale ou o domain no nome do arquivo faz o WordPress não encontrar a tradução, mesmo com tudo o mais correto.

i18n no JavaScript

Strings em blocos do editor, em scripts do admin ou no front-end também precisam ser traduzíveis. O WordPress expõe o pacote @wordpress/i18n (acessível como wp.i18n), com as mesmas funções do PHP, e você conecta o catálogo ao script com wp_set_script_translations() no momento do enfileiramento:

<?php
// PHP: enfileira o script e conecta as traduções (arquivos .json em /languages)
add_action( 'wp_enqueue_scripts', 'minha_loja_scripts' );

function minha_loja_scripts() {
    wp_enqueue_script(
        'minha-loja-front',
        plugins_url( 'js/front.js', __FILE__ ),
        array( 'wp-i18n' ),       // dependência obrigatória
        '1.0.0',
        true
    );
    wp_set_script_translations( 'minha-loja-front', 'minha-loja', plugin_dir_path( __FILE__ ) . 'languages' );
}

No lado do JavaScript, importe e use __() normalmente. Lembre-se: a tradução de JS usa arquivos .json (gerados com wp i18n make-json), não .mo — mas o text domain é o mesmo do PHP.

Armadilhas comuns

Boas práticas

• Envolva a string no momento em que a escreve. Não deixe para "internacionalizar depois" — o retrofit é o caminho mais caro.
• Prefira as variantes que escapam (esc_html__(), esc_attr_e()) ao ecoar em HTML: tradução e segurança no mesmo passo.
• Mantenha o text domain idêntico ao slug e sempre literal. Rode o linter do wp i18n no CI para pegar divergências cedo.
• Numere os placeholders a partir de dois argumentos e comente cada um com /* translators: */.
• Use number_format_i18n() e date_i18n() para números e datas — a formatação também muda por locale.
• Não traduza fora de contexto de usuário: nomes de hooks, chaves de array e identificadores internos não vão para o catálogo. Internacionalize apenas o que é visível.

Internacionalizar é, no fim, uma questão de disciplina com um punhado de funções — exatamente como acontece com hooks e com a segurança. Feito desde o primeiro commit do seu plugin, custa segundos por string e abre o seu produto para o mundo inteiro.