Dokumentation · Technische Dokumentation

Internationalisierung und Poedit

Dieses Dokument erklärt, wie das ADP Car Market Hub-Plugin Übersetzungen handhabt, wo die Sprachdateien liegen und wie Übersetzungen mit Poedit (oder einem anderen kompatiblen Gettext-Editor) aktualisiert oder hinzugefügt werden.

Wann Sie dieses Dokument verwenden sollten

Lesen Sie dieses Dokument, wenn Sie:

Das Plugin in eine neue Sprache übersetzen möchten.
Eine bestehende Übersetzung nach einem Plugin-Upgrade aktualisieren möchten.
Überprüfen möchten, welche Locales mitgeliefert und wie sie geladen werden.
Fehler bei Zeichenketten beheben möchten, die im Admin-Bereich oder im Frontend unübersetzt erscheinen.

Übersicht

Das Plugin nutzt die standardmäßigen WordPress-Internationalisierungsmechanismen (i18n):

Alle übersetzbaren Zeichenketten sind in Gettext-Funktionen (__(), _e(), _n(), _x() usw.) unter Verwendung der Textdomain adp-car-market-hub gekapselt.
Übersetzungen werden aus dem Ordner languages/ des Plugins über load_plugin_textdomain() bei plugins_loaded mit der Priorität 1 geladen, bevor benutzerseitige Zeichenketten gerendert werden.
Eine POT-Vorlage (adp-car-market-hub.pot) wird mit dem Plugin ausgeliefert und kann mit Poedit oder WP-CLI geöffnet oder neu generiert werden.

Die Textdomain entspricht dem Plugin-Ordner-Slug (adp-car-market-hub), sodass Übersetzungen aus Toolchains im Stil von translate.wordpress.org automatisch erkannt werden, wenn sie an den Standard-Speicherorten abgelegt werden.

Dateien in `languages/`

Der mitgelieferte Ordner languages/ enthält:

adp-car-market-hub.pot — Übersetzungsvorlage, generiert durch i18n make-pot von WP-CLI (sichtbar im POT-Header).
adp-car-market-hub-de_DE.po — Deutsch (Deutschland).
adp-car-market-hub-de_DE_formal.po / adp-car-market-hub-de_DE_formal.mo — Deutsch (Sie-Form).
adp-car-market-hub-de_AT.po — Deutsch (Österreich).
adp-car-market-hub-de_CH.po — Deutsch (Schweiz).
adp-car-market-hub-fr_FR.po — Französisch (Frankreich).
adp-car-market-hub-it_IT.po — Italienisch (Italien).

Überprüfen Sie die genaue Liste der .po- und .mo-Dateien in der aktuellen Plugin-Version, bevor Sie kundenrelevante Texte veröffentlichen. WordPress lädt die .mo-Datei, die zur aktiven Website-Locale passt; .po-Dateien allein reichen zur Laufzeit nicht aus.

Anforderungen oder Voraussetzungen

Ein Gettext-Editor — Poedit ist das empfohlene GUI-Tool. Die kostenlose Version ist ausreichend.
Optional: WP-CLI mit dem Befehl i18n, um die POT-Datei aus dem Quellcode neu zu generieren.
Schreibzugriff auf den Ordner languages/ des Plugins (oder einen Override-Speicherort, siehe unten).

Schritt-für-Schritt-Anleitung

In eine neue Locale übersetzen

Öffnen Sie Poedit und wählen Sie Datei → Neu aus POT/PO-Vorlage....
Wählen Sie languages/adp-car-market-hub.pot aus.
Wählen Sie die Ziel-Locale aus. Speichern Sie die Datei als adp-car-market-hub-<locale>.po im selben Ordner languages/, wobei <locale> der WordPress-Sprachcode ist (zum Beispiel es_ES, nl_NL).
Übersetzen Sie die Zeichenketten im Editor.
Speichern Sie. Poedit schreibt automatisch eine passende .mo-Datei neben der .po-Datei.
Stellen Sie die WordPress-Website-Sprache auf Ihre neue Locale ein und laden Sie die Admin- und Frontend-Seiten neu, um die Übersetzungen zu überprüfen.

Eine bestehende Übersetzung nach einem Plugin-Upgrade aktualisieren

Öffnen Sie die vorhandene .po-Datei in Poedit.
Wählen Sie Katalog → Aus POT-Datei aktualisieren... und wählen Sie die neue adp-car-market-hub.pot aus.
Übersetzen Sie alle neuen oder geänderten Zeichenketten (Poedit markiert diese als unübersetzt oder ungenau/fuzzy).
Speichern Sie. Die .mo-Datei wird automatisch neu generiert.

Die POT-Vorlage aus dem Quellcode neu generieren (optional)

Wenn Sie den Plugin-Quellcode pflegen und die POT-Vorlage selbst aktualisieren müssen, können Sie dies mit WP-CLI tun:

wp i18n make-pot . languages/adp-car-market-hub.pot --domain=adp-car-market-hub

Führen Sie dies im Stammverzeichnis des Plugins aus. Der Datei-Header dokumentiert die WP-CLI-Version, mit der sie erstellt wurde.

Übersetzungen außerhalb des Plugin-Ordners verwenden

WordPress sucht auch in wp-content/languages/plugins/adp-car-market-hub-<locale>.mo nach Übersetzungen. Legen Sie dort eine benutzerdefinierte .mo-Datei ab, wenn Sie möchten, dass Übersetzungen Plugin-Upgrades überstehen, bei denen languages/ überschrieben wird.

Betriebliche Hinweise

Die Textdomain wird mit der Priorität plugins_loaded bei 1 geladen, was absichtlich vor dem Ausführen des Haupt-init()-Callbacks des Plugins bei der Standardpriorität geschieht. Dies stellt sicher, dass jede später registrierte übersetzbare Zeichenkette bereits Zugriff auf die geladene .mo-Datei hat.
Speichern Sie die .po-Datei nach dem Bearbeiten immer mit Poedit neu (oder kompilieren Sie die .mo-Datei mit msgfmt) — WordPress liest zur Laufzeit die binäre .mo-Datei, nicht die textbasierte .po-Datei.
Bei Sprachcodes wird auf Dateisystemen mit Unterscheidung zwischen Groß- und Kleinschreibung auf die exakte Schreibweise geachtet. Verwenden Sie den genauen WordPress-Locale-Identifikator.
Übersetzungs-Updates sollten keine Quelldateien verändern; diese Dokumentationsaufgabe schließt diese explizit aus.
Einige Zeichenketten (zum Beispiel Provider-Modell-Identifikatoren im KI-Assistenten oder technische Optionsbezeichnungen) verbleiben absichtlich auf Englisch. Übersetzen Sie die für den Benutzer sichtbaren Texte und lassen Sie Identifikatoren unverändert.

Fehlerbehebung

Eine Zeichenkette wird immer noch auf Englisch angezeigt — stellen Sie sicher, dass eine .mo-Datei für die aktive Locale in languages/ (oder in wp-content/languages/plugins/) existiert, die Datei mit der Textdomain des Plugins (adp-car-market-hub) übereinstimmt und Ihre WordPress-Website-Sprache korrekt eingestellt ist.
Eine neue Übersetzung wird erst nach dem Leeren des Caches geladen — einige Object-Cache-Plugins zwischenspeichern Übersetzungen. Leeren Sie den WordPress-Objekt-Cache nach dem Bereitstellen neuer .mo-Dateien.
Poedit zeigt nach einem Update viele ungenaue (fuzzy) Zeichenketten an — dies ist zu erwarten, wenn sich der Quelltext ändert. Überprüfen Sie jeden ungenauen Eintrag, korrigieren Sie die Übersetzung und entfernen Sie die Markierung „ungenau“.
Benutzerdefinierte Übersetzungen werden durch Plugin-Updates überschrieben — speichern Sie benutzerdefinierte Übersetzungen in wp-content/languages/plugins/ statt im languages/-Ordner des Plugins.