Zum Inhalt

Anleitung für Entwicklerinnen und Entwickler

Für alle, die Site-Templates, Rezepte oder Themes für Drupal CMS bauen.

Default Content Locale Extended übersetzt eine Vorlage während der Installation. Wie gut das gelingt, hängt davon ab, wie die Vorlage gebaut ist. Diese Seite zeigt, wie Sie Ihre Vorlage von Anfang an übersetzbar machen und wie Sie das prüfen.

So arbeitet das Modul mit Ihrer Vorlage

  1. Beim Installieren des Moduls werden seine Übersetzungsdateien (translations/<vorlage>.<sprache>.po) in die Übersetzungsdatenbank von Drupal geladen.
  2. Während die Vorlage ihre Inhalte importiert, ersetzt das Modul die englischen Texte durch die Übersetzung: Knoten, Begriffe, Medien, Menüpunkte, Canvas-Seiten, Bildbeschreibungen.
  3. Nachdem die Vorlage angewendet wurde, übersetzt es Konfiguration, die Drupal allein nicht erfasst: Canvas-Kopf- und -Fußbereiche, Formulare (Webform), URL-Aliase und einige Moduleinstellungen.

Übersetzt wird nach dem englischen Originaltext. Ändert sich ein Text in einer neuen Version Ihrer Vorlage, braucht nur dieser Text eine neue Übersetzung. Alle anderen bleiben gültig.

Voraussetzung: das Modul muss vor den Inhalten aktiv sein

Das Modul muss installiert sein, bevor die Vorlage ihre Inhalte importiert. Das erledigt drush dcle:site-templates: Der Befehl legt für jede Vorlage ein Rezept <vorlage>_localized an, das zuerst das Hilfsrezept localize_site_template anwendet (installiert dcle und, falls Canvas vorhanden ist, dcle_canvas) und danach die Vorlage. Der Drupal-CMS-Installer zeigt diese Rezepte als „… (localized)“ an. Erprobt ist das mit Haven auf Deutsch und Französisch.

Nachträglich lässt sich eine Vorlage nicht übersetzen: Ist sie schon installiert, bleiben ihre Inhalte englisch. Möchten Sie dcle direkt in die install:-Liste Ihrer Vorlage aufnehmen, sprechen Sie uns vorher in der Issue-Queue an.

Checkliste: So wird Ihre Vorlage übersetzbar

Jeder Punkt beruht auf einem Fehler, den wir in echten Vorlagen gefunden haben.

Themes und Komponenten

  • Keine festen Texte im Template. Jeder sichtbare Text in Twig braucht |t bzw. {% trans %}, auch aria-label, alt, title und Fallback-Texte wie „Your browser does not support the video tag.“
  • Props auch wirklich ausgeben. Eine Komponente, die Props für Texte anbietet, sie im Template aber ignoriert und den englischen Text fest hineinschreibt, lässt sich weder bearbeiten noch übersetzen.
  • Namen nicht im Icon verstecken. Wenn ein Linktitel durch ein Icon ersetzt wird, muss der zugängliche Name (z. B. „Follow us on @network“) den Titel trotzdem enthalten.
  • Beispielwerte sind keine Inhalte. Die examples bzw. Standardwerte von Canvas-Komponenten sind versioniert und lassen sich nicht übersetzen. Texte, die Besucher sehen sollen, gehören in die Eingaben der Seite.
  • Eingaben als Daten speichern. Canvas-Eingaben gehören als Struktur in den Export, nicht als JSON-Zeichenkette. Fünf Vorlagen ließen sich wegen JSON-Zeichenketten zeitweise gar nicht installieren.

Beispielinhalte

  • Mit Sprache exportieren. Jeder Inhalt braucht einen langcode. Inhalte ohne Sprache haben bei Summit die Spracherkennung des Installers gestört.
  • Textfelder übersetzbar anlegen. Felder, die Fließtext enthalten, sollten als übersetzbar konfiguriert sein.
  • Auf Inhalte verweisen, nicht auf Pfade. Menüpunkte und Links, die auf einen fest geschriebenen Alias wie /about-us zeigen, laufen ins Leere, sobald der Alias übersetzt wird. Das Modul legt dann Weiterleitungen an. Sauberer ist ein Verweis auf den Inhalt selbst.
  • Keine festen IDs. Einstellungen, die auf /node/12 zeigen (z. B. die 404-Seite), treffen nach einem Import oft den falschen Inhalt.
  • Sicheres HTML. Drupals Übersetzungssystem verwirft Texte mit Tags außerhalb seiner Liste erlaubter Tags, zum Beispiel <u> oder <div>. Verwenden Sie in übersetzbaren Texten einfaches HTML.

Konfiguration und Rezepte

  • Übersetzbare Schema-Typen. Texte in der Konfiguration eigener Module und Themes brauchen im Konfigurationsschema den Typ label oder text, nicht string. Sonst weiß Drupal nicht, dass sie übersetzt werden dürfen.
  • Die Sitesprache nicht verändern. Ein Rezept darf die Standardsprache der Website nicht auf Englisch setzen. Sonst landen alle Inhalte in einer Sprache, die es nach der Installation nicht mehr gibt.

Ihre Vorlage prüfen

Das Modul bringt ein Werkzeug mit, das alle übersetzbaren Texte einer Vorlage auflistet: Inhalte, Canvas-Seiten und Konfiguration, jeweils mit der Stelle, an der sie verwendet werden. Die Vorlage muss dafür auf der Website installiert sein.

# Alle Texte der Vorlage als Übersetzungsvorlage (.pot)
drush dcle:template-pot meine_vorlage --output=meine_vorlage.pot

# Nach einer Installation auf Deutsch: nur die Texte, die noch fehlen
drush dcle:template-pot meine_vorlage --language=de --untranslated-only

meine_vorlage ist der Maschinenname des Rezepts, also der Name seines Ordners unter recipes/. Ebenso geht ein Pfad zum Rezeptordner.

Die .pot-Datei ist auch eine gute Bestandsaufnahme: Taucht darin ein Text nicht auf, den Besucher sehen, steckt er wahrscheinlich fest in einem Template. Dann hilft die Checkliste oben weiter.

Eine Vorlage gilt als vollständig übersetzt, wenn beides erfüllt ist:

  1. --untranslated-only meldet 0 offene Texte.
  2. Auf den fertigen Seiten ist kein englischer Text mehr zu sehen, auch nicht im Kopf- und Fußbereich, in Formularen oder in Bildbeschreibungen.

Übersetzungen beisteuern

Übersetzungen werden derzeit zentral in Default Content Locale Extended gepflegt, eine Datei pro Vorlage und Sprache. Wie Sie eine Übersetzung einreichen, steht in der Anleitung für Übersetzerinnen und Übersetzer.

Fehler in Drupal CMS, Canvas oder einer Vorlage, die Sie beim Prüfen finden, melden Sie bitte beim jeweiligen Projekt. Fehler in diesem Modul gehören in die Issue-Queue von Default Content Locale Extended.