msgctxt gebruiken: Context toevoegen aan Gettext-vertalingen

Je vertaalt het Engelse woord "Book" naar het Duits, en je vertaler geeft vol vertrouwen "Buch" terug. Drie weken later verschijnt er een bugrapport: de knop "Book a table" op je reserveringsformulier leest nu "Buch a table" - het zelfstandig naamwoord, niet het werkwoord. Het woord was correct. De context ontbrak. Dit is een van de meest voorkomende stille mislukkingen in softwarelokalisatie, en de oplossing bestaat al tientallen jaren in Gettext: msgctxt.

Als je ooit een vertaling hebt geleverd waarbij een enkele Engelse string op de ene plek correct was en op een andere plek onzin, dan ben je het ambiguïteitsprobleem tegengekomen. Hetzelfde bronwoord leidt tot verschillende vertalingen, afhankelijk van de context. Zonder msgctxt heeft de vertaler (menselijk of AI) geen manier om die gevallen uit elkaar te houden, omdat ze alleen de kale string msgid "Book" zien. Deze gids legt uit hoe msgctxt werkt in Gettext, hoe je je broncode markeert met _x() en _ex(), hoe het verschijnt in je .po-bestanden, en waarom een contextbewuste vertaalpipeline de enige betrouwbare manier is om deze strings op schaal correct te krijgen.

Het ambiguïteitsprobleem: Eén woord, vele betekenissen

Natuurlijke taal zit vol met woorden die in het Engels tot één token worden samengevoegd, maar in andere talen opsplitsen in meerdere woorden. De vertaler ziet alleen de bronstring, dus wanneer twee ongerelateerde UI-elementen hetzelfde Engelse woord delen, delen ze dezelfde msgid - en voegt Gettext ze samen tot één vermelding.

Woorden die opsplitsen over talen heen

Overweeg drie klassieke voorbeelden:

• "Book" - het zelfstandig naamwoord (een object op een plank) versus het werkwoord ("Book a flight"). Duits: Buch versus buchen.
• "Post" - inhoud publiceren versus mail verzenden. Frans: publier versus courrier.
• "Order" - een volgorde/sortering versus een aankoop. Spaans: orden versus pedido.

In het Engels gebruikt je code op beide plaatsen dezelfde letterlijke string:

// Somewhere in a library catalog screen
echo __( 'Book', 'mytextdomain' );

// Somewhere in a reservation form button
echo __( 'Book', 'mytextdomain' );

Hoe identieke strings samenvallen tot één vermelding

Wanneer je wp i18n make-pot of xgettext uitvoert, vallen beide aanroepen samen tot één .po-vermelding:

#: catalog.php:42 reservation-form.php:88
msgid "Book"
msgstr ""

Er is precies één msgstr om in te vullen. Wat de vertaler ook kiest, één van de twee schermen zal verkeerd zijn. De vertaler kan dit niet oplossen, zelfs niet als ze het probleem begrijpen, omdat het formaat zelf hen niet toestaat om twee vertalingen voor één msgid te leveren. De ambiguïteit zit ingebakken in de data.

Wat is msgctxt en hoe lost het ambiguïteit op?

msgctxt is een contextstring die aan een vertaalvermelding is gekoppeld. Het korte antwoord: het voegt een tweede sleutel toe naast msgid, zodat Gettext (context, msgid) als een uniek paar beschouwt. Twee vermeldingen met dezelfde msgid maar verschillende msgctxt worden twee afzonderlijke, onafhankelijk te vertalen strings.

In het opzoekmodel van Gettext wordt een vertaling normaal gesproken alleen geordend op de bronstring. Met msgctxt wordt de sleutel de combinatie van context plus bron. Dat is het hele mechanisme, en het is waarom het zo netjes werkt: je verandert de weergegeven tekst niet, alleen de interne opzoeksleutel.

De msgctxt-regel in een .po-bestand

In een .po-bestand verschijnt de context op een eigen regel direct boven de msgid:

#: catalog.php:42
msgctxt "noun"
msgid "Book"
msgstr "Buch"

#: reservation-form.php:88
msgctxt "verb"
msgid "Book"
msgstr "Reservieren"

Nu zijn er twee vermeldingen. Ze hebben identieke msgid-waarden, maar verschillende msgctxt-waarden, dus elk krijgt zijn eigen msgstr. De catalogus geeft Buch weer; de reserveringsknop geeft Reservieren weer. De runtime kiest de juiste omdat je code heeft aangegeven welke context te gebruiken.

Vergelijk dat met de defecte versie met één vermelding hierboven. Het verschil zit niet in de kwaliteit van de vertaling, maar in de vraag of het datamodel überhaupt toestaat dat het juiste antwoord bestaat.

Je code markeren: _x() en _ex()

Om msgctxt in je .po-template uit te zenden, roep je een contextbewuste vertaalfunctie aan in plaats van de reguliere. In WordPress zijn dit _x() en zijn echoënde tegenhanger _ex(); in pure Gettext worden ze toegewezen aan pgettext().

Kiezen tussen _x() en _ex()

De reguliere __()-functie neemt de string en het tekst-domein aan. De context-variant voegt de context in als het tweede argument:

// 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' );

Het tweede argument is het contextlabel. Het wordt nooit aan je gebruikers getoond - het bestaat puur om ambiguïteit op te heffen, zowel voor de Gettext-opzoekactie als voor wie (of wat) de vertaling uitvoert. Schrijf contexten als korte, beschrijvende hints: 'zelfstandig naamwoord', 'werkwoord', 'knoplabel', 'admin menu'. Een vage context zoals '1' is technisch geldig, maar nutteloos voor een vertaler.

Wanneer je de template regenereert, herkent de extractor deze aanroepen en genereert de msgctxt-regel. Tools zoals Poedit en andere PO-editors groeperen de vermeldingen dan zichtbaar per context, zodat een menselijke vertaler onmiddellijk ziet dat "Boek (zelfstandig naamwoord)" en "Boek (werkwoord)" twee verschillende taken zijn. Als je nog bezig bent met het instellen van je extractie-toolchain of worstelt met hoe variabelen omgaan met deze strings, dan behandelt onze gids over PO-bestanden vertalen zonder codevariabelen te breken de omringende workflow uitgebreid.

Waarom naïeve vertalers – en veel AI-tools – dit verkeerd doen

Hier is het ongemakkelijke deel. Het toevoegen van msgctxt aan je bron is noodzakelijk, maar niet voldoende. De context helpt alleen als degene die de vertaling uitvoert deze daadwerkelijk leest.

De 'weggegooide context'-foutmodus

Een naïef batchvertaalscript doet het volgende: het loopt door de vermeldingen, pakt elke msgid, stuurt deze naar een vertaal-API en schrijft het resultaat naar msgstr. Het kijkt nooit naar de msgctxt-regel. Dus, hoewel je zorgvuldig _x( 'Book', 'noun' ) en _x( 'Book', 'verb' ) hebt geschreven, stuurt het script twee identieke verzoeken - "translate Book" - en plakt hetzelfde antwoord in beide. Al je markup-inspanning wordt in de laatste stap weggegooid.

Veel algemene AI-vertaaltools hebben dezelfde blinde vlek. Ze zijn gebouwd om tekst te vertalen, en msgctxt is metadata, geen tekst. Als de tool je .po afvlakt tot een lijst van strings voordat het naar het model wordt gestuurd, bereikt de context nooit de prompt van het model. Het model, zonder enig signaal, valt terug op de meest statistisch voorkomende betekenis van het woord - meestal het zelfstandig naamwoord voor "Book", de publicatiebetekenis voor "Post" - en vertaalt stilzwijgend het minderheidsgeval verkeerd. Je zult geen foutmelding zien. Je zult weken later een bugrapport van een Duitse gebruiker zien.

Context en meervouden delen dezelfde hoofdoorzaak

Dit is ook waar meervoudsvormen en context elkaar kruisen, omdat beide afhankelijk zijn van het feit dat de tool de structuur van Gettext begrijpt in plaats van het bestand als platte tekst te behandelen. Als je strings ook telling-gebaseerde vormen bevatten, is hetzelfde structurele bewustzijn van belang - we behandelen dat uitgebreid in Gettext-meervouden begrijpen.

Hoe een contextbewuste pipeline msgctxt gebruikt

Een vertaalpipeline die msgctxt respecteert, doet het tegenovergestelde van het naïeve script. Het parseert het .po-bestand als gestructureerde data, houdt de context van elke vermelding gekoppeld aan de bronstring, en geeft die context door aan de AI als onderdeel van de prompt - zodat het model weet dat het "Book" specifiek als werkwoord vertaalt, niet in het abstract.

Context als een eersteklas signaal

Dit is precies hoe SimplePoTranslate het probleem aanpakt. Zijn contextbewuste AI leest de msgctxt-regel als een eersteklas signaal: wanneer twee vermeldingen een msgid delen maar verschillen in context, worden ze vertaald als de afzonderlijke strings die ze werkelijk zijn, en de contexthint informeert de woordkeuze van het model. Het resultaat is dat "Book (zelfstandig naamwoord)" terugkomt als Buch terwijl "Book (werkwoord)" terugkomt als buchen of reservieren - automatisch, zonder dat je elke dubbelzinnige term handmatig hoeft te corrigeren.

Even belangrijk is dat de pipeline de msgctxt-regel in de uitvoer behoudt. Een minder krachtige tool zou de context kunnen verwijderen tijdens round-tripping, je twee vermeldingen stilletjes weer tot één kunnen samenvoegen en de ambiguïteit bij de volgende samenvoeging opnieuw kunnen introduceren. Volledige Gettext-ondersteuning betekent dat de context de vertaling, de .mo-compilatie en eventuele latere re-imports overleeft - zodat je disambiguatie duurzaam is, en geen eenmalige handmatige patch. Gecombineerd met Syntax Locking voor placeholders binnen die strings, krijg je vertalingen die zowel contextueel correct als structureel intact zijn.

Jij bent nog steeds verantwoordelijk voor de markup-beslissing - alleen jij weet dat een bepaald "Book" een werkwoord is. Maar zodra je je bron hebt geannoteerd met _x() en _ex(), zet een contextbewuste pipeline die annotatie om in correcte vertalingen in elke doeltaal, zonder dat je elke string afzonderlijk hoeft te bewaken.

Conclusie

Het ambiguïteitsprobleem - één Engels woord, vele betekenissen - is geen eigenaardigheid die je kunt negeren; het is een structurele eigenschap van hoe Gettext strings opslaat. De oplossing is msgctxt: annoteer dubbelzinnige strings in je bron met _x() en _ex(), geef elke voorkomende string een duidelijk contextlabel, en laat Gettext de vertaling indexeren op het (context, msgid)-paar. Dat deel is aan jou, en het kost maar een paar minuten.

Het moeilijkere deel is ervoor zorgen dat je vertaalstap die context daadwerkelijk respecteert in plaats van deze weg te gooien. Naïeve scripts en tekst-gebaseerde AI-tools negeren msgctxt en introduceren precies de bug opnieuw die je probeerde te voorkomen. Een contextbewuste pipeline leest de context, vertaalt elke gedisambigueerde vermelding correct en behoudt deze tijdens compilatie en re-imports.

Klaar om te stoppen met het leveren van context-blinde misvertalingen? Probeer SimplePoTranslate gratis — geen creditcard nodig. De gratis laag verwerkt echte .po- en .pot-bestanden met volledige msgctxt-contextondersteuning, zodat je gedisambigueerde strings de eerste keer correct worden vertaald.