Benutzerdefinierte Gutenberg-Blöcke übersetzbar machen

Erfahren Sie, wie Sie festlegen, welche der von Ihnen entwickelten benutzerdefinierten Gutenberg-Blöcke übersetzbar sein sollen. Sie können dies tun, indem Sie die Datei wpml-config.xml mithilfe des Test-Plugins Multilingual Tools konfigurieren.

Dieser Leitfaden richtet sich an Entwickler, die ihre eigenen benutzerdefinierten Blöcke für Gutenberg erstellen. Wenn Sie kein Plugin-Autor sind, lesen Sie, wie Sie mit dem Gutenberg-Editor erstellte Inhalte übersetzen.

Erste Schritte

Um loszulegen, installieren und aktivieren Sie:

1. WPML-Core-Plugin
2. WPML String-Übersetzung
3. Multilingual Tools

Das Plugin Multilingual Tools sollte nicht auf Live- oder Produktions-Websites verwendet werden. Verwenden Sie es nur zu Testzwecken.

XML-Code generieren und testen, um Gutenberg-Blöcke für die Übersetzung zu registrieren

1. Erstellen Sie einen neuen Beitrag oder eine neue Seite und fügen Sie die Gutenberg-Blöcke hinzu, die Sie registrieren möchten. Stellen Sie sicher, dass Sie in jedem Feld, das Sie übersetzbar machen möchten, Testinhalte hinzufügen, und veröffentlichen Sie sie dann.

Scrollen Sie nach unten zum Abschnitt WPML: Gutenberg Blocks und kopieren Sie den generierten XML-Code.

2. Gehen Sie zu WPML → Einstellungen und fügen Sie den generierten XML-Code unter dem Tab Benutzerdefinierte XML-Konfiguration ein.

Stellen Sie sicher, dass Sie den automatisch generierten Code gründlich überprüfen. Möglicherweise müssen Sie einige Felder entfernen, die nicht übersetzt werden sollen, wie z. B. Konfigurationsfelder mit spezifischen Werten.

Klicken Sie auf Speichern, wenn Sie fertig sind.

3. Gehen Sie zurück zu der von Ihnen veröffentlichten Seite und nehmen Sie kleine Aktualisierungen vor, wie das Bearbeiten eines Button-Textes oder einer Überschrift.

Klicken Sie auf das Plus-Symbol unter dem Abschnitt Sprache, um den Erweiterten Übersetzungs-Editor zu öffnen. Die Felder aus den Gutenberg-Blöcken erscheinen im Editor und sind für die Übersetzung verfügbar.

Sobald Sie die Gutenberg-Blöcke registriert haben, die Sie übersetzbar machen möchten, können Sie Ihre Sprachkonfigurationsdatei erstellen. Wenn Sie bereits eine haben, bearbeiten Sie diese einfach, um Ihren endgültigen XML-Code hinzuzufügen.

Beispiele für die Registrierung von Gutenberg-Blöcken als übersetzbar

Bilder übersetzen

Nehmen wir an, Sie haben ein Bild, das mit dem folgenden Code angezeigt wird:

<!-- wp:image {"id":3} -->
<figure class="wp-block-image"><img src="http://example.com/wp-content/uploads/2018/07/figure-2.png" alt="Image alt text" class="wp-image-3"/><figcaption>Image Caption</figcaption></figure>
<!-- /wp:image -->

Sie möchten die Attributwerte figcaption und alt dieses Bildes übersetzen.

Um dies zu erreichen, müssen Sie den folgenden Code in die Datei wpml-config.xml einfügen:

<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="core/image" translate="1">
        <xpath>//figure/figcaption</xpath>
        <xpath>//figure/img/@alt</xpath>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Bitte beachten Sie, dass der Typ core/image und nicht wp:image ist, da dies der von der Block-API zurückgegebene Wert ist.

Links übersetzen

Sie können festlegen, welche Gutenberg-Blockfelder Links sind. WPML ersetzt dann alle Links durch ihre Übersetzungen, sofern diese verfügbar sind.

<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="core/some-block" translate="1">
        <xpath type="link">//a/@href</xpath>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Übersetzung von Block-Attributen

Hier ist ein Beispiel für ein Format zur Definition eines Editor-Blocks:

<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin/my-block" translate="1">
        <xpath label="My Block">//p</xpath>
        <key name="title" />
        <key name="foo">
            <key name="bar1" />
            <key name="bar2" />
        </key>
        <key name="/^[^_]\S+$/" search-method="regex" />
        <key name="something" search-method="wildcards" />
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Sie können das Key-Element auf die gleiche Weise verwenden, wie es bei der Konfiguration von Admin-Texten / wp_options verwendet wird. Dies bedeutet auch, dass Sie Key-Elemente innerhalb von übergeordneten Key-Elementen haben können.

Sie können das Attribut label verwenden, um optionale benutzerdefinierte Beschriftungen hinzuzufügen, die im Erweiterten Übersetzungs-Editor neben den Block-Elementen angezeigt werden. Wenn das label-Attribut Teil des gutenberg-block-Tags ist, wird es als Fallback-Beschriftung für Elemente des Blocks verwendet, für die keine spezifische Beschriftung definiert ist.

<wpml-config>
    <gutenberg-blocks>
        <gutenberg-block type="my-plugin/mybutton" translate="1" label="My fallback block label">
            <xpath>//span</xpath>
            <xpath>//a@href</xpath>
        </gutenberg-block>
    </gutenberg-blocks>
</wpml-config>

Das Attribut search-method kann einen von zwei Werten haben:

• wildcards (Standard)
• regex.

Sie können Wildcards auf die gleiche Weise verwenden wie für Admin-Texte. Das bedeutet, dass ein Sternchen (*) im name-Attribut verwendet werden kann. Hier ist ein Beispiel für einen Block:

<!-- wp:my-plugin/my-block
    {
        "myp": {
            "mypTitle":"The title",
            "mypContent":"The Content",
            "_mypSystem:"Meta attribute to not translate"
        }
    }
/-->

Sie können die Block-Definition mithilfe einer Wildcard festlegen:

<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin/my-block" translate="1">
      <key name="myp">
          <key name="myp*" />
      </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Dadurch können Sie „The title“ und „The content“ übersetzen, da dies die einzigen Attribute sind, die mit myp beginnen.

Der Wert regex ermöglicht es Ihnen, einen regulären Ausdruck im name-Attribut zu haben. Dies kann für komplexe Konfigurationen extrem nützlich sein. Hier ist ein Beispiel für einen Block:

<!-- wp:my-plugin/my-block
    {
        "data": {
            "title":"The title",
            "_title":"e980759463943209f6f1ae09a239e353",
            "content":"The Content",
            "_content":"1502a7b825dfe7b789c63830609f1701"
        }
    }
/-->

Sie können die Block-Definition mit einem regulären Ausdruck festlegen:

<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin/my-block" translate="1">
        <key name="data">
            <key name="/^[^_]\S+$/" search-method="regex" />
        </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Dadurch können Sie „The title“ und „The content“ übersetzen, da dies die einzigen Attribute sind, die nicht mit einem Unterstrich (_) beginnen.

Einige Block-Plugins speichern Daten in einem URL-kodierten JSON-String innerhalb des Attributs eines Blocks. Das Attribut encoding ermöglicht es Ihnen, den String zu dekodieren und seine Sub-Keys für die Übersetzung zu registrieren.

Zum Beispiel speichert das Plugin LazyBlocks den Inhalt von Repeater-Feldern in einem kodierten JSON-String:

<!-- wp:lazyblock/testwpml {"name":"%5B%7B%22firstname%22:%22Shekhare%22,%22lastname%22:%22Bhandari%22%7D,%7B%22firstname%22:%22Compatibility%22,%22lastname%22:%22Escalation%22%7D%5D","blockId":"Z169b0O","blockUniqueClass":"lazyblock-testwpml-Z169b0O"} /-->

Sie können die Sub-Keys firstname und lastname mit der folgenden XML-Konfiguration registrieren:

<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="lazyblock/team" translate="1">
      <key name="name" encoding="json">
        <key name="*">
          <key name="firstname" />
          <key name="lastname" />
        </key>
      </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Block-Attribut-Links übersetzen

Damit WPML URLs automatisch übersetzen kann, können Sie Gutenberg-Block-Attribute als Links deklarieren.

Hier ist ein Beispiel für einen benutzerdefinierten Gutenberg-Block mit einem anklickbaren Link:

<!-- wp:foo/link {"label":"Click here!","url":"https://example.com/some-page/"} /-->

Um die Attribute label und url übersetzbar zu machen, fügen Sie Folgendes zu Ihrer Datei wpml-config.xml hinzu:

<gutenberg-block type="foo/link" translate="1">
	<key name="label" />
	<key name="url" type="link" />
</gutenberg-block>

In dieser Konfiguration ermöglicht die Angabe von type="link" für das Attribut url, dass WPML die URL automatisch übersetzt.

Block-Namespace

Sie können eine globale Konfiguration für den Block-Namespace haben.

Der Block-Name ist kein obligatorischer Teil der Definition mehr.

Wenn die Block-Konfiguration für alle Blöcke in einem Namespace gleich ist, können Sie sie wie folgt schreiben:

<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin" translate="1">
        <key name="data">
            <key name="/^[^_]\S+$/" search-method="regex" />
        </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Automatische Konvertierung von IDs in Blöcken

Die ID-Konvertierung ist vielseitig und versucht sich an die meisten möglichen ID-Formate anzupassen (einzelne ID, Liste von IDs, serialisiertes Array, JSON-kodiertes Array).

Betrachten Sie den folgenden Block:

<!-- wp:foo/form {"ids":[27,28]} -->
<div class="wp-block-foo-form-wrap">
  <form class="foo-form" action="" method="post">
    <input type="hidden" name="foo_form_post_ids" value="27,28" />
    <input type="submit" />
  </form>
</div>
<!-- /wp:foo/form -->

Sie können die Block-Attribut-IDs und den HTML-Tag-Attributwert foo_form_post_ids wie unten als Beitrags-IDs deklarieren:

<gutenberg-block type="foo/form" translate="0">
  <key name="ids">
      <key name="*" type="post-ids" sub-type="post" />
  </key>
  <xpath type="post-ids" sub-type="post">//*[@name="foo_form_post_ids"]/@value</xpath>
</gutenberg-block>

Der Block wird mit der höchsten Priorität im Filter render_block_data wie unten konvertiert:

<!-- wp:foo/form {"ids":[42,43]} -->
<div class="wp-block-foo-form-wrap">
    <form class="foo-form" action="" method="post">
        <input type="hidden" name="foo_form_post_ids" value="42,43" />
        <input type="submit" />
    </form>
</div>
<!-- /wp:foo/form -→

Sie können die folgenden Konfigurationsattribute verwenden:

• type – kann post-ids oder taxonomy-ids sein
• sub-type (optional): kann die spezifische Entität des type sein, falls diese bereits bekannt ist. Zum Beispiel product für den benutzerdefinierten Beitragstyp Product. Wenn nicht definiert, wird die spezifische Entität erraten.

Zusätzliche Ressourcen

Um mehr über die Datei wpml-config.xml zu erfahren, besuchen Sie den Leitfaden Sprachkonfigurationsdateien.

Informationen zum Anpassen anderer Elemente mithilfe der Datei wpml-config.xml finden Sie in unseren zusätzlichen Leitfäden:

• Benutzerdefinierte Shortcodes mit WPML übersetzen
• Page-Builder-Inhalte für die Übersetzung registrieren
• Benutzerdefinierte Page-Builder-Widgets für die Übersetzung registrieren
• Übersetzungsoptionen für benutzerdefinierte Felder mithilfe der WPML-Konfigurationsdatei festlegen
• Benutzerdefinierte Begriffe, Typen & Taxonomien als übersetzbar registrieren
• Texte übersetzen, die Themes und Plugins in wp_options speichern
• Den WPML-Sprachumschalter mithilfe der WPML-Konfigurationsdatei anpassen