Internationalisierung für Entwickler

Dieses Dokument beschreibt, wie das ADP Car Market Hub-Plugin die Internationalisierung (i18n) für Übersetzer und Mitwirkende handhabt. Es deckt die Textdomain, den Lademechanismus, die mit dem Plugin ausgelieferten Übersetzungsdateien, die zur Erstellung der POT-Datei verwendeten Tools und die Konventionen ab, die beim Hinzufügen neuer übersetzbarer Zeichenketten zu beachten sind.

Wann dieses Dokument zu verwenden ist

Lesen Sie dieses Dokument, wenn Sie:

• Eine neue übersetzbare Zeichenkette zu PHP-, JavaScript- oder Template-Code hinzufügen müssen.
• Die POT-Datei nach dem Hinzufügen von Zeichenketten neu generieren müssen.
• Eine neue Sprachübersetzung für das Plugin bereitstellen möchten.
• Verstehen möchten, warum eine bestimmte Admin- oder Frontend-Zeichenkette übersetzt oder nicht übersetzt ist.
• Für Hinweise für Übersetzer siehe das README-i18n.md des Repositorys.

Übersicht

Das Plugin verwendet die standardmäßigen WordPress-i18n-APIs (__(), _e(), _n(), _x(), esc_html__(), esc_attr__(), esc_html_e(), esc_attr_e(), …) mit einer einzigen Textdomain.

• Textdomain: adp-car-market-hub.
• Domain-Pfad: /languages (im Plugin-Header deklariert).
• Loader: load_plugin_textdomain( 'adp-car-market-hub', false, '/languages' ) wird von einer Funktion aufgerufen, die an plugins_loaded mit Priorität 1 angehängt ist, sodass Übersetzungen geladen werden, bevor die plugin-eigenen init-Arbeiten ausgeführt werden.

JavaScript-Zeichenketten, die von den gebündelten Skripten des Plugins verwendet werden, werden in PHP vorübersetzt und über wp_localize_script() an JavaScript übergeben. Das Plugin verlässt sich derzeit nicht auf wp_set_script_translations() und den damit verbundenen JSON-Übersetzungs-Workflow.

Anforderungen oder Voraussetzungen

• Quelldateien, die unter Verwendung der WordPress-i18n-Funktionen mit 'adp-car-market-hub' als Textdomain geschrieben wurden.
• Installierte WP-CLI bei der Neugenerierung der POT-Datei (das Hilfsskript verwendet wp i18n make-pot).
• Ein POEdit-kompatibler Editor (oder ein beliebiges Tool, das GNU gettext versteht) zum Bearbeiten von .po-Dateien.

Mit dem Plugin ausgelieferte Übersetzungsdateien

Alle Übersetzungsdateien befinden sich unter /languages und folgen der standardmäßigen WordPress-Namenskonvention.

Jedes ausgelieferte Locale enthält sowohl eine .po-Quelle als auch eine kompilierte .mo. Die obige Liste spiegelt die derzeit vorhandenen Dateien wider; überprüfen Sie den neuesten Stand im Ordner /languages vor der Veröffentlichung.

Tooling

Neugenerierung der POT-Datei

Ein Hilfsskript wird im Verzeichnis bin/ des Repositorys bereitgestellt. Es ruft den Befehl i18n make-pot von WP-CLI auf und schließt Ordner aus, die nicht gescannt werden sollen (.git, node_modules, vendor, tests, bin).

Um es auszuführen:

1. Stellen Sie sicher, dass WP-CLI installiert und unter PATH verfügbar ist.
2. Führen Sie das Skript vom Repository-Root aus.
3. Die aktualisierte .pot-Datei wird nach languages/adp-car-market-hub.pot geschrieben.

Kompilieren von .mo-Dateien

Nach dem Bearbeiten einer .po-Datei kompilieren Sie eine passende .mo mit Ihrem Editor (das Speichern in POEdit erzeugt beide Dateien automatisch) oder mit msgfmt aus gettext.

Schritt-für-Schritt-Anleitung

Eine übersetzbare Zeichenkette in PHP hinzufügen

1. Umschließen Sie die Zeichenkette mit der entsprechenden WordPress-i18n-Funktion und übergeben Sie 'adp-car-market-hub' als Textdomain. Zum Beispiel __( 'Lead saved.', 'adp-car-market-hub' ) oder esc_html__( 'Vehicles', 'adp-car-market-hub' ).
2. Wenn die Zeichenkette mit HTML verkettet wird, bevorzugen Sie die Varianten esc_*__ und esc_*_e, um Escaping und Übersetzung in einem Aufruf zu kombinieren.
3. Verwenden Sie für Pluralformen _n() oder _nx(). Zur Kontext-Unterscheidung verwenden Sie _x().
4. Generieren Sie die POT-Datei neu (siehe oben), damit Übersetzer die neue Zeichenkette erfassen können.

Eine in JavaScript verwendete übersetzbare Zeichenkette hinzufügen

1. Übersetzen Sie die Zeichenkette zuerst in PHP (__( 'Sending…', 'adp-car-market-hub' )).
2. Übergeben Sie sie an JavaScript über das wp_localize_script()-Array, das vom relevanten Handle verwendet wird. Siehe Frontend Assets und Admin Assets für die bereits verwendeten lokalisierten Objekte (zum Beispiel AS24CI, as24ciCompare, AS24CI_LEADS, AS24CI_BATCH).
3. Lesen Sie den Wert aus der entsprechenden globalen Variable im JavaScript-Code aus.

Eine neue Übersetzung bereitstellen

1. Kopieren Sie languages/adp-car-market-hub.pot nach languages/adp-car-market-hub-<locale>.po unter Verwendung des WordPress-Sprachcodes (zum Beispiel es_ES).
2. Übersetzen Sie die Zeichenketten.
3. Kompilieren Sie die .mo-Datei zusammen mit der .po.
4. Öffnen Sie einen Pull Request mit beiden Dateien.

Betriebliche Hinweise

• Einzelne Textdomain. Jede übersetzbare Zeichenkette im Plugin verwendet 'adp-car-market-hub'. Führen Sie keine zusätzlichen Textdomains ein.
• Halten Sie die POT aktuell. Wenn ein Mitwirkender Zeichenketten hinzufügt oder entfernt, generieren Sie die POT-Datei im selben Änderungsschritt neu, damit Übersetzungsdateien sauber zusammengeführt werden können.
• JavaScript-Zeichenketten. Da JS-Zeichenketten über wp_localize_script() übersetzt werden, erscheinen sie nur dann in der POT, wenn der entsprechende PHP-seitige __()-Aufruf vorhanden ist. Übersetzen Sie JS-Zeichenketten immer zuerst in PHP.
• Gebietsschemaspezifische Formatierung. Die Formatierung von Zahlen und Währungen wird von den plugin-eigenen Locale-Helpern übernommen. Verwenden Sie die vom Plugin bereitgestellten Helper, anstatt die Formatierungslogik in Ihrem eigenen Code neu zu implementieren.
• WordPress-Übersetzungsplattform. Das Plugin kann außerhalb des Repositorys über jeden standardmäßigen gettext-Workflow übersetzt werden. Es ist kein spezieller externer Übersetzungsdienst erforderlich.

Fehlerbehebung

• Eine Zeichenkette wird im Frontend nicht übersetzt. Stellen Sie sicher, dass die Zeichenkette in einer i18n-Funktion mit der korrekten Textdomain umschlossen ist. Überprüfen Sie, ob die Sprache in WordPress (Einstellungen → Allgemein → Website-Sprache) installiert ist und dass eine .mo-Datei für dieses Locale in /languages existiert.
• Neu hinzugefügte Zeichenketten erscheinen nicht in der POT. Führen Sie das POT-Hilfsskript erneut aus. Stellen Sie sicher, dass sich Ihre Datei nicht in einem der ausgeschlossenen Ordner befindet.
• JS-seitiger Text ist nach der PHP-Übersetzung immer noch auf Englisch. Stellen Sie sicher, dass die Zeichenkette über wp_localize_script() für das entsprechende Handle übergeben wird. Das Plugin erkennt nicht übersetzte JS-Zeichenketten nicht automatisch.
• Pluralformen fallen auf die Singularform zurück. Verwenden Sie _n() (oder _nx() für Kontext) anstelle von __() für alle Zeichenketten, die je nach Anzahl variieren.
• Überprüfen Sie das Verhalten in der aktuellen Plugin-Version, bevor Sie eine benutzerdefinierte Integration veröffentlichen. Lokalisierte JavaScript-Objektnamen können sich zwischen den Versionen ändern.

Verwandte Dokumente

• Frontend Assets
• Admin Assets
• Coding Standards
• Repository Structure
• Contribution Guidelines