Internationalisierung für Entwickler

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

Wann dieses Dokument zu verwenden ist

Lesen Sie dieses Dokument, wenn Sie Folgendes tun müssen:

• Eine neue übersetzbare Zeichenkette (String) zu PHP-, JavaScript- oder Template-Code hinzufügen.
• Die POT-Datei nach dem Hinzufügen von Zeichenketten neu generieren.
• Eine neue Sprachübersetzung für das Plugin bereitstellen.
• Verstehen, warum eine bestimmte Admin- oder Frontend-Zeichenkette übersetzt oder nicht übersetzt ist.

Hinweise für Übersetzer finden Sie unter README-i18n.md im Repository.

Übersicht

Das Plugin verwendet die Standard-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.
• Installiertes WP-CLI für die Neugenerierung der POT-Datei (das Hilfsskript verwendet wp i18n make-pot).
• Ein POEdit-kompatibler Editor (oder ein beliebiges Tool, das GNU gettext versteht) zur Bearbeitung von .po-Dateien.

Mit dem Plugin ausgelieferte Übersetzungsdateien

Alle Übersetzungsdateien befinden sich unter /languages und folgen der Standard-WordPress-Namenskonvention.

Jedes ausgelieferte Gebietsschema (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 aktuellen Stand im Ordner /languages vor der Veröffentlichung.

Tools

POT-Datei neu generieren

Ein Hilfsskript wird im Verzeichnis bin/ des Repositories bereitgestellt. Es ruft den Befehl i18n make-pot von WP-CLI auf und schliesst 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 über PATH verfügbar ist.
2. Führen Sie das Skript vom Stammverzeichnis des Repositories aus.
3. Die aktualisierte .pot-Datei wird nach languages/adp-car-market-hub.pot geschrieben.

.mo-Dateien kompilieren

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

Schritt-für-Schritt-Anleitung

Eine übersetzbare Zeichenkette in PHP hinzufügen

1. Umschliessen 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 Maskierung (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 über das wp_localize_script()-Array, das vom entsprechenden Handle verwendet wird, an JavaScript. 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 in derselben Änderung neu, damit die Übersetzungsdateien sauber zusammengeführt werden können.
• JavaScript-Zeichenketten. Da JS-Zeichenketten über wp_localize_script() übersetzt werden, erscheinen sie in der POT-Datei nur, 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 gehandhabt. Verwenden Sie die vom Plugin bereitgestellten Helper, anstatt die Locale-Logik in Ihrem eigenen Code neu zu implementieren.
• WordPress-Übersetzungsplattform. Das Plugin kann ausserhalb des Repositories über jeden Standard-gettext-Workflow übersetzt werden. Es ist kein spezieller externer Übersetzungsdienst erforderlich.

Fehlerbehebung

• Eine Zeichenkette wird im Frontend nicht übersetzt. Vergewissern Sie sich, dass die Zeichenkette in einer i18n-Funktion mit der korrekten Textdomain umschlossen ist. Vergewissern Sie sich, dass die Sprache in WordPress (Einstellungen → Allgemein → Website-Sprache) installiert ist und dass eine .mo-Datei für dieses Gebietsschema in /languages existiert.
• Neu hinzugefügte Zeichenketten erscheinen nicht in der POT. Führen Sie das POT-Hilfsskript erneut aus. Überprüfen Sie, ob sich Ihre Datei nicht in einem der ausgeschlossenen Ordner befindet.
• JS-seitiger Text ist nach der PHP-Übersetzung immer noch auf Englisch. Vergewissern Sie sich, 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