Usando msgctxt: Adicionando Contexto às Traduções Gettext
Você traduz a palavra inglesa "Book" para o alemão, e seu tradutor retorna com confiança "Buch". Três semanas depois, um relatório de bug aparece: o botão "Book a table" no seu formulário de reserva agora lê "Buch a table" - o substantivo, não o verbo. A palavra estava certa. O contexto estava faltando. Esta é uma das falhas silenciosas mais comuns na localização de software, e a solução existe no Gettext há décadas: msgctxt.
Se você já enviou uma tradução onde uma única string em inglês estava correta em um lugar e sem sentido em outro, você se deparou com o problema da ambiguidade. A mesma palavra de origem mapeia para diferentes traduções dependendo de onde aparece. Sem msgctxt, o tradutor (humano ou IA) não tem como diferenciar esses casos, porque tudo o que vê é a string nua msgid "Book". Este guia explica como o msgctxt funciona no Gettext, como marcar seu código-fonte com _x() e _ex(), como ele aparece em seus arquivos .po e por que um pipeline de tradução ciente do contexto é a única maneira confiável de obter essas strings corretas em escala.
O Problema da Ambiguidade: Uma Palavra, Muitos Significados
A linguagem natural é cheia de palavras que se reduzem a um único token em inglês, mas se dividem em várias palavras em outros idiomas. O tradutor vê apenas a string de origem, então, quando dois elementos de UI não relacionados compartilham a mesma palavra em inglês, eles compartilham o mesmo msgid - e o Gettext os mescla em uma única entrada.
Palavras Que Se Dividem Entre Idiomas
Considere três exemplos clássicos:
- "Book" - o substantivo (um objeto em uma prateleira) versus o verbo ("Reservar um voo"). Alemão: Buch versus buchen.
- "Post" - publicar conteúdo versus enviar correspondência. Francês: publier versus courrier.
- "Order" - uma sequência/ordenamento versus uma compra. Espanhol: orden versus pedido.
Em inglês, seu código usa a mesma string literal em ambos os lugares:
// Somewhere in a library catalog screen
echo __( 'Book', 'mytextdomain' );
// Somewhere in a reservation form button
echo __( 'Book', 'mytextdomain' );
Como Strings Idênticas Colapsam em Uma Única Entrada
Quando você executa wp i18n make-pot ou xgettext, ambas as chamadas colapsam em uma única entrada .po:
#: catalog.php:42 reservation-form.php:88
msgid "Book"
msgstr ""
Há exatamente um msgstr para preencher. O que quer que o tradutor escolha, uma das duas telas estará errada. O tradutor não pode corrigir isso mesmo que entenda o problema, porque o próprio formato não permite fornecer duas traduções para um msgid. A ambiguidade está intrínseca aos dados.
O Que É msgctxt e Como Ele Desambigua?
msgctxt é uma string de contexto anexada a uma entrada de tradução. A resposta curta: ele adiciona uma segunda chave ao lado de msgid, então o Gettext trata (context, msgid) como um par único. Duas entradas com o mesmo msgid mas diferentes msgctxt tornam-se duas strings separadas, traduzíveis independentemente.
No modelo de busca do Gettext, uma tradução é normalmente indexada apenas pela string de origem. Com msgctxt, a chave se torna a combinação de contexto mais origem. Esse é todo o mecanismo, e é por isso que funciona tão limpo: você não está mudando o texto exibido, apenas a chave de busca interna.
A Linha msgctxt em um Arquivo .po
Em um arquivo .po, o contexto aparece em sua própria linha diretamente acima do msgid:
#: catalog.php:42
msgctxt "noun"
msgid "Book"
msgstr "Buch"
#: reservation-form.php:88
msgctxt "verb"
msgid "Book"
msgstr "Reservieren"
Agora existem duas entradas. Elas têm valores msgid idênticos, mas valores msgctxt distintos, então cada uma recebe seu próprio msgstr. O catálogo renderiza Buch; o botão de reserva renderiza Reservieren. O tempo de execução escolhe o correto porque seu código informou qual contexto usar.
Compare isso com a versão de entrada única quebrada acima. A diferença não é a qualidade da tradução - é se o modelo de dados permite que a resposta correta exista.
Marcando Seu Código: _x() e _ex()
Para emitir msgctxt em seu modelo .po, você chama uma função de tradução ciente do contexto em vez da simples. No WordPress, estas são _x() e sua irmã de eco _ex(); no Gettext puro, elas mapeiam para pgettext().
Escolhendo Entre _x() e _ex()
A função simples __() recebe a string e o domínio de texto. A variante de contexto insere o contexto como o segundo argumento:
// Without context - ambiguous
__( 'Book', 'mytextdomain' );
// With context - the second argument is the msgctxt
_x( 'Book', 'noun', 'mytextdomain' ); // returns the translated string
_ex( 'Book', 'verb', 'mytextdomain' ); // echoes it directly
// Real-world disambiguation
_x( 'Post', 'verb: publish content', 'mytextdomain' );
_x( 'Post', 'noun: mail item', 'mytextdomain' );
_x( 'Order', 'sequence or sorting', 'mytextdomain' );
_x( 'Order', 'customer purchase', 'mytextdomain' );
O segundo argumento é o rótulo de contexto. Ele nunca é mostrado aos seus usuários - existe puramente para desambiguar, tanto para a busca do Gettext quanto para quem (ou o que) está fazendo a tradução. Escreva contextos como dicas curtas e descritivas: 'substantivo', 'verbo', 'rótulo do botão', 'menu de administração'. Um contexto vago como '1' é tecnicamente válido, mas inútil para um tradutor.
Ao regenerar o modelo, o extrator reconhece essas chamadas e emite a linha msgctxt. Ferramentas como Poedit e outros editores PO agrupam as entradas visivelmente por contexto, para que um tradutor humano veja imediatamente que "Book (substantivo)" e "Book (verbo)" são dois trabalhos diferentes. Se você ainda está configurando sua cadeia de ferramentas de extração ou lidando com a interação de variáveis com essas strings, nosso guia sobre tradução de arquivos PO sem quebrar variáveis de código aborda o fluxo de trabalho circundante em profundidade.
Por Que Tradutores Ingênuos - e Muitas Ferramentas de IA - Erram Isso
Aqui está a parte desconfortável. Adicionar msgctxt à sua origem é necessário, mas não suficiente. O contexto só ajuda se o que está fazendo a tradução realmente o lê.
O Modo de Falha de Contexto Descartado
Um script de tradução em lote ingênuo faz o seguinte: ele percorre as entradas, pega cada msgid, envia para uma API de tradução e escreve o resultado em msgstr. Ele nunca olha para a linha msgctxt. Então, mesmo que você tenha escrito cuidadosamente _x( 'Book', 'noun' ) e _x( 'Book', 'verb' ), o script envia duas solicitações idênticas - "traduzir Book" - e cola a mesma resposta em ambas. Todo o seu esforço de marcação é descartado na última etapa.
Muitas ferramentas de tradução de IA de propósito geral têm o mesmo ponto cego. Elas são construídas para traduzir texto, e msgctxt é metadados, não texto. Se a ferramenta achatar seu .po em uma lista de strings antes de enviá-lo para o modelo, o contexto nunca chega ao prompt do modelo. O modelo, sem nenhum sinal, assume o sentido estatisticamente mais comum da palavra - geralmente o substantivo para "Book", o sentido de publicação para "Post" - e traduz incorretamente o caso minoritário silenciosamente. Você não verá um erro. Você verá um relatório de bug de um usuário alemão semanas depois.
Contexto e Plurais Compartilham a Mesma Causa Raiz
É aqui também que o tratamento de plurais e o contexto se cruzam, porque ambos dependem da ferramenta entender a estrutura do Gettext, em vez de tratar o arquivo como texto plano. Se suas strings também envolvem formas baseadas em contagem, a mesma consciência estrutural importa - detalhamos isso em entendendo os plurais do Gettext.
Como um Pipeline Ciente do Contexto Usa msgctxt
Um pipeline de tradução que respeita msgctxt faz o oposto do script ingênuo. Ele analisa o arquivo .po como dados estruturados, mantém o contexto de cada entrada anexado à sua string de origem e passa esse contexto para a IA como parte do prompt - para que o modelo saiba que está traduzindo "Book" especificamente como um verbo, não em abstrato.
Contexto como um Sinal de Primeira Classe
É exatamente assim que o SimplePoTranslate aborda o problema. Sua IA ciente do contexto lê a linha msgctxt como um sinal de primeira classe: quando duas entradas compartilham um msgid mas diferem no contexto, elas são traduzidas como as strings distintas que realmente são, e a dica de contexto informa a escolha de palavras do modelo. O resultado é que "Book (substantivo)" retorna como Buch enquanto "Book (verbo)" retorna como buchen ou reservieren - automaticamente, sem que você precise corrigir manualmente cada termo ambíguo.
Tão importante quanto, o pipeline preserva a linha msgctxt na saída. Uma ferramenta mais fraca pode remover o contexto durante o round-trip, colapsando silenciosamente suas duas entradas de volta em uma e reintroduzindo a ambiguidade na próxima mesclagem. O suporte total ao Gettext significa que o contexto sobrevive à tradução, à compilação .mo e a quaisquer reimportações posteriores - para que sua desambiguação seja durável, não um patch manual pontual. Combinado com o Bloqueio de Sintaxe para placeholders dentro dessas strings, você obtém traduções que são contextual e estruturalmente intactas.
Você ainda é responsável pela decisão de marcação - somente você sabe que um determinado "Book" é um verbo. Mas uma vez que você anota sua origem com _x() e _ex(), um pipeline ciente do contexto transforma essa anotação em traduções corretas em todos os idiomas de destino, sem a necessidade de supervisão por string.
Conclusão
O problema da ambiguidade - uma palavra em inglês, muitos significados - não é uma peculiaridade que você pode ignorar; é uma característica estrutural de como o Gettext armazena strings. A solução é msgctxt: anote strings ambíguas em sua origem com _x() e _ex(), dê a cada ocorrência um rótulo de contexto claro e deixe o Gettext indexar a tradução no par (context, msgid). Essa parte é com você, e leva minutos.
A parte mais difícil é garantir que sua etapa de tradução realmente honre esse contexto em vez de descartá-lo. Scripts ingênuos e ferramentas de IA somente de texto descartam msgctxt e reintroduzem o bug exato que você estava tentando evitar. Um pipeline ciente do contexto lê o contexto, traduz cada entrada desambiguada corretamente e a preserva através da compilação e reimportações.
Pronto para parar de entregar traduções incorretas que ignoram o contexto? Experimente o SimplePoTranslate gratuitamente — não é necessário cartão de crédito. O nível gratuito lida com arquivos
.poe.potreais com suporte completo ao contexto msgctxt, para que suas strings desambiguadas sejam traduzidas corretamente na primeira vez.