So übersetzen Sie ein WordPress-Plugin (Schritt für Schritt)

Sie haben das perfekte WordPress-Plugin für Ihr Projekt gefunden. Es tut genau das, was Sie brauchen, die Bewertungen sind hervorragend, und dann aktivieren Sie es und stellen fest, dass jede Schaltfläche, jedes Label und jede Fehlermeldung auf Englisch ist. Ihre deutschen, französischen oder japanischen Besucher stehen kurz davor, auf eine Textwand zu stoßen, die sie nicht lesen können.

Die gute Nachricht ist, dass die meisten gut gebauten Plugins übersetzungsbereit sind. Das bedeutet, der Entwickler hat seine Strings in Gettext-Funktionen verpackt, damit Leute wie Sie sie übersetzen können. Die Herausforderung besteht darin, zu wissen, wo die Dateien liegen, wie Ihre Übersetzung zu benennen ist und wo Sie sie ablegen müssen, damit das nächste Plugin-Update Ihre Arbeit nicht zunichtemacht.

Dieser Leitfaden zeigt Ihnen, wie Sie ein WordPress-Plugin übersetzen – von Anfang bis Ende: das Finden der Textdomäne und des Sprachordners, das Abrufen oder Generieren der .pot-Vorlage, das Erstellen korrekt benannter .po- und .mo-Dateien und deren Platzierung, damit WordPress sie zuverlässig lädt. Wir behandeln auch den einen Plugin-Typ, den dieser Ansatz nicht vollständig übersetzen kann, damit Sie nicht stundenlang einen unmöglichen Fall bekämpfen.

Wie finden Sie die Übersetzungsdateien eines Plugins?

Bevor Sie etwas übersetzen, benötigen Sie zwei Informationen vom Plugin: seine Textdomäne und seinen Sprachordner (languages folder). Die Textdomäne ist die eindeutige Zeichenkette, die das Plugin verwendet, um seine eigenen Übersetzungen zu identifizieren, und der Sprachordner ist der Ort, an dem die Quellvorlage liegt.

Den Sprachordner und die Textdomäne finden

Öffnen Sie das Plugin-Verzeichnis unter wp-content/plugins/your-plugin/ und suchen Sie nach einem /languages-Unterordner. Dort finden Sie normalerweise eine .pot-Datei, die leere Vorlage, die jede übersetzbare Zeichenkette enthält.

Um die Textdomäne zu bestätigen, öffnen Sie die Haupt-PHP-Datei des Plugins und sehen Sie sich den Header-Block an:

/**
 * Plugin Name: Awesome Plugin
 * Text Domain: awesome-plugin
 * Domain Path: /languages
 */

Hier ist die Textdomäne awesome-plugin. Dieser Wert ist entscheidend, da Ihre Übersetzungsdateien ihn in ihren Namen enthalten müssen, sonst wird WordPress sie niemals dem Plugin zuordnen. Sie werden ihn auch in jedem String-Aufruf im gesamten Code sehen:

echo __( 'Settings saved successfully.', 'awesome-plugin' );

Dieses zweite Argument, awesome-plugin, ist wieder die Textdomäne. Jede Zeichenkette, die sie verwendet, kann durch Ihren Katalog übersetzt werden. Wenn einer Zeichenkette in der Plugin-Oberfläche dieser Wrapper fehlt, zum Beispiel wenn ein Entwickler echo 'Save' ohne __() hartcodiert hat, dann ist diese Zeichenkette überhaupt nicht übersetzbar, und keine .po-Datei kann sie erreichen. Die meisten seriösen Plugins umschließen alles korrekt, aber wenn Sie ein oder zwei hartnäckige Zeichenketten bemerken, die sich weigern zu übersetzen, ist ein fehlender Gettext-Wrapper in der Quelle ein wahrscheinlicher Übeltäter.

Eine schnelle Methode, um zu beurteilen, ob ein Plugin wirklich übersetzungsbereit ist, besteht darin, dessen Eintrag im WordPress.org-Verzeichnis zu überprüfen, der einen Übersetzungsanteil anzeigt und Links zu einer /languages-Vorlage enthält. Ein Plugin mit einem aktiven Übersetzungsprojekt hat weitaus eher saubere, vollständig umschlossene Zeichenketten als ein verlassenes.

Was, wenn das Plugin keine POT-Datei hat?

Einige Plugins werden ohne .pot-Vorlage ausgeliefert. Wenn der /languages-Ordner leer ist oder fehlt, müssen Sie die Vorlage selbst generieren, indem Sie den Quellcode nach übersetzbaren Zeichenketten durchsuchen.

Das Standardwerkzeug hierfür ist WP-CLI, das jeden Gettext-Aufruf in eine neue .pot extrahiert.

wp i18n make-pot wp-content/plugins/awesome-plugin \
  wp-content/plugins/awesome-plugin/languages/awesome-plugin.pot

Dieser Befehl durchsucht die PHP- und JavaScript-Dateien des Plugins, findet jeden __(), _e(), _n() und verwandten Aufruf und schreibt eine vollständige Vorlage. Wenn Sie eine grafische Route bevorzugen, kann Poedit Pro den Quellcode auf die gleiche Weise scannen. In beiden Fällen ist das Ergebnis eine .pot, die alle Quellstrings mit leeren Übersetzungen enthält, bereit, in eine echte Sprachdatei umgewandelt zu werden.

Das Generieren einer eigenen Vorlage hat einen versteckten Vorteil: Es erfasst Zeichenketten, die der ursprüngliche Entwickler möglicherweise vergessen hat, in eine ausgelieferte .pot aufzunehmen. Plugins entwickeln sich schnell, und eine Vorlage, die mit Version 2.1 kam, könnte Zeichenketten fehlen, die in 2.4 hinzugefügt wurden. Das Regenerieren aus der aktuellen Quelle garantiert, dass Ihr Katalog das widerspiegelt, was das Plugin tatsächlich heute anzeigt, nicht das, was es vor zwei Veröffentlichungen angezeigt hat. Wenn Sie über einen längeren Zeitraum Übersetzungen für ein Plugin pflegen, ist das erneute Ausführen von make-pot nach jedem größeren Update eine zuverlässige Gewohnheit.

Erstellen der PO- und MO-Dateien mit dem richtigen Namen

Der häufigste Fehler beim Übersetzen eines Plugins ist der Dateiname. WordPress findet Plugin-Übersetzungen, indem es ein sehr spezifisches Muster abgleicht, und ein falsches Zeichen bedeutet, dass Ihre Übersetzung vollständig ignoriert wird.

Die Dateinamen-Formel

Für Plugin-Übersetzungen lautet das Muster text-domain-locale. Für die awesome-plugin Textdomäne, übersetzt ins Deutsche, müssen die Dateien also wie folgt benannt werden:

awesome-plugin-de_DE.po
awesome-plugin-de_DE.mo

Der Ländercode (Locale Code) ist der WordPress-Sprachcode der Website: de_DE für Deutsch, fr_FR für Französisch, es_ES für Spanisch, pt_BR für brasilianisches Portugiesisch. Wenn der Ländercode falsch ist, überspringt WordPress Ihre Datei stillschweigend. Sie erstellen diese aus der .pot-Vorlage in einem Editor wie Poedit, der die binäre .mo automatisch beim Speichern kompiliert. Wenn Sie neu in diesem Editor sind, führt der vollständige Poedit-Leitfaden Sie Schritt für Schritt durch die Erstellung einer Übersetzung aus einer Vorlage.

Wo die Dateien platziert werden, damit Updates sie nicht löschen

Es gibt zwei mögliche Speicherorte, und die Wahl des richtigen ist entscheidend.

# RISKY: inside the plugin — wiped on every plugin update
wp-content/plugins/awesome-plugin/languages/awesome-plugin-de_DE.mo

# SAFE: the global languages override folder — survives updates
wp-content/languages/plugins/awesome-plugin-de_DE.mo

Verwenden Sie immer wp-content/languages/plugins/. WordPress prüft dieses Überschreibungsverzeichnis zuerst, und da es außerhalb des Plugin-Ordners liegt, berührt das Aktualisieren des Plugins Ihre Übersetzungen niemals. Dateien, die sich im eigenen Ordner des Plugins befinden, werden in dem Moment überschrieben, in dem eine neue Version installiert wird.

Dieses Überschreibungsverhalten ist eine der nützlichsten und am wenigsten bekannten Funktionen der WordPress-Lokalisierung. Es bedeutet, dass Sie benutzerdefinierte oder korrigierte Übersetzungen für jedes Drittanbieter-Plugin bereitstellen können, ohne es jemals zu forken, und Ihre Änderungen sind vollständig update-sicher. Wenn Sie mehrere Client-Websites mit demselben Plugin verwalten, können Sie sogar einen einzigen Satz von Überschreibungs-.mo-Dateien aufbewahren und diese auf alle Sites verteilen, wissend, dass jede Site sie automatisch übernimmt, solange der Ländercode übereinstimmt.

Wie WordPress Ihre Übersetzung lädt

Ein übersetzungsbereites Plugin weist WordPress an, seinen Katalog während der Initialisierung durch den Aufruf von load_plugin_textdomain() zu laden:

add_action( 'init', function() {
    load_plugin_textdomain(
        'awesome-plugin',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages'
    );
} );

Für die meisten modernen Plugins unter WordPress 4.6 und höher müssen Sie dies nicht anfassen. WordPress lädt Übersetzungen automatisch aus wp-content/languages/plugins/, solange Ihr Dateiname und der Ländercode der Website übereinstimmen. Wenn Ihre fertige Übersetzung immer noch nicht angezeigt wird, ist die Ursache fast immer eine Dateinamensinkonsistenz, eine veraltete .mo-Datei oder eine auf den falschen Ländercode eingestellte Site-Sprache. Unser Leitfaden zur Fehlerbehebung, wenn Ihre Übersetzungen in WordPress nicht angezeigt werden, behandelt jeden dieser Fehlerpunkte.

Plugins, die Strings in der Datenbank speichern

Hier ist die wichtige Einschränkung. Der Gettext-Ansatz übersetzt nur Zeichenketten, die im Code des Plugins liegen. Einige Plugins, insbesondere Formular-Builder, Page-Builder und E-Commerce-Erweiterungen, ermöglichen es Ihnen, Inhalte (Formularbeschriftungen, Produktattribute, benutzerdefinierte Nachrichten) zu erstellen, die in der WordPress-Datenbank gespeichert werden. Diese Zeichenketten sind benutzergenerierte Daten, nicht Teil der .pot-Datei, daher kann eine .po-Datei sie nicht erreichen. Für Datenbankinhalte benötigen Sie ein mehrsprachiges Plugin wie WPML oder Polylang oder die eigene String-Übersetzungsfunktion des Plugins. Testen Sie immer, ob eine bestimmte Zeichenkette im Code oder in der Datenbank gespeichert ist, bevor Sie annehmen, dass eine .po-Datei sie beheben kann.

Ein einfacher Test sagt Ihnen, mit welcher Art von Zeichenkette Sie es zu tun haben. Wenn der Text etwas ist, das Sie in ein Einstellungsfeld eingegeben haben, eine Formularbeschriftung, die Sie erstellt haben, eine benutzerdefinierte Dankesnachricht, ein Produktname, dann ist es Datenbankinhalt und eine .po-Datei kann ihn nicht berühren. Wenn der Text Teil der integrierten Benutzeroberfläche des Plugins ist, Schaltflächenbeschriftungen, Validierungsfehler, Admin-Hinweise, die mit dem Plugin selbst geliefert werden, dann liegt er im Code und eine .po-Datei ist genau das richtige Werkzeug. Diese Abgrenzung frühzeitig zu ziehen, spart Stunden der Frustration, denn selbst die perfekte Bearbeitung einer .po-Datei wird niemals eine Zeichenkette übersetzen, die das Plugin zur Laufzeit aus der Datenbank zieht.

Übersetzen im großen Stil ohne manuelle Plackerei

Ein Plugin manuell in eine Sprache zu übersetzen ist machbar. Es in zehn Sprachen zu übersetzen oder eine ganze Reihe von Plugins für eine Client-Site zu übersetzen, wird zu tagelanger, repetitiver Arbeit, und jede manuelle Bearbeitung birgt das Risiko, einen Platzhalter wie %s oder %1$s falsch zu handhaben und die Ausgabe zu beschädigen.

Hier ändert ein Cloud-Workflow die Rechnung. Laden Sie die .po- oder .pot-Datei des Plugins auf SimplePoTranslate hoch, wählen Sie Ihre Zielsprachen aus, und kontextbewusste KI übersetzt den gesamten Katalog, während Syntax Locking jeden Platzhalter, HTML-Tag und Code-Token einfriert, sodass nichts kaputtgehen kann. Smart Batching verarbeitet große Kataloge in einem einzigen Durchgang, und Sie laden ein ZIP-Archiv herunter, das .po, .mo, .json, .php und .xliff zusammen enthält, korrekt formatiert und bereit, in wp-content/languages/plugins/ abgelegt zu werden. Es läuft vollständig in der Cloud, sodass keine Desktop-Installation und kein Bloat auf Ihrer Website erforderlich sind.

Beachten Sie, dass das Übersetzen eines Plugins sich vom Übersetzen eines Themes unterscheidet, da letzteres eine leicht abweichende Ordnerkonvention und Ladefunktion verwendet. Wenn ein Theme Ihr Ziel ist, folgen Sie stattdessen unserem speziellen Leitfaden zur Lokalisierung jedes WordPress-Themes, auch wenn Sie kein Entwickler sind.

Nutzen Sie den manuellen Weg, wenn Sie ein Plugin und eine Sprache haben. Nutzen Sie die Cloud, wenn Sie viele Sprachen schnell benötigen, ohne die Platzhaltersicherheit zu opfern.

Bereit, Ihr WordPress-Plugin in jede Sprache zu übersetzen, die Ihr Publikum spricht, ohne eine einzige Variable zu beschädigen? Probieren Sie SimplePoTranslate kostenlos aus – keine Kreditkarte erforderlich. Die kostenlose Stufe ermöglicht es Ihnen, Ihre erste Plugin-.po-Datei in wenigen Minuten zu übersetzen, mit Syntax Locking auf jeder Zeichenkette.