Dokumentation · Integrationshandbuch

Übersetzungs- und Poedit-Anleitung

Dieses Dokument erklärt, wie das ADP Car Market Hub-Plugin mit mehrsprachigen WordPress-Websites umgeht, welche Übersetzungsdateien mit dem Plugin geliefert werden und wie Sie Plugin-Texte mit Poedit oder gleichwertigen Tools übersetzen oder aktualisieren.

Wann Sie dieses Dokument verwenden sollten

Verwenden Sie dieses Dokument, wenn Sie:

Das Plugin auf einer Website einrichten, deren WordPress-Sprache nicht Englisch ist, und sicherstellen möchten, dass die Übersetzungen geladen werden.
Als Garage oder Agentur Übersetzungen für eine bereits im Plugin enthaltene Sprache hinzufügen oder korrigieren möchten.
Als Entwickler eine neue Sprachdatei für ein Gebietsschema beisteuern möchten, das noch nicht im Plugin enthalten ist.
Fehler beheben möchten, wenn Plugin-Texte auf Englisch erscheinen, obwohl die Website-Sprache auf ein anderes Gebietsschema eingestellt ist.

Die Zielgruppe ist ein WordPress-Administrator oder ein Entwickler, der mit dem WordPress-Internationalisierungs-Workflow und der grundlegenden Nutzung der Befehlszeile vertraut ist.

Übersicht

Das Plugin verwendet den standardmässigen WordPress-Lokalisierungsmechanismus. Alle für den Benutzer sichtbaren Texte im PHP-Code des Plugins sind in WordPress-Übersetzungsfunktionen (__(), _e(), esc_html__() und ähnliche) mit der Textdomain adp-car-market-hub verpackt. WordPress lädt die entsprechende Übersetzungsdatei aus dem Ordner languages/ des Plugins, wenn die Website-Sprache unter Einstellungen → Allgemein → Sprache der Website eingestellt ist.

Die folgenden Sprachdateien sind zum Zeitpunkt der Erstellung dieses Dokuments im Plugin enthalten:

Gebietsschema-Code	Sprache
`de_AT`	Deutsch (Österreich)
`de_CH`	Deutsch (Schweiz)
`de_DE`	Deutsch (Deutschland)
`de_DE_formal`	Deutsch (Deutschland, formelle Anrede)
`fr_FR`	Französisch (Frankreich)
`it_IT`	Italienisch (Italien)
`es_ES`	Spanisch (Spanien)
`nl_NL`	Niederländisch (Niederlande)

Überprüfen Sie die aktuelle Liste, indem Sie das Verzeichnis languages/ im Plugin-Ordner (wp-content/plugins/adp-car-market-hub/languages/) kontrollieren. Jedes Gebietsschema verfügt über eine .po-Quelldatei (vom Menschen bearbeitbar). Wenn eine kompilierte .mo-Datei vorhanden ist, ist dies die Datei, die WordPress tatsächlich zur Laufzeit lädt.

Wenn die Website mit einem Gebietsschema betrieben wird, das nicht in der obigen Liste aufgeführt ist, zeigt das Plugin alle Texte in der Fallback-Sprache an, die Englisch ist.

Voraussetzungen

WordPress-Administratorzugriff.
Zum Bearbeiten von Übersetzungen: Poedit (https://poedit.net/) oder ein gleichwertiger Editor für .po- / .mo-Dateien oder das WordPress-Plugin Loco Translate (https://wordpress.org/plugins/loco-translate/).
Zum Erstellen einer neuen POT-Datei: WP-CLI Version 2.6 oder höher oder das make-pot.sh-Skript in bin/make-pot.sh.
Zum Kompilieren von .mo-Dateien über die Befehlszeile: das GNU gettext-Hilfsprogramm msgfmt oder der Befehl wp i18n make-mo von WP-CLI.

Wie das Plugin Übersetzungen lädt

Das Plugin ruft load_plugin_textdomain() bei der Aktion plugins_loaded mit Priorität 1 auf. Dies bedeutet, dass die Übersetzungsdatei für die aktuelle Website-Sprache geladen wird, bevor anderer Plugin-Code mit der Standardpriorität ausgeführt wird, sodass alle Admin- und Frontend-Texte ab dem Moment der Plugin-Initialisierung für die Übersetzung verfügbar sind.

WordPress sucht die Sprachdatei in der folgenden Reihenfolge:

wp-content/languages/plugins/adp-car-market-hub-{locale}.mo (Übersetzungsdateien, die von WordPress selbst oder von einem Übersetzungsverwaltungstool installiert wurden).
wp-content/plugins/adp-car-market-hub/languages/adp-car-market-hub-{locale}.mo (mit dem Plugin gelieferte Dateien).

Dateien in wp-content/languages/plugins/ haben Priorität. Wenn Sie eine mitgelieferte Übersetzung mit einem Plugin wie Loco Translate aktualisieren, wird die aktualisierte Datei normalerweise im ersten Pfad gespeichert, was Ihre Änderungen vor dem Überschreiben bei Plugin-Updates schützt.

Schritt-für-Schritt-Anleitung

Verwendung einer vorhandenen mitgelieferten Übersetzung

Öffnen Sie in WordPress Einstellungen → Allgemein.
Stellen Sie die Sprache der Website auf das gewünschte Gebietsschema ein (zum Beispiel Deutsch (Schweiz) für de_CH).
Speichern Sie die Einstellungen.
Navigieren Sie zu einer beliebigen Admin-Seite des Plugins oder rufen Sie das Fahrzeugarchiv im Frontend auf. Die Plugin-Texte (Labels, Buttons, Fehlermeldungen) sollten in der ausgewählten Sprache erscheinen.
Wenn Texte weiterhin auf Englisch erscheinen, lesen Sie den Abschnitt Fehlerbehebung weiter unten.

Bearbeiten oder Korrigieren einer vorhandenen Übersetzung mit Poedit

Laden Sie Poedit von https://poedit.net/. herunter und installieren Sie es.
Suchen Sie die .po-Datei für das Gebietsschema, das Sie bearbeiten möchten, im Verzeichnis languages/ des Plugins. Zum Beispiel: wp-content/plugins/adp-car-market-hub/languages/adp-car-market-hub-de_CH.po.
Öffnen Sie die .po-Datei in Poedit.
Suchen Sie den Text, den Sie ändern möchten, in der Textliste. Die Spalte Quelltext zeigt das englische Original und die Spalte Übersetzung zeigt den aktuellen übersetzten Wert. Klicken Sie auf eine Zeile, um die Übersetzung im Bearbeitungsbereich darunter zu bearbeiten.
Speichern Sie die Datei. Poedit kompiliert automatisch die entsprechende .mo-Datei im selben Verzeichnis.
Empfohlen: Kopieren Sie die aktualisierten Dateien .po und .mo nach wp-content/languages/plugins/, damit Plugin-Updates sie nicht überschreiben: - wp-content/languages/plugins/adp-car-market-hub-de_CH.po - wp-content/languages/plugins/adp-car-market-hub-de_CH.mo
Löschen Sie allfällige WordPress-Caches, die veraltete Ausgaben liefern könnten, und überprüfen Sie dann die Änderung auf der entsprechenden Plugin-Seite.

Bearbeiten einer vorhandenen Übersetzung mit Loco Translate

Installieren und aktivieren Sie das Plugin Loco Translate aus dem WordPress-Plugin-Verzeichnis.
Navigieren Sie in WordPress zu Loco Translate → Plugins.
Suchen Sie ADP Car Market Hub in der Liste und klicken Sie darauf.
Wählen Sie die Sprache aus, die Sie bearbeiten möchten.
Bearbeiten Sie die Texte im Loco Translate-Editor und speichern Sie. Loco Translate kompiliert die .mo-Datei automatisch und speichert Ihre Änderungen in wp-content/languages/plugins/, wodurch sie vor Plugin-Updates geschützt sind.

Erstellen einer Übersetzung für eine neue Sprache

Öffnen Sie die POT-Vorlagendatei: wp-content/plugins/adp-car-market-hub/languages/adp-car-market-hub.pot. Die POT-Datei enthält alle übersetzbaren Texte im Plugin ohne Übersetzungen.
Wählen Sie in Poedit Datei → Neu aus POT/PO-Vorlage..., wählen Sie die .pot-Datei aus und wählen Sie die Zielsprache.
Übersetzen Sie die Texte.
Speichern Sie als adp-car-market-hub-{locale}.po und kompilieren Sie zu adp-car-market-hub-{locale}.mo. Verwenden Sie genau den Gebietsschema-Code, den WordPress für diese Sprache verwendet (zum Beispiel fr_CH für die französischsprachige Schweiz). Überprüfen Sie den Code unter Einstellungen → Allgemein → Sprache der Website.
Legen Sie beide Dateien in wp-content/languages/plugins/ ab, damit sie bei Plugin-Updates nicht überschrieben werden.
Stellen Sie die Website-Sprache ein und überprüfen Sie, ob die neue Übersetzung korrekt geladen wird.

Aktualisieren von Übersetzungsdateien nach einem Plugin-Update

Wenn das Plugin aktualisiert wird, können neue Texte hinzugefügt werden. Die mitgelieferten .po-Dateien werden von den Plugin-Entwicklern aktualisiert, aber alle benutzerdefinierten Übersetzungen, die ausserhalb des Plugin-Verzeichnisses gespeichert sind, werden nicht automatisch aktualisiert.

Um Ihre benutzerdefinierte Übersetzungsdatei auf den neuesten Stand zu bringen:

Laden Sie die aktualisierte POT-Datei aus dem Verzeichnis languages/ des Plugins herunter.
Öffnen Sie in Poedit Ihre benutzerdefinierte .po-Datei, wählen Sie dann Übersetzung → Aus POT-Datei aktualisieren... und wählen Sie die neue .pot-Datei aus. Poedit führt die neuen Texte in Ihre Datei zusammen und markiert unübersetzte Texte zur Beachtung.
Übersetzen Sie die neuen Texte.
Speichern und kompilieren Sie.

Wenn Sie WP-CLI verwenden, aktualisieren Sie eine .po-Datei mit msgmerge:

msgmerge --update languages/adp-car-market-hub-de_CH.po languages/adp-car-market-hub.pot

Kompilieren Sie die aktualisierte Datei:

msgfmt -o languages/adp-car-market-hub-de_CH.mo languages/adp-car-market-hub-de_CH.po

Oder kompilieren Sie alle .po-Dateien auf einmal mit WP-CLI:

wp i18n make-mo languages/

Konfigurationsreferenz

Es gibt keine eigene Seite für Übersetzungseinstellungen im Plugin-Adminbereich. Die Übersetzung wird vollständig über die WordPress-Website-Spracheinstellung und das standardmässige WordPress-Lokalisierungssystem abgewickelt.

Was zu konfigurieren ist	Wo
Website-Sprache, die bestimmt, welche Übersetzungsdatei geladen wird	Einstellungen → Allgemein → Sprache der Website
Mitgelieferte Übersetzungen bearbeiten, ohne Änderungen bei Updates zu verlieren	Verwenden Sie Loco Translate, das Bearbeitungen in `wp-content/languages/plugins/` speichert
Eine aktualisierte POT-Datei aus dem PHP-Quellcode des Plugins generieren	Führen Sie `./bin/make-pot.sh` oder `wp i18n make-pot` aus (siehe die i18n-README)

Betriebliche Hinweise

Textdomain. Jeder übersetzbare Text im Plugin verwendet die Textdomain adp-car-market-hub. Diese Textdomain wird im Plugin-Header deklariert und muss mit dem Dateinamen-Präfix der Übersetzungsdateien übereinstimmen (zum Beispiel adp-car-market-hub-de_DE.mo). Eine Diskrepanz zwischen Textdomain und Dateiname ist der häufigste Grund, warum Texte nicht übersetzt werden.
Kompilierte .mo-Dateien sind zur Laufzeit erforderlich. WordPress liest kompilierte .mo-Dateien, nicht die für Menschen lesbaren .po-Quelldateien. Kompilieren Sie eine neue oder aktualisierte .po-Datei immer zu .mo, bevor Sie erwarten, dass Änderungen im Browser sichtbar werden.
Formelles vs. informelles Deutsch. Das Gebietsschema de_DE_formal bietet einen formellen Anredestil (Sie) für Deutsch. Wählen Sie dieses Gebietsschema auf Websites, auf denen eine formelle Formulierung erwartet wird.
Sowohl Frontend- als auch Admin-Texte sind abgedeckt. Die Textdomain des Plugins umfasst Texte sowohl für Admin-Seiten (Einstellungen, Importstatus, Logs) als auch für die Frontend-Ausgabe (Fahrzeug-Labels, Filter-Labels, Kontaktformular-Meldungen, Finanzierungsrechner). Beide Textgruppen befinden sich in derselben .po- / .mo-Datei.
WordPress-Sprachpakete. Wenn das WordPress-Sprachpaketsystem eine Community-Übersetzung für adp-car-market-hub für das ausgewählte Gebietsschema bereitstellt, bietet WordPress möglicherweise an, diese automatisch herunterzuladen. Auf diese Weise erhaltene Dateien werden in wp-content/languages/plugins/ gespeichert und zusammen mit dem WordPress-Core aktualisiert. Überprüfen Sie, ob die Community-Übersetzung vollständig ist, bevor Sie sich in einer Produktionsumgebung darauf verlassen.
Caching. Wenn Übersetzungen nach einer Änderung nicht erscheinen, löschen Sie allfällige WordPress-Objekt-Caches, Page-Caches oder Opcode-Caches. Zwischengespeicherter Bytecode alter .mo-Dateien kann bestehen bleiben, bis der Cache geleert wird.
Dokumentationsdateien. Die Dokumentation in docs/ ist nur auf Englisch verfasst. Es gibt keine übersetzten Dokumentationsdateien. Die Übersetzung von Plugin-PHP-Texten (wie in dieser Anleitung beschrieben) und die Übersetzung der Dokumentation sind zwei verschiedene Dinge.

Fehlerbehebung

Symptom	Wahrscheinliche Ursache	Was zu prüfen ist
Plugin-Texte erscheinen auf Englisch, obwohl die Website-Sprache korrekt eingestellt ist.	Die `.mo`-Datei für das ausgewählte Gebietsschema fehlt oder ist nicht kompiliert.	Überprüfen Sie, ob sowohl die `.po`- als auch die `.mo`-Datei in `wp-content/plugins/adp-car-market-hub/languages/` oder `wp-content/languages/plugins/` vorhanden sind. Die `.mo`-Datei muss vorhanden sein.
Poedit speichert die `.po`-Datei, aber die Texte ändern sich in WordPress nicht.	Poedit hat die `.mo` neben der `.po` kompiliert, aber WordPress lädt eine `.mo` aus einem anderen Pfad.	Überprüfen Sie sowohl das Plugin-Verzeichnis `languages/` als auch `wp-content/languages/plugins/`. Die Datei in `wp-content/languages/plugins/` hat Priorität.
Einige Texte werden übersetzt, andere bleiben auf Englisch.	Diese Texte wurden in einer Version hinzugefügt, die nach der letzten Aktualisierung der Übersetzung erschienen ist.	Aktualisieren Sie die `.po`-Datei wie oben beschrieben anhand der aktuellen POT-Datei, übersetzen Sie die neuen Texte und kompilieren Sie sie erneut.
Nach einem Plugin-Update werden die Übersetzungen wieder auf Englisch zurückgesetzt.	Das Plugin-Update hat die `.mo`-Datei im plugin-eigenen Verzeichnis `languages/` überschrieben.	Verschieben Sie Ihre benutzerdefinierten Übersetzungsdateien nach `wp-content/languages/plugins/`. Dateien dort werden von Plugin-Updates nicht berührt.
Die Einstellung der Website-Sprache zeigt an, dass für ein bestimmtes Gebietsschema keine kompilierte `.mo`-Datei existiert.	Es ist nur eine `.po`-Quelldatei im Paket enthalten, ohne eine kompilierte `.mo`.	Kompilieren Sie die `.po`-Datei mit `msgfmt` oder mit Poedit und legen Sie die resultierende `.mo`-Datei im selben Verzeichnis ab.
Loco Translate zeigt bei einigen Texten Warnungen wegen fehlender Referenzen an.	Der Text existiert in der Übersetzung, ist aber nicht mehr im Plugin-Quellcode vorhanden.	Diese verwaisten Texte sind harmlos; sie beeinträchtigen das Laufzeitverhalten nicht. Sie können sie in Loco Translate löschen, um die Datei sauber zu halten.