Localization von Themes und Plugins – Eine Einführung

Ärgern dich die (meist) englischen Bezeichnungen in deinem Theme oder bei einem Plugin? Möchtest du nicht alle Stellen per Hand suchen und übersetzen? Nur um dann bei einem Update alle Änderungen wieder zu verlieren? Die Lösung hierzu heißt Localization/Lokalisierung.

Dieser Beitrag richtet sich eher an WordPress-Nutzer, die sich praktisch noch gar nicht mit der Materie beschäftigt haben und wissen möchten, was es damit auf sich hat. Aber auch für Fortgeschrittene mag sich der eine oder andere Tipp hier verbergen. Das meiste stammt aus einem älteren Beitrag, der mir mittlerweile zu kompliziert erscheint und an dem ich mich deshalb noch einmal versuchen möchte.

Der Beitrag ist recht lang und deshalb in mehrere Abschnitte unterteilt. Wer sich schon auskennt, kann sich an der Zusammenfassung versuchen oder einzelne Abschnitte überspringen.

  1. Voraussetzungen
  2. Grundprinzip der Lokalisierung
  3. Besonderheit bei Plugins
  4. Einrichten von poEdit
  5. Erstellen/Bearbeiten einer Sprachdatei
  6. Bedienung von poEdit
  7. Zusammenfassung

Voraussetzungen

Folgende Voraussetzungen werden benötigt für die eigentliche Übersetzungsarbeit und das anschließende ungefährliche Testen. Wer live auf seinem Blog testen möchte, überspringt den ersten Punkt.

  1. ENTWEDER eine lokale Installation (Anleitung im Mediengestalter-Blog) ODER eine Testinstallation auf einem entfernten Server parallel zur bestehenden. Vorgehen für die zweite Variante:[1]
    • Kopie des WordPress-Ordners (z.B. wordpress-test) auf dem Server erstellen,
    • in wp-config die Zeile
      $table_prefix  = 'wp_';

      ändern zu

      $table_prefix  = 'wp_test_';
    • WordPress installieren,
    • Sichtbarkeit des Blogs deaktivieren (in Einstellungen » Privatshäre),
    • für beide Varianten gilt: URL anpassen (Anleitung bei frische-zitronen.de)
  2. Die Software poEdit (erhältlich für Windows und Linux) zum Editieren der Sprachdatei.
  3. Auf dem lokalen Rechner ein Ordner (z.B. wp) mit zwei Unterordnern zur getrennten Lokalisierung von Theme und Plugins:
    • wordpress-test, der der eigentlichen WordPress-Installation entspricht, aber OHNE den Ordner wp-content/plugins und nur das gewünschte Theme im Ordner wp-content/themes,
    • wordpress-test-plugins für die zusätzlichen Plugins,
    • für jedes Plugin einen eigenen Ordner (auch wenn es nur eine Datei ist – der Ordner heißt dann wie das Plugin).
  4. Prüfen: In der Datei wp-config steht die Zeile
    define ('WPLANG', 'de_DE');

    und im Ordner wp-includes/languages gibt es die Datei de_DE.mo.[2] Der Dateiname kann auch anders lauten, er sollte nur mit der in WPLANG definierten Variable übereinstimmen.

Grundprinzip der Lokalisierung

← zum vorherigen Abschnitt↑ Inhaltsverzeichnis→ zum nächsten Abschnitt

Laut WordPress-Codex (Localizing WordPress) ist dies ein zweistufiger Prozess. Im ersten Schritt ist der Entwickler gefragt, der im Quelltext die Möglichkeiten bereitstellt, damit später sein Theme bzw. Plugin übersetzt werden kann. Und im zweiten Schritt erfolgt dann die tatsächliche Übersetzung (hier per poEdit).

Das Ganze basiert auf dem GNU gettext Framework, dem Standard für modulare Übersetzung. Laut der deutschen WordPress-Doku (Bearbeitung der Sprachdatei), sind für gettext zwei Dateien wichtig. Der Ablauf ist folgendermaßen:

  1. Gettext liest Zeichenfolgen im Quelltext ein, die in der PO-Datei gespeichert werden.
  2. Die Übersetzung erfolgt durch Bearbeiten der PO-Datei.
  3. Die übersetzten Zeichenfolgen werden in der MO-Datei gespeichert.
  4. Beim Aufruf einer Seite wird die MO-Datei von WordPress ausgelesen und es wird die Übersetzung angezeigt.

Die einzelnen Zeichenfolgen müssen im Quelltext markiert werden für die Übersetzung. Dies erfolgt über zwei PHP-Funktionen, __() und _e(). Zur Erklärung heißt es (meine Übersetzung des Originaltextes):

__($message)

(zwei Unterstriche) Durchsucht das Lokalisierungsmodul nach der Übersetzung von $message und übergibt die Übersetzung als Rückgabewert (return statement). Wenn keine Übersetzung für $message gefunden wird, wird einfach $message zurückgegeben.

_e($message)

(Unterstrich und e) Durchsucht das Lokalisierungsmodul nach $message und übergibt die Übersetzung als Ausgabewert (echo statement). Wenn keine Übersetzung für $message gefunden wird, wird einfach $message ausgegeben.

Die Markierungen dienen als Schlüsselwörter beim Einlesen. In den PHP-Dateien sollte dann also nicht

echo 'gib mich aus'

stehen, sondern

_e('gib mich aus');

bzw. nicht

'gib mich zurück'

sondern

__('gib mich zurück')

Gut: Das Theme bzw. Plugin ist schon auf diese Weise vorbereitet, d.h. gettextet. Man erspart sich die Fleißarbeit, alle Zeichenfolgen zu ersetzen.

Schlecht: Ist das nicht der Fall, muss man die Dateien selber gettexten und an den entsprechenden Stellen __() und _e() einfügen. Dabei die Anführungszeichen nicht vergessen! Man kann sowohl einfache (‚) als auch doppelte („) verwenden, es sollten nur die gleichen öffnenden und schließenden sein.

Besonderheit bei Plugins

← zum vorherigen Abschnitt↑ Inhaltsverzeichnis→ zum nächsten Abschnitt

Hier gibt es einen zusätzlichen Parameter, die sog. Domäne, also lautet die Funktion

__($message, $domain)

Damit kann für jedes Plugin (bzw. jede Domäne) eine eigene Sprachdatei erstellt werden. Häufig ist es so, dass die Autoren der Plugins das schon getan haben. Dann findet sich im Quelltext eine Zeile, die etwa so aussehen sollte:

load_plugin_textdomain('plugin-name');

oder

load_plugin_textdomain('plugin-name','wp-content/plugins/pfad/zur/sprachdatei');

Die Domäne impliziert, dass die Übersetzungen in der Sprachdatei wp-content/plugins/$domain-de_DE.mo statt in wp-includes/languages/de_DE.mo zu suchen sind. Der zweite Parameter kann genutzt werden, um einen speziellen Ordner anzugeben. Nachzulesen ist das Ganze im Abschnitt Localizing Plugins.

Vorteil: Die eigentliche Installation und die Zusatzfunktionen werden getrennt übersetzt. Die Haupt-Sprachdatei wird nicht unnötig aufgebläht.

Nachteil: Man muss für jedes Plugin (bzw. jede Domäne) eine eigene Sprachdatei erstellen und verwalten.

Möchte man Ordnung halten und alle Plugin-Sprachdateien in einem bestimmten Verzeichnis speichern, z.B. wp-content/plugins/languages, muss dieses Verzeichnis bei jedem Plugin in der obigen Funktion eingetragen werden.

Achtung: Angenommen, man möchte keine getrennte Lokalisierung der Plugins vornehmen, sondern die Übersetzungen in der Hauptsprachdatei speichern. Dann muss der zusätzliche Parameter entfernt werden, wenn der Plugin-Autor diesen eingefügt hat. Ansonsten ignoriert WordPress diese Zeichenketten bei der Übersetzung, weil nach der Domänen-Sprachdatei gesucht wird.

Einrichten von poEdit

← zum vorherigen Abschnitt↑ Inhaltsverzeichnis→ zum nächsten Abschnitt

Im Beitrag Erstellen der Sprachdatei mit poEdit ist vor allem der Abschnitt Konfiguration von poEdit – Allgemeine Programmeinstellungen wichtig. Dort heißt es

Deshalb starten wir poEdit und rufen die Programmeinstellungen (Datei > Einstellungen) auf. Auf der ersten Registerkarte trägst du jetzt deinen Vor- und Nachnamen ein. Auf der Editor-Registerkarte entfernst du das Häkchen vor der Option CR/LF-Konvertierung > Behalte Format existierender Kategorie bei. Dann wechselst du auf die Karteikarte Parser und klickst auf Neu.
In den Feldern trägst du jetzt von oben nach unten ein:

  1. PHP
  2. *.php
  3. xgettext –output=%o %K –language=php %F
  4. –keyword=%k
  5. %f

Das letzte Feld bleibt frei. Jetzt klickst du zweimal auf OK. Damit ist poEdit fertig für das Parsen von PHP-Dateien.

Neben diesen allgemeinen Einstellungen gibt es noch Einstellungen für die Katalogverwaltung. Die folgenden weichen von den „offiziellen“ von WordPress ab, weil hier in einer anderen Ordnerstruktur gearbeitet wird.

  1. Aufrufen der Katalogverwaltung mit Datei > Katalogverwaltung
  2. Neues Übersetzungsprojekt anlegen durch Klick auf den ersten Button ganz links (Tooltip: Erstelle neues Übersetzungsprojekt)
  3. Name kann beliebig gewählt werden
  4. wichtigste Einstellung: absoluter Pfad zum Projekt (Der schon vorgegebene Pfad kann durch Klick auf den Bearbeiten-Button (a|e) angepasst werden. Ist kein Pfad vorgegeben, durch Klick auf den Neu-Button einen neuen erstellen. Hier den Pfad zum oben angelegten Ordner (wp) angeben.)
  5. Fertigstellen des Übersetzungsprojektes durch Klick auf OK

Damit sind alle allgemeingültigen Einstellungen abgeschlossen. Die folgenden Einstellungen sind katalogspezifisch.

Erstellen/Bearbeiten einer Sprachdatei

← zum vorherigen Abschnitt↑ Inhaltsverzeichnis→ zum nächsten Abschnitt

Zunächst gehe ich von dem Fall aus, dass bereits eine Sprachdatei existiert, die aktualisiert werden soll. Für die deutsche Version von WordPress, kann man sich die aktuelle PO-Datei herunterladen. Diese ist ein guter Ausgangspunkt für das Übersetzen. poEdit bietet nämlich einen sogenannten Übersetzungsspeicher (Translation Memory, abgekürzt tm), der aufgrund ähnlicher Formulierungen die wahrscheinlichste Übersetzung rät.

Die Sprachdatei de_DE.po im Verzeichnis wp speichern (d.h. in dem Ordner ÜBER der WordPress-Installation) und mit poEdit öffnen. Damit poEdit die richtigen Textstellen zum Übersetzen findet, müssen einige Einstellungen vorgenommen werden.

  1. Katalogoptionen öffnen (Katalog > Optionen),
  2. in der Registerkarte Projektinfo sollte schon alles Wichtige eingetragen sein, vor allem sollte UTF-8 als Zeichensatz gewählt sein,
  3. in der Registerkarte Pfade als Basispfad ./wordpress-test (Punkt Slash und der oben gewählte Ordnername für die WordPress-Installation) eingeben,
  4. zusätzliche folgende Pfade durch Klick auf den Neu-Button eintragen:
    • . [das ist ein Punkt]
    • wp-includes
    • wp-admin
    • wp-content\themes [hier Backslash verwenden]
  5. in der Registerkarte Schlüsselwörter zwei neue Einträge anlegen mit __ und _e (den oben erwähnten Schlüsselwörtern),
  6. Klick auf OK.

Screenshot von poEditDer Klick auf Ok sollte ein Durchsuchen des Quelltextes zur Folge haben. Wenn Fehler kommen, kann es evtl. daran liegen, dass man sich beim Eingeben der Pfade vertan hat. Dann Rückgängig wählen und erneut die Daten eingeben. Das Ergebnis sollte ungefähr so aussehen, wie das Bild rechts (Anklicken für volle Größe). Erst einmal SPEICHERN (zweiter Button von links).

Möchte man eine neue Sprachdatei erstellen, öffnet man poEdit und wählt Datei > Neuer Katalog. Es erscheint wieder der Dialog Katalogoptionen, nur diesmal völlig leer. Die Einstellungen für die Registerkarten Pfade und Schlüsselwörter sind die gleichen wie oben. In der Registerkarte Projektinfo trägt man in den ersten drei Feldern die entsprechenden Infos ein. In die nächsten drei Felder sollten german, germany, utf-8 eingetragen werden. Der Rest bleibt leer. Nach klick auf OK wird man aufgefordert die Datei zu speichern. Als Speicherort den wp-Ordner wählen und als Dateiname die Variable bei WPLANG, z.B. de_DE.po.

Für eine Plugin-Sprachdatei gibt es zwei Abweichungen. Bei den Pfaden besteht der Basispfad und der Pfad zum Plugin im einfachsten Fall jeweils aus einem Punkt (= gleiches Verzeichnis wie die Sprachdatei). Gespeichert wird die Datei im Ordner des Plugins unter dem Namen $domain-de_DE.po, wobei $domain meist der Name des Plugins ist (siehe oben genannte Besonderheit).

Gibt es bereits eine Sprachdatei, die sich in einem Unterordner des Plugins (z.B. languages) befindet, wird der Basispfad zu ../ (= eine Ebene über der Sprachdatei). Enthält der Plugin-Ordner Unterordner mit zu übersetzenden Dateien, werden diese als zusätzliche Pfade eingetragen.

Bedienung von poEdit

← zum vorherigen Abschnitt↑ Inhaltsverzeichnis→ zum nächsten Abschnitt

Zur Bedienung von poEdit wird man bei WordPress auf die Programm-eigene Hilfe verwiesen. Die ist jedoch lückenhaft, teilweise veraltet, schwer verständlich und bezieht sich nur allgemein auf gettext-Techniken. Deshalb hier eine kurze Einführung.

Die bunten Zeilen bekommt man, wenn im Ansicht-Menü die Option „Gefärbte Übersetzungsliste“ angekreuzt ist. Die Farben haben folgende Bedeutung:

  • hellblau = unübersetzt
  • gelb/beige = unklar
  • weiß = übersetzt/alles ok

Am Anfang jeder Zeile können verschiedene Icons auftauchen. Die Beschreibung ist in der Hilfe nicht auf dem neuesten Stand. Hat man in der aktuellen Sitzung eine Zeile verändert, sieht man einen gelben Stern. Die Hilfe gibt an, dass es sich um einen grünen Punkt handeln soll. Wurde ein Eintrag von der tm übersetzt, so sieht man ein Computer-Icon. Besitzt ein Eintrag einen Kommentar, so soll ein Bleistift-Icon erscheinen. Tatsächlich handelt es sich aber um eine Sprechblase.

In der Statuszeile unten stehen die Anzahlen der Zeichenketten (gesamt, unklar, ungültig, unübersetzt). So behält man den Überblick darüber, was noch gemacht werden muss. Alle unklaren Übersetzungen werden von WordPress bei der Anzeige ignoriert, d.h. sie werden so wie nicht übersetzte Zeichenketten behandelt.

Ein schnelles Durcharbeiten ist möglich, da man mit Tab und den Cursor-Tasten bequem durch die Zeichenketten navigieren kann. Es gibt die Short-Cuts Alt-U zum Bestätigen einer unklaren Übersetzung und Alt-C zum Kopieren des Originals in die Übersetzung.

Achtung ist geboten, wenn Platzhalter im Originaltext vorkommen. Diese sind mit einem % gekennzeichnet. Die Anzahlen sollten beim Original und in der Übersetzung übereinstimmen, sonst wird die Übersetzung ungültig.[3] Wenn mehrere Platzhalter vorkommen, sollten diese unterschiedliche Bezeichnungen haben. Oft werden aber alle Platzhalter in einer Zeichenkette mit %s bezeichnet. Das ist ok, solange im Original und der Übersetzung die gleiche Reihenfolge eingehalten wird. Leider ist das aber beim Übersetzen vom Englischen ins Deutsche nicht in allen Fällen möglich. Oder man wählt absichtlich eine Formulierung, die eine andere Reihenfolge der Platzhalter erfordert.

In diesem Fall muss der Quelltext bearbeitet werden. Das geht aber nicht direkt in poEdit, sondern nur in einem externen Editor. Wo die Zeichenkette auftaucht, mit Dateiname und Zeilennummer, erfährt man durch einen Rechtsklick auf die Zeichenkette (siehe Screenshot). Klick auf den Eintrag im Kontextmenü öffnet den Editor an dieser Textstelle[4]. Nun kann man die Platzhalter durchnummerieren mit %1$s, %2$s, .... Datei speichern nicht vergessen.

Nach jeder Änderung der Originaltexte oder Hinzufügen von Dateien, muss der Katalog aktualisiert werden, d.h mit den Quellen synchronisiert werden. Dazu einfach den Update-Button klicken (dritter Button von links). Nach dem Aktualisieren und Speichern werden die Icons und Farben angepasst.

Das Kontextmenü gibt außerdem Informationen über die Übersetzungsvorschläge an (wenn es denn welche gibt) und man kann sich den besten aussuchen oder selber eine bessere Übersetzung eingeben.

Am Ende der Bearbeitung den Katalog speichern. Damit wird automatisch auch die MO-Datei erstellt. Wenn nicht, unter Datei > Einstellungen, Registerkarte Editor ganz oben diese Option ankreuzen.

Zusammenfassung

Um immer wieder seine WordPress-Installation bzw. neue Plugins zu übersetzen geht man folgendermaßen vor.

  1. Synchronisation der Test-WordPress-Installation mit dem wp-Ordner, mit dem Unterschied, dass die Plugins separat abgespeichert werden (Was ist damit gemeint?),
  2. bei einem neuen Theme oder Plugin:
    1. Textstellen auf gettext-Zustand prüfen, d.h. ob überhaupt gettextet, ob mit __($message) oder mit __($message, $domain) (letzteres gilt nur für Plugins),
    2. wenn nötig, Textstellen anpassen (Was ist damit gemeint?),
    3. bei Plugins, Anpassen an individuelle Vorzüge (Was ist damit gemeint?),
    4. geänderte Dateien zur Test-WordPress-Installation kopieren.
  3. Öffnen/Erstellen der PO-Datei in poEdit (Wie geht das?),
  4. Ändern, Aktualisieren und Speichern der PO-Datei bis zum gewünschten Ergebnis (Wie geht das?),
  5. Kopieren der erstellen MO-Datei in das entsprechende Verzeichnis der Test-WordPress-Installation (wp-includes/languages für die Haupt-Sprachdatei, und wp-content/plugins bzw. wp-content/plugins/languages,
  6. Aufruf der Seite, auf der der übersetzte Text auftauchen soll, um zu prüfen, dass man die richtigen Stelle erwischt hat,
  7. gegebenenfalls diese Schritte wiederholen, bis das gewünschte Ergebnis erreicht ist,
  8. Wenn dies dann endlich der Fall ist, kann man die Dateien endlich zur „realen“ WordPress-Installation kopieren (d.h. alle neuen und geänderten Dateien – bloß keine vergessen!)

Das war es auch schon. Verbesserungsvorschläge, Anregungen, Kritik oder sonstige Anmerkungen?

Nachtrag: verständliche und Schritt-für-Schritt-Anleitung bei Texto.de

  1. Eine parallele Installation ist weniger aufwändig und man testet auf dem Server, auf dem die eigentliche WP-Installation ist. Die benötigten Zugriffsrechte auf die entfernten Daten per FTP sollten gegeben sein. []
  2. Dies sollte der Fall sein, wenn man die DE-Version von WordPress installiert hat. Ansonsten muss man nachträglich die deutsche Sprachdatei installieren. []
  3. Wenn es ungültige Fehlerketten gibt, lässt sich der Katalog manchmal nicht mehr speichern. Es gibt dann eine Fehlermeldung mit Details. Abhilfe schafft die Bearbeitung der PO-Datei in einem Texteditor. Die Zeile(n) suchen, die in der Fehlermeldung angegeben ist/sind und alles zwischen den Anführungszeichen bei msgstr löschen. []
  4. Sollte das nicht funktionieren, stimmen die Einstellungen zum externen Editor nicht. Diese findet man unter Datei > Einstellungen, Registerkarte Editor. Im Feld Editor EXE-Datei sollte z.B. notepad %f stehen. Das Ankreuzfeld darunter sollte ein Häkchen haben. Funktionert es immer noch nicht, kann man die Datei auch manuell im Editor öffnen. []

Veröffentlicht von

juliaL49

Wilde Mischung aus musikinteressiertem Konzertbesucher, fernsehbegeistertem Whovian, radfahrendem Läufer, fotografierendem Atheisten und ausgewandertem Bioinformatiker

7 Gedanken zu „Localization von Themes und Plugins – Eine Einführung“

  1. Wow, ich hab lange gesucht, aber dank dieser Anleitung hab ich endlich PoEdit verstanden.

    Wirklich eine super Anleitung!
    Danke

  2. Echt super Beschreibung. Zumindest bei einem Plugin habe ich die „Übersetzung“ nun geschafft…

    Evtl. könnte man noch etwas zu „übliche Fehler“ schreiben…

Kommentare sind geschlossen.