msgctxt verwenden: Kontext zu Gettext-Übersetzungen hinzufügen
Sie übersetzen das englische Wort „Book“ ins Deutsche, und Ihr Übersetzer liefert souverän „Buch“ zurück. Drei Wochen später trifft ein Bug-Report ein: Der Button „Book a table“ auf Ihrem Reservierungsformular lautet nun „Buch a table“ – das Nomen, nicht das Verb. Das Wort war richtig. Der Kontext fehlte. Dies ist eine der häufigsten stillen Fehlfunktionen in der Softwarelokalisierung, und die Lösung existiert in Gettext seit Jahrzehnten: msgctxt.
Wenn Sie jemals eine Übersetzung ausgeliefert haben, bei der ein einziger englischer String an einer Stelle korrekt und an einer anderen unsinnig war, sind Sie auf das Ambiguitätsproblem gestoßen. Dasselbe Quellwort wird je nach Kontext unterschiedlich übersetzt. Ohne msgctxt hat der Übersetzer (Mensch oder KI) keine Möglichkeit, diese Fälle zu unterscheiden, da er nur den reinen String msgid "Book" sieht. Dieser Leitfaden erklärt, wie msgctxt in Gettext funktioniert, wie Sie Ihren Quellcode mit _x() und _ex() markieren, wie es in Ihren .po-Dateien erscheint und warum eine kontextsensitive Übersetzungspipeline der einzig zuverlässige Weg ist, diese Strings im großen Maßstab korrekt zu übersetzen.
Das Ambiguitätsproblem: Ein Wort, viele Bedeutungen
Die natürliche Sprache ist voll von Wörtern, die zu einem einzigen englischen Token zusammenfallen, sich aber in anderen Sprachen in mehrere Wörter aufteilen. Der Übersetzer sieht nur den Quellstring. Wenn also zwei unabhängige UI-Elemente dasselbe englische Wort teilen, teilen sie auch dieselbe msgid – und Gettext führt sie zu einem Eintrag zusammen.
Wörter, die sich über Sprachen hinweg aufteilen
Betrachten Sie drei klassische Beispiele:
- „Book“ – das Nomen (ein Objekt im Regal) versus das Verb („Book a flight“). Deutsch: Buch versus buchen.
- „Post“ – Inhalte veröffentlichen versus E-Mails senden. Französisch: publier versus courrier.
- „Order“ – eine Reihenfolge/Sortierung versus ein Kauf. Spanisch: orden versus pedido.
Im Englischen verwendet Ihr Code an beiden Stellen denselben Literal-String:
// Somewhere in a library catalog screen
echo __( 'Book', 'mytextdomain' );
// Somewhere in a reservation form button
echo __( 'Book', 'mytextdomain' );
Wie identische Strings zu einem einzigen Eintrag kollabieren
Wenn Sie wp i18n make-pot oder xgettext ausführen, kollabieren beide Aufrufe zu einem einzigen .po-Eintrag:
#: catalog.php:42 reservation-form.php:88
msgid "Book"
msgstr ""
Es gibt genau einen msgstr zum Ausfüllen. Was auch immer der Übersetzer wählt, einer der beiden Bildschirme wird falsch sein. Der Übersetzer kann dies nicht beheben, selbst wenn er das Problem versteht, da das Format selbst es ihm nicht erlaubt, zwei Übersetzungen für eine msgid bereitzustellen. Die Ambiguität ist in den Daten verankert.
Was ist msgctxt und wie disambiguiert es?
msgctxt ist ein Kontext-String, der an einen Übersetzungs-Eintrag angehängt wird. Die kurze Antwort: Es fügt einen zweiten Schlüssel neben msgid hinzu, sodass Gettext (context, msgid) als eindeutiges Paar behandelt. Zwei Einträge mit derselben msgid, aber unterschiedlichem msgctxt, werden zu zwei separaten, unabhängig übersetzbaren Strings.
Im Nachschlagemodell von Gettext wird eine Übersetzung normalerweise nur über den Quellstring indiziert. Mit msgctxt wird der Schlüssel zur Kombination aus Kontext und Quelle. Das ist der gesamte Mechanismus, und deshalb funktioniert er so sauber: Sie ändern nicht den angezeigten Text, sondern nur den internen Nachschlageschlüssel.
Die msgctxt-Zeile in einer .po-Datei
In einer .po-Datei erscheint der Kontext in einer eigenen Zeile direkt über der msgid:
#: catalog.php:42
msgctxt "noun"
msgid "Book"
msgstr "Buch"
#: reservation-form.php:88
msgctxt "verb"
msgid "Book"
msgstr "Reservieren"
Nun gibt es zwei Einträge. Sie haben identische msgid-Werte, aber unterschiedliche msgctxt-Werte, sodass jeder seinen eigenen msgstr erhält. Der Katalog rendert Buch; der Reservierungsbutton rendert Reservieren. Die Laufzeit wählt den richtigen aus, weil Ihr Code ihr mitgeteilt hat, welchen Kontext sie verwenden soll.
Vergleichen Sie dies mit der fehlerhaften Einzel-Eintrag-Version oben. Der Unterschied ist nicht die Übersetzungsqualität – es ist die Frage, ob das Datenmodell überhaupt zulässt, dass die richtige Antwort existiert.
Markieren Ihres Codes: _x() und _ex()
Um msgctxt in Ihre .po-Vorlage auszugeben, rufen Sie eine kontextsensitive Übersetzungsfunktion anstelle der einfachen auf. In WordPress sind dies _x() und seine ausgebende Schwesterfunktion _ex(); in reinem Gettext sind sie pgettext() zugeordnet.
Auswahl zwischen _x() und _ex()
Die einfache __()-Funktion nimmt den String und die Textdomain entgegen. Die Kontextvariante fügt den Kontext als zweites Argument ein:
// 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' );
Das zweite Argument ist das Kontext-Label. Es wird Ihren Benutzern nie angezeigt – es dient ausschließlich der Disambiguierung, sowohl für die Gettext-Suche als auch für denjenigen (oder dasjenige), der die Übersetzung vornimmt. Schreiben Sie Kontexte als kurze, beschreibende Hinweise: 'noun', 'verb', 'button label', 'admin menu'. Ein vager Kontext wie '1' ist technisch gültig, aber für einen Übersetzer nutzlos.
Wenn Sie die Vorlage neu generieren, erkennt der Extractor diese Aufrufe und gibt die msgctxt-Zeile aus. Tools wie Poedit und andere PO-Editoren gruppieren die Einträge dann sichtbar nach Kontext, sodass ein menschlicher Übersetzer sofort erkennt, dass „Book (Nomen)“ und „Book (Verb)“ zwei verschiedene Aufgaben sind. Wenn Sie noch Ihre Extraktions-Toolchain einrichten oder sich damit auseinandersetzen, wie Variablen mit diesen Strings interagieren, deckt unser Leitfaden zum Übersetzen von PO-Dateien ohne Code-Variablen zu beschädigen den gesamten Workflow ausführlich ab.
Warum naive Übersetzer – und viele KI-Tools – dies falsch machen
Hier kommt der unangenehme Teil. Das Hinzufügen von msgctxt zu Ihrer Quelle ist notwendig, aber nicht ausreichend. Der Kontext hilft nur, wenn die Instanz, die die Übersetzung vornimmt, ihn auch tatsächlich liest.
Der Fehlermodus „Verworfener Kontext“
Ein naives Stapelübersetzungs-Skript funktioniert so: Es durchläuft Einträge, nimmt jeden msgid, sendet ihn an eine Übersetzungs-API und schreibt das Ergebnis in msgstr. Es berücksichtigt niemals die msgctxt-Zeile. Obwohl Sie also sorgfältig _x( 'Book', 'noun' ) und _x( 'Book', 'verb' ) geschrieben haben, sendet das Skript zwei identische Anfragen – „Book übersetzen“ – und fügt dieselbe Antwort in beide ein. All Ihr Markup-Aufwand wird im letzten Schritt verworfen.
Viele allgemeine KI-Übersetzungstools haben denselben blinden Fleck. Sie sind darauf ausgelegt, Text zu übersetzen, und msgctxt ist Metadaten, kein Text. Wenn das Tool Ihre .po-Datei in eine Liste von Strings glättet, bevor es sie an das Modell sendet, erreicht der Kontext niemals den Prompt des Modells. Das Modell, dem jegliches Signal fehlt, greift auf die statistisch häufigste Bedeutung des Wortes zurück – normalerweise das Nomen für „Book“, die Veröffentlichungsbedeutung für „Post“ – und übersetzt den Minderheitsfall stillschweigend falsch. Sie werden keinen Fehler sehen. Sie werden Wochen später einen Bug-Report von einem deutschen Benutzer erhalten.
Kontext und Pluralformen teilen dieselbe Ursache
Hier überschneiden sich auch die Pluralbehandlung und der Kontext, da beides davon abhängt, dass das Tool die Struktur von Gettext versteht, anstatt die Datei als reinen Text zu behandeln. Wenn Ihre Strings auch zählerbasierte Formen beinhalten, ist dieselbe strukturelle Sensibilität wichtig – wir schlüsseln dies in Gettext-Pluralformen verstehen auf.
Wie eine kontextsensitive Pipeline msgctxt verwendet
Eine Übersetzungspipeline, die msgctxt respektiert, tut das Gegenteil des naiven Skripts. Sie parst die .po-Datei als strukturierte Daten, hält den Kontext jedes Eintrags an seinen Quellstring gebunden und gibt diesen Kontext als Teil des Prompts an die KI weiter – so weiß das Modell, dass es „Book“ speziell als Verb übersetzt und nicht abstrakt.
Kontext als erstklassiges Signal
Genau so geht SimplePoTranslate das Problem an. Seine kontextsensitive KI liest die msgctxt-Zeile als erstklassiges Signal: Wenn zwei Einträge eine msgid teilen, sich aber im Kontext unterscheiden, werden sie als die eigenständigen Strings übersetzt, die sie tatsächlich sind, und der Kontext-Hinweis beeinflusst die Wortwahl des Modells. Das Ergebnis ist, dass „Book (Nomen)“ als Buch zurückkommt, während „Book (Verb)“ als buchen oder reservieren zurückkommt – automatisch, ohne dass Sie jeden mehrdeutigen Begriff manuell korrigieren müssen.
Ebenso wichtig ist, dass die Pipeline die msgctxt-Zeile in der Ausgabe beibehält. Ein schwächeres Tool könnte den Kontext während des Round-Tripping entfernen, Ihre zwei Einträge stillschweigend wieder zu einem zusammenfassen und die Ambiguität beim nächsten Merge wieder einführen. Volle Gettext-Unterstützung bedeutet, dass der Kontext die Übersetzung, die .mo-Kompilierung und spätere Re-Importe überlebt – so ist Ihre Disambiguierung dauerhaft und kein einmaliger manueller Patch. Kombiniert mit Syntax Locking für Platzhalter innerhalb dieser Strings erhalten Sie Übersetzungen, die sowohl kontextuell korrekt als auch strukturell intakt sind.
Sie sind immer noch für die Markup-Entscheidung verantwortlich – nur Sie wissen, dass ein bestimmtes „Book“ ein Verb ist. Aber sobald Sie Ihre Quelle mit _x() und _ex() annotiert haben, wandelt eine kontextsensitive Pipeline diese Annotation in korrekte Übersetzungen für jede Zielsprache um, ohne dass eine Überwachung pro String erforderlich ist.
Fazit
Das Ambiguitätsproblem – ein englisches Wort, viele Bedeutungen – ist keine Marotte, die man ignorieren kann; es ist ein strukturelles Merkmal, wie Gettext Strings speichert. Die Lösung ist msgctxt: Annotieren Sie mehrdeutige Strings in Ihrer Quelle mit _x() und _ex(), geben Sie jedem Vorkommen ein klares Kontext-Label und lassen Sie Gettext die Übersetzung über das (context, msgid)-Paar schlüsseln. Dieser Teil liegt bei Ihnen, und er dauert nur wenige Minuten.
Der schwierigere Teil ist sicherzustellen, dass Ihr Übersetzungsschritt diesen Kontext tatsächlich berücksichtigt, anstatt ihn zu verwerfen. Naive Skripte und reine Text-KI-Tools verwerfen msgctxt und führen genau den Fehler wieder ein, den Sie zu verhindern versuchten. Eine kontextsensitive Pipeline liest den Kontext, übersetzt jeden disambiguierten Eintrag korrekt und bewahrt ihn durch Kompilierung und Re-Importe.
Bereit, kontextblinde Fehlübersetzungen zu vermeiden? Testen Sie SimplePoTranslate kostenlos – keine Kreditkarte erforderlich. Der kostenlose Tarif verarbeitet echte
.po- und.pot-Dateien mit voller msgctxt-Kontextunterstützung, sodass Ihre disambiguierten Strings beim ersten Mal korrekt übersetzt werden.