Wie man eine .pot-Datei für ein Theme oder Plugin erstellt

Sie haben gerade ein WordPress-Plugin fertiggestellt, das Sie mit der Welt teilen möchten. Der Code funktioniert, die Funktionen sind stabil, und jemand aus Deutschland fragt per E-Mail, wie man es ins Deutsche übersetzen kann. Sie verweisen sie auf den languages-Ordner und stellen fest, dass dort nichts ist. Keine Vorlage, keine Zeichenketten, keine Möglichkeit für einen Übersetzer, überhaupt zu wissen, was übersetzt werden muss. Ihr Plugin ist technisch gesehen nur dem Namen nach „übersetzungsbereit“.

Jedes übersetzbare WordPress-Projekt beginnt mit einer Datei: dem .pot-Template. Bevor jemand eine deutsche, französische oder japanische Version erstellen kann, müssen Sie eine POT-Datei erstellen, die jede für den Benutzer sichtbare Zeichenkette in Ihrem Code auflistet. Überspringen Sie diesen Schritt, und Übersetzer müssen Ihren Quelltext Zeile für Zeile lesen und raten, welche Zeichenketten überhaupt sichtbar sein sollen.

Dieser Leitfaden führt Sie durch die zwei Hälften der Aufgabe: die Vorbereitung Ihres Quellcodes, damit Zeichenketten auffindbar sind, und anschließend die Generierung der .pot selbst mit drei verschiedenen Tools. Wir werden WP-CLI, Poedit und den älteren makepot/grunt-Ansatz verwenden, mit echten Befehlen, die Sie kopieren können. Am Ende werden Sie eine saubere Vorlage haben, die Sie jedem Übersetzer aushändigen können.

Schritt Eins: Markieren Sie Ihre Zeichenketten als übersetzbar

Bevor Sie eine POT-Datei erstellen können, muss jede Zeichenkette, die ein Benutzer sehen könnte, in eine Gettext-Funktion eingeschlossen werden. Ein Scanner kann nur Zeichenketten extrahieren, die er erkennt, und er erkennt sie anhand dieser Funktionsaufrufe – einfache String-Literale sind für ihn unsichtbar.

WordPress bietet eine Familie von Lokalisierungsfunktionen, jede für einen etwas anderen Kontext:

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

Das zweite Argument in jedem Aufruf – 'my-plugin' – ist die Textdomäne. Es gruppiert alle Zeichenketten eines Plugins oder Themes unter einem Namespace, damit WordPress weiß, welche .mo-Datei für sie geladen werden soll. Jede übersetzbare Zeichenkette in Ihrem Projekt muss exakt dieselbe Textdomäne teilen, sonst werden einige Zeichenketten niemals übersetzt.

Verwenden Sie _x(), wann immer ein Wort mehrdeutig ist. Das englische „Post“ kann ein Substantiv oder ein Verb sein, und viele Sprachen übersetzen sie unterschiedlich. Kontext-Strings helfen Übersetzern, sie zu unterscheiden. Und greifen Sie zu den Varianten esc_html__() und esc_attr__(), wann immer die übersetzte Zeichenkette in HTML ausgegeben wird, damit Sie gleichzeitig sicher und lokalisiert bleiben.

Es gibt ein paar Gewohnheiten, die Ihre Zeichenketten extrahierbar halten. Geben Sie immer ein einfaches String-Literal als erstes Argument an – niemals eine Variable oder eine Verkettung wie __( 'Hello ' . $name, 'my-plugin' ), da der Scanner den Quelltext statisch liest und Laufzeitwerte nicht auflösen kann. Für Sätze mit einer Zahl verwenden Sie _n(), damit Pluralformen korrekt erfasst werden, und für Sätze mit einem dynamischen Wert verwenden Sie sprintf() um einen Platzhalter wie %s anstatt Zeichenketten zusammenzukleben. Konsistenz ist hier das, was den nächsten Schritt – die Generierung des Templates – ein vollständiges, brauchbares Ergebnis liefern lässt.

Schritt Zwei: Deklarieren Sie die Textdomäne in Ihrem Header

WordPress benötigt zwei Header-Felder, um zu wissen, wo Ihre Übersetzungen liegen: die Textdomäne und der Domain Path. Setzen Sie diese in der Hauptdatei Ihres Plugins oder der style.css Ihres Themes, und WordPress lädt zur Laufzeit automatisch die richtige .mo-Datei.

<?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
 */

Die Textdomäne muss mit der Zeichenkette übereinstimmen, die Sie an jeden __()- und _e()-Aufruf übergeben haben – hier my-plugin. Der Domain Path teilt WordPress mit, welcher Unterordner die Übersetzungsdateien enthält, relativ zum Plugin- oder Theme-Root. Die Konvention ist /languages, und genau dort sollte Ihre generierte .pot liegen.

Mit eingeschlossenen Zeichenketten und deklariertem Header ist Ihr Code bereit zum Scannen. Das umfassendere Bild der Vorbereitung eines Projekts für die Übersetzung – einschließlich Themes, die nicht Ihre eigenen sind – wird unter how to localize any WordPress theme even if you are not a developer behandelt.

Wie generiert man die .pot-Datei? Drei Methoden

Sie generieren eine .pot, indem Sie einen Scanner über Ihren Quellcode laufen lassen, der jeden Gettext-Aufruf findet und die Zeichenketten in eine Vorlage schreibt. Hier sind drei zuverlässige Methoden, dies zu tun, vom modernen Standard bis zum älteren Ansatz.

Methode 1: WP-CLI (Empfohlen)

Die offizielle, moderne Art, eine POT-Datei zu erstellen, ist WP-CLI mit dem Befehl i18n. Es ist Teil der WordPress-Core-Tools, versteht PHP- und JavaScript-Zeichenketten und erstellt eine standardkonforme Vorlage in einer Zeile.

# 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

Das erste Argument ist das Quellverzeichnis (. für den aktuellen Ordner), und das zweite ist der Ausgabepfad. WP-CLI durchsucht Ihre Dateien, extrahiert jede eingeschlossene Zeichenkette, zeichnet die Quelldatei und Zeilennummer als Kommentar auf und schreibt die .pot. Es ist schnell, skriptfähig und die richtige Wahl für jedes ernsthafte Projekt.

Das generierte Template enthält hilfreiche Metadaten, die Sie mit zusätzlichen Flags anpassen können. Übergeben Sie --headers, um den Projektnamen, die Version und die Kontaktadresse der Übersetzer festzulegen, damit der .pot-Header-Block korrekt ausgefüllt wird und nicht als Platzhalter bleibt. WP-CLI extrahiert auch automatisch JavaScript-Zeichenketten aus wp_set_script_translations()-Aufrufen, was für moderne Block-Themes und Gutenberg-Plugins wichtig ist, wo die Hälfte des benutzerseitigen Textes in JavaScript statt in PHP liegt. Ein Befehl deckt beide Welten ab.

Methode 2: Poedit (Grafisch)

Wenn Sie eine Desktop-App bevorzugen, kann Poedit Ihren Quellcode scannen und die Vorlage über seine Oberfläche generieren. Öffnen Sie Poedit, wählen Sie, ob Sie eine neue Übersetzung aus POT erstellen oder Quellen direkt scannen möchten, zeigen Sie auf Ihren Projektordner und konfigurieren Sie die Quell-Keywords (__, _e, _x, esc_html__) unter den Katalogeigenschaften.

Die Quellcode-Scan- und .pot-Generierungsfunktionen von Poedit sind in der Pro-Edition enthalten, aber der Workflow ist benutzerfreundlich für Entwickler, die lieber klicken als Befehle tippen. Es ist auch ein solider Editor für die anschließende Übersetzungsphase. Poedit und mehrere andere Desktop-Optionen werden in top 5 free tools to edit and translate PO files on Mac and Windows verglichen.

Methode 3: makepot / grunt (Veraltet)

Vor WP-CLI war das Standardwerkzeug das Skript makepot.php aus dem WordPress i18n-tools Repository, oft in eine Grunt-Build-Aufgabe mit grunt-wp-i18n eingebunden. Sie werden es immer noch in älteren Plugins und Themes finden.

# Legacy makepot.php invocation
php makepot.php wp-plugin /path/to/my-plugin languages/my-plugin.pot

Es funktioniert, aber es wird im Vergleich zu WP-CLI nicht mehr gepflegt und ist langsamer einzurichten. Verwenden Sie es nur, wenn Sie ein älteres Projekt pflegen, das bereits davon abhängt; für alles Neue bevorzugen Sie wp i18n make-pot.

Halten Sie das Template auf dem neuesten Stand, wenn sich Ihr Code ändert

Eine .pot ist eine Momentaufnahme Ihrer Zeichenketten zu einem bestimmten Zeitpunkt. Jedes Mal, wenn Sie eine Funktion hinzufügen, eine Beschriftung ändern oder einen Tippfehler in einer sichtbaren Zeichenkette beheben, veraltet das Template, und Übersetzer übersehen die neue Formulierung.

Machen Sie die Neuerstellung zu einem Teil Ihrer Release-Routine. Führen Sie wp i18n make-pot vor jedem Versionssprung erneut aus, und führen Sie dann das aktualisierte Template mit wp i18n update-po oder msgmerge in bestehende Übersetzungen zusammen, damit Übersetzer ihre fertige Arbeit behalten und nur die neuen Lücken sehen. Behandeln Sie die .pot als ein Build-Artefakt, das Sie neu generieren, nicht als eine Datei, die Sie manuell bearbeiten.

Ein veraltetes Template führt zu einem subtilen, frustrierenden Fehler: Neue Zeichenketten erscheinen auf Englisch, selbst auf einer „vollständig übersetzten“ Website, weil sie nie in der .pot enthalten waren, mit der der Übersetzer gearbeitet hat. Dies zu erkennen ist so einfach wie das Skripten der Neuerstellung in Ihren Build, damit das Template niemals hinter dem Code zurückbleibt. Einige Teams fügen eine CI-Prüfung hinzu, die den Build fehlschlagen lässt, wenn die Neuerstellung der .pot einen Unterschied erzeugt, wodurch garantiert wird, dass das übergebene Template immer mit der aktuellen Quelle übereinstimmt.

Sobald Übersetzer fertige .po-Dateien zurücksenden, müssen diese noch in das binäre .mo-Format kompiliert werden, das WordPress tatsächlich lädt – und wenn Sie den gesamten Download-Übersetzen-Neukompilieren-Kreislauf lieber überspringen möchten, kann ein Cloud-Tool dies von A bis Z erledigen. SimplePoTranslate akzeptiert Ihre .pot direkt, übersetzt sie mit kontextsensitiver KI, die versteht, was jede Zeichenkette in Ihrer Oberfläche bedeutet, und gibt eine einzige ZIP-Datei mit den bereits erstellten und benannten .po, .mo und mehr zurück. Sein Syntax Locking fixiert Platzhalter wie %s und %1$s, damit Ihre Variablen bei der Übersetzung niemals kaputtgehen.

Zusammenfassung

Um eine POT-Datei richtig zu erstellen, machen Sie Ihren Code zuerst auffindbar – schließen Sie jede sichtbare Zeichenkette in __(), _e(), _x() oder eine Escaping-Variante ein, die alle eine Textdomäne teilen, und deklarieren Sie diese Domäne sowie den Domain Path in Ihrem Header. Generieren Sie dann das Template mit WP-CLI für neue Projekte, Poedit, wenn Sie eine GUI bevorzugen, oder makepot nur bei der Pflege von Legacy-Code.

Generieren Sie früh, generieren Sie oft neu, und lassen Sie Ihr Template niemals hinter Ihrem Code zurückfallen. Eine aktuelle .pot ist der Unterschied zwischen einem Plugin, das wirklich bereit für die Welt ist, und einem, das es nur vorgibt zu sein.

Bereit, Ihr .pot-Template ohne das manuelle Kompilieren in fertige Übersetzungen zu verwandeln? Testen Sie SimplePoTranslate kostenlos – keine Kreditkarte erforderlich. Laden Sie Ihr Template im kostenlosen Tarif hoch und laden Sie versandfertige Übersetzungsdateien in wenigen Minuten herunter.