Benutzerdefinierten Gutenberg-Block erstellen – Teil 8: Übersetzungsunterstützung

In diesem Teil konzentrieren wir uns darauf, wie die Texte und Werte in unserem benutzerdefinierten Gutenberg-Block übersetzt werden. Wir verwenden WP-CLI, um die erforderlichen Dateien zu generieren, damit Gutenberg unsere Übersetzungen laden kann, wenn die WordPress-Sprache gewechselt wird.

Bevor Sie damit fortfahren, müssen Sie WP CLI (Befehlszeilenschnittstelle für WordPress) installiert haben. Wenn Sie es nicht haben, folgen Sie einfach der Anleitung im WordPress-Handbuch für CLI.

Um kurz zu erklären, wie man für Javascript (Gutenberg)-Skripte übersetzt: WordPress benötigt .moDateien für die Übersetzung von PHP-Dateien, aber für Javascript benötigt WordPress eine .jsonDatei. Jede Javascript-Datei benötigt eine JSON-Datei zur Übersetzung. Der JSON sollte ein bestimmtes Format haben (WP CLI generiert es für uns) mit unseren übersetzten Zeichenfolgen. Wir benötigen eine JSON-Datei pro Sprache, in die wir übersetzen möchten.

Wir müssen also zuerst die Gettext-Funktionen (__(), _e()etc.) in unsere Javascript-Dateien einfügen und wie gewohnt eine PO-Datei für unser Theme oder Plugin generieren. Da wir die Texte in unseren Skriptdateien mit zB umschlossen haben __(), sollte die PO-Datei sie enthalten können. Dann führen wir die Übersetzung wie gewohnt in unserer PO-Datei durch. Und schließlich verwenden wir WP CLI, um die erforderlichen Zeichenfolgen aus der PO-Datei zu extrahieren und JSON-Dateien für alle unsere Javascript-Dateien zu generieren.

Denken Sie daran, dass die .po/ .mo-Dateien Ihres Themes oder Plugins niemals Auswirkungen auf Ihre Javascript-Dateien haben werden – auch wenn sie übersetzte Zeichenfolgen aus unseren Javascript-Dateien enthalten.

Umsetzung der Übersetzung in Javascript

Der erste Schritt besteht darin, alle Texte in unserer Javascript-Datei innerhalb von Übersetzungsfunktionen zu verpacken. Wenn Sie die Übersetzung für WordPress in PHP durchgeführt haben, sind Sie wahrscheinlich sehr vertraut mit den Funktionen __(), _e(), esc_html__()und so weiter. WordPress hat ein Paket wp.i18n, das diese Funktionen enthält, die genau wie in PHP funktionieren.

Wie bei PHP müssen Sie eine Textdomain-Domain (Name/Handle) angeben. Es kann alles sein, was Sie wollen, aber halten Sie es kurz, da Sie es wahrscheinlich sehr oft abtippen müssen. Für mein Theme habe ich meine Textdomain mit der Domain eingerichtet awhitepixel. In PHP übersetze ich also __('My string', 'awhitepixel')Strings, und in Javascript-Dateien wird es genauso sein.

Beginnen wir mit der Bearbeitung unserer Javascript-Datei. Zuerst müssen wir die Funktion __and _eaus dem wp.i18nPaket destrukturieren. Aufgrund der Natur von React werden Sie die Funktion höchstwahrscheinlich meistens oder vielleicht nur verwenden __.

const { __, _e } = wp.i18n;

Und dann geht es darum, alle unsere fest codierten Texte in der Javascript-Datei zu finden und zu aktualisieren. Beachten Sie, dass die Funktionen __und _eJavascript-Kontext erfordern. Das heißt, wenn wir Strings zum Beispiel als Eigenschaftswerte von Objekten eingeben, verwenden wir sie __()sofort, aber als Werte für zB Props müssen wir alles umschließen { }, um anzuzeigen, dass es sich um Javascript-Code handelt.

Zum Beispiel registerBlockTypesieht unser mit Unterstützung für die Übersetzung so aus:

registerBlockType('awp/firstblock', {
    title: __('My first block', 'awhitepixel'), 
    category: 'common',
    icon: 'smiley',
    description: __('Learning in progress', 'awhitepixel'),
    keywords: [__('example', 'awhitepixel'), __('test', 'awhitepixel')],
    attributes: {
        ...

Und was Requisiten betrifft, dh in InspectorControls:

Schließen Sie alle Texte, für die Sie die Übersetzung unterstützen möchten, in __()und ein _e(). Wenn Sie diesem Tutorial Schritt für Schritt gefolgt sind, sollten Sie keine Fälle haben, in denen Sie verwenden müssen _e(). Wenn Sie fertig sind, kompilieren Sie das Javascript neu, und wir entfernen uns von Javascript.

Po- und/oder Pot-Dateien einrichten

Dieser Schritt variiert ein wenig, je nachdem, was Sie bereits getan und für Ihr Design oder Plugin eingerichtet haben. Möglicherweise schreiben Sie Ihre Gutenberg-Skripte in einem neuen und leeren Plugin, das nicht für die PHP-Übersetzung eingerichtet wurde, oder in einem Design, in dem bereits eine Textdomain registriert ist. Möglicherweise haben Sie PO- (und MO-) Dateien bereit, oder Sie haben möglicherweise nur eine POT-Datei. Ich werde mein Bestes geben, um alle Grundlagen abzudecken.

Mein Theme oder Plugin hat bereits eine po(t)-Datei

Wenn Sie bereits eine PO- oder POT-Datei in Ihrem Projekt haben, haben Sie höchstwahrscheinlich auch die PHP-Funktion load_theme_textdomain()oder irgendwo in Ihrem Code. Bitte stellen Sie sicher, dass die registrierte Domain dieselbe ist, die Sie in Ihren Javascript-Dateien verwendet haben.load_child_theme_textdomain()``load_plugin_textdomain()

Alles, was Sie tun müssen, ist, die PO-Datei für die Sprache, die Sie übersetzen möchten, zu laden (oder eine aus der POT-Datei zu generieren), beispielsweise in PoEdit. Klicken Sie auf „Von Code aktualisieren” (oder ähnlich in anderen Programmen), damit das Programm alle Projektdateien (einschließlich unserer kürzlich aktualisierten Javascript-Dateien) scannen und den Pool der Zeichenfolgen für die Übersetzung aktualisieren kann. Die Zeichenfolgen in unserer Javascript-Datei sollten erscheinen. Dann Sie müssen sie nur wie gewohnt übersetzen und speichern.

PS: Wenn Sie nicht auf „Von Code aktualisieren” klicken oder die Dateien erneut scannen können, wurde die PO-Datei wahrscheinlich nicht richtig eingerichtet. Suchen Sie nach Tipps im nächsten Abschnitt.

Ich habe keine Übersetzungsdateien

Wenn Ihr Design oder Projekt nicht mit Übersetzung eingerichtet wurde, müssen Sie entweder eine POT-Datei mit WP-CLI generieren oder manuell eine PO-Datei erstellen.

Eine ausführliche Anleitung zum Erstellen einer PO-Datei habe ich in meinem Theme Tutorial for Beginners – Part 8. Der Beitrag beschreibt, wie Sie die Datei erstellen und richtig einrichten können, um Ihre Themendateien zu durchsuchen, und die Schlüsselwörter, nach denen gesucht werden soll (__, _e, etc.).

Wenn Sie lieber eine POT-Datei erstellen möchten, können Sie den Befehl wp i18n make-pot in WP-CLI verwenden und dann daraus eine PO-Datei erstellen, z. B. mit PoEdit. Denken Sie daran, dass Sie die POT-Datei (und dann die PO-Datei) jedes Mal neu generieren müssen, wenn Sie Zeichenfolgen in Ihrem Code aktualisieren.

Endresultat

Was Sie letztendlich brauchen, ist eine PO-Datei, die Ihre Javascript-Strings dort gefunden hat, wo diese übersetzt wurden. Ich empfehle, Ihre Übersetzungsdateien in einem separaten Ordner in Ihrem Design oder Plugin zu platzieren. Wenn wir mit dem Generieren von JSON-Dateien beginnen, haben wir am Ende eine ganze Reihe von Dateien für die Übersetzung und es ist schön, sie alle zusammen in einem eigenen Ordner zu halten.

Als Bezugspunkt lege ich alle Übersetzungsdateien in meine theme/assets/lang/. Ich habe eine norwegische Übersetzung für mein Design mit dem Namen hinzugefügt nb_NO.po, die die übersetzten Zeichenfolgen aus unserer benutzerdefinierten Block-JavaScript-Datei enthält.

Generieren von JSON-Dateien aus der po-Datei

Der nächste Schritt besteht darin, WP-CLI zu verwenden, um JSON-Dateien aus unserer po-Datei zu generieren. Dazu verwenden wir den Befehl wp i18n make-json.

Beachten Sie, dass dieser Befehl standardmäßig die übersetzten Zeichenfolgen aus Ihrer PO-Datei zur Verwendung beim Generieren der JSON-Datei herausnimmt. Dies kann während der Entwicklung Ihres Designs oder Plugins umständlich sein. Denn wenn Sie neue Strings hinzufügen oder anpassen, müssen Sie die Dateien erneut scannen und alle Strings erneut übersetzen (und wieder und wieder). Glücklicherweise gibt es ein Flag für den Befehl, um dies zu vermeiden.

Lasst uns beginnen! Navigieren Sie in Ihrem Terminal zu Ihrem Sprachverzeichnis für Ihr Projekt. Führen Sie den folgenden Befehl aus und verweisen Sie auf Ihre po-Datei (wie erwähnt, habe ich eine nb_NO.poDatei bereit).

wp i18n make-json nb_NO.po --no-purge

Wenn Sie kein Problem damit haben, die übersetzten Zeichenfolgen aus Ihrer PO-Datei zu entfernen (z. B. wenn Sie Ihren endgültigen Build erstellen), können Sie das --no-purgeFlag überspringen.

Das Terminal sollte „Success” anzeigen und angeben, wie viele JSON-Dateien erstellt wurden. Wenn Sie sehen, dass es zwei JSON-Dateien generiert hat, liegt dies daran, dass es sowohl unsere Quellcode-JavaScript-Datei als auch die Build-Datei gelesen und für jede eine generiert hat. Wenn Sie mehr Javascript-Dateien in Ihrem Projekt haben, erhalten Sie am Ende noch mehr JSON-Dateien.

Zum Zeitpunkt der Erstellung dieses Artikels (WordPress v 5.3.2 und WP-CLI Version 2.4.0) werden die JSON-Dateien mit dem Sprachcode und einem Hash – einer kryptischen Zeichenfolge – als Dateinamen generiert. Wir müssen den richtigen finden und ihn umbenennen.

Umbenennen der JSON-Datei und Laden in PHP

Ihr Sprachordner sieht wahrscheinlich so aus:

Denken Sie daran, dass der Befehl eine JSON-Datei pro Javascript-Datei generiert hat – und weil wir tatsächlich zwei Dateien für unseren benutzerdefinierten Block haben (die Quelle und der Build), wurden zwei Dateien generiert. Wenn Ihr Javascript-Code in mehrere Dateien aufgeteilt wird, erhält jede zwei eigene JSON-Dateien.

Wenn Sie nur mit zwei JSON-Dateien sitzen (weil keine anderen Javascript-Dateien gefunden wurden), können Sie jetzt eine davon löschen. Wenn Sie mehr als zwei haben, müssen Sie die JSON-Dateien öffnen und sehen, für welche Datei sie bestimmt sind. Die JSON-Dateien enthalten eine Eigenschaft „ source“, die Ihnen mitteilt, für welche Javascript-Datei diese JSON-Datei bestimmt ist. Verwenden Sie das, um herauszufinden, welche JSON-Datei beibehalten werden soll. Ich empfehle, die endgültige Build-Datei (im Gegensatz zu den Entwicklungsdateien) zu finden, da diese alle Zeichenfolgen aus allen Dateien enthalten sollte.

Wenn Sie den richtigen gefunden haben, müssen wir ihn umbenennen. Wir müssen es umbenennen, um diesem Muster zu folgen:

[textdomain]-[language code]-[script handle].json

Verwenden Sie die Textdomain, die Sie überall verwendet haben (zB __('My string', 'awhitepixel')), fügen Sie einen Bindestrich und den Sprachcode hinzu. Geben Sie dann einen Bindestrich und das Skript-Handle ein, mit dem Sie Ihre Gutenberg-JavaScript-Datei registriert haben (wp_register_script()). Als Referenz ist meine Textdomäne awhitepixel, mein Sprachcode ist nb_NO, und mein Skript-Handle für das Gutenberg-Skript ist awp-myfirstblock-js. Also benenne ich die JSON-Datei um in:

awhitepixel-nb_NO-awp-myfirstblock-js.json

Sagen Sie WordPress, dass es unser JSON laden soll

Jetzt bleibt nur noch der letzte Schritt – WordPress sagen, dass es unsere JSON-Datei laden soll. Wir müssen die Funktion verwenden [wp_set_script_translations](https://developer.wordpress.org/reference/functions/wp_set_script_translations/)(). Dies ist eine ziemlich neue WordPress-Funktion, daher empfehle ich, sie in eine function_exists(). Es akzeptiert drei Parameter; das Skript-Handle für unseren Block, die Textdomäne und den Pfad zu unserem Übersetzungsordner (Hinweis: der Pfad, nicht die URL).

Innerhalb unserer Funktion, die an angeschlossen initist, wo wir unser Blockskript registriert und aufgerufen register_block_typehaben, können wir diese neue Funktion auch aufrufen, um unsere JSON-Übersetzungsdatei zu laden. PS: Denken Sie daran, dass der Haken enqueue_block_assetsfür die Registrierung von Übersetzungen nicht funktioniert.

add_action('init', function() {
    wp_register_script('awp-myfirstblock-js', ....);
    register_block_type('awp/firstblock', ....
 
    if (function_exists('wp_set_script_translations')) {
        wp_set_script_translations('awp-myfirstblock-js', 'awhitepixel', get_template_directory(). '/assets/lang');
    }
});

Und das ist alles! Ihr Block sollte jetzt übersetzt werden. Schalten Sie die WordPress-Sprache auf die Sprache um, in die Sie übersetzt haben, und überprüfen Sie es selbst. Wenn ich meine WordPress-Sprache auf Norwegisch umstelle und meinen Block hinzufüge, wird der Name und alles darin übersetzt: