Vorbereitung

Wie bereits im ersten Teil dargestellt, muss zunächst in der Datei functions.php die »Textdomain« eingebunden werden. Seit WordPress 2.7 ist es möglich, zusätzlich zum Namen der Domain ein Verzeichnis anzugeben, in dem nach den Übersetzungen gesucht wird (in diesem Fall das Verzeichnis messages/ unterhalb des Template-Verzeichnisses):

load_theme_textdomain('mydomain', get_template_directory().'/messages');

Anschließend müssen in den Templatedateien sämtliche Strings ausgezeichnet werden, die übersetzt werden sollen. Wenn man ein neues Theme von Grund auf gestaltet, tut man gut daran, das von Anfang an zu tun. Andernfalls ist das eine recht mühselige Arbeit.

Ein paar Beispiele

In der Datei index.php befindet sich innerhalb »Der Schleife« (The Loop) diese Zeile zur Ausgabe des Inhalts eines Artikels:

the_content('Read the rest of this entry');

Dies wird zu

the_content( __('Read the rest of this entry', 'mydomain') );

Die Funktion __($message, $domain) sucht innerhalb der Domain $domain (hier: ‘mydomain’) nach einer Übersetzung für den String $message (hier: ‘Read the rest of this entry’) und gibt diese zurück. Oder, falls keine Übersetzung gefunden wurde, den ursprünglichen String.

In der Datei comments.php findet sich das Label für das Formularfeld »author«:

<label for="author">Your name</label>

Dies wird zu

<label for="author"><?php _e('Your name', 'mydomain'); ?></label>

Die Funktion _e(...) ist äquivalent zu echo __(...)

Automatisierung mit GNU make

Nun geht es darum, diese Strings zu extrahieren und in separaten Dateien zu speichern, die dann jeweils die Übersetzung in eine weitere Sprache ermöglichen. Um das Hantieren mit den .po- und .mo-Dateien (siehe Teil 1) etwas einfacher zu gestalten, habe ich folgendes Makefile geschrieben:

# List of locales to generate (space separated)
LOCALES = de_DE

# List of source files
SRC_FILES = ../*.php

# .pot file to create
POT_FILE = messages.pot

$(POT_FILE): $(SRC_FILES)
        xgettext --keyword=__ --keyword=_e --keyword=_c --keyword=__ngettext:1,2 --keyword=__ngettext_noop:1,2 $(SRC_FILES) && \
        mv messages.po $(POT_FILE)

po_files: $(patsubst %,%.po,$(LOCALES))

mo_files: $(patsubst %,%.mo,$(LOCALES))

%.po: $(POT_FILE)
        [ -f $@ ] && \
        msgmerge -U $@ $< && touch $@ || \
        msginit -l $* -o $@

%.mo: %.po
        msgfmt -o $@ $<

Wichtig: die eingerückten Zeilen müssen mit einem Tab und nicht mit Leerzeichen eingerückt werden!

Diese Datei wird unter dem Namen Makefile (Groß-/Kleinschreibung beachten) im Verzeichnis messages/ abgelegt, das unterhalb des Template-Verzeichnisses angelegt wird:

mytheme/
|-- footer.php
|-- functions.php
|-- header.php
|-- index.php
|-- messages/
|   `-- Makefile
|-- screenshot.png
|-- searchform.php
|-- sidebar.php
|-- single.php
`-- style.css

Damit das Folgende funktioniert, müssen die GNU-Tools make und gettext installiert sein, was unter Debian der Befehl aptitude install gettext make erledigt.

.po-Files generieren

Zunächst wechseln wir in das neu angelegte Verzeichnis:

$ cd messages/
$ ls
Makefile

Jetzt legen wir die .po-Datei an, in der die deutschen Übersetzungen gespeichert werden:

$ make de_DE.po

Übersetzen

Nun wird die eigentliche Übersetzungsarbeit fällig. Es bietet sich an, für das Bearbeiten der .po-Dateien eines der zahlreichen Tools zu verwenden, die es einem erleichtern, sich ganz auf die Texte zu konzentrieren, ohne dass man Gefahr läuft die Syntax der Datei kaputt zu machen.

Vorab sollte man in der .po-Datei noch die Zeichenkodierung auf UTF-8 ändern, um sich Probleme mit Umlauten zu ersparen:

"Content-Type: text/plain; charset=UTF-8\n"

.mo-Files generieren

Ist die Übersetzung abgeschlossen, kann die .po-Datei compiliert, d.h. die .mo-Datei erzeugt werden. Das passiert durch den Aufruf von

$ make de_DE.mo

Jetzt sollten die übersetzten Texte im Theme erscheinen. Falls das nicht klappt, sollte als erstes geprüft werden, ob in der wp-config.php die Konstante WPLANG auf den Wert ‘de_DE’ gesetzt ist.

.po-Files aktualisieren

Wird nun weiter am Template gearbeitet, kann es natürlich passieren, dass neue Strings definiert werden, die übersetzt werden wollen. In diesem Fall aktualisiert der Aufruf von make de_DE.po die .po-Datei – alle bisher gemachten Übersetzungen bleiben dabei erhalten. Die Erzeugung der .mo-Datei erfolgt wie gehabt.

Übersetzungen in weitere Sprachen

Wer sich mit Makefiles auskennt, hat vermutlich schon bemerkt, dass sich mit meinem Makefile eine ganze Liste von Sprachdateien in einem Rutsch aktualisieren lassen. Dazu werden in der 2. Zeile alle Locales, die erzeugt werden sollen, durch Leerzeichen getrennt hintereinander aufgelistet (hier z.B. für Deutsch, Französisch, Spanisch und Italienisch):

LOCALES = de_DE fr_FR es_ES it_IT

Nun können alle .po-Dateien mit make po_files bzw. alle .mo-Dateien mit make mo_files auf den neuesten Stand gebracht werden. Es ist übrigens auch möglich, weitere Sprachen im Nachhinein zu ergänzen. Make erzeugt bzw. aktualisiert immer nur die Dateien, die notwendig sind.

Als Internationalisierung (i18n) wird die Vorbereitung eines Programms o.ä. für die Übersetzung bezeichnet, d.h. es wird eine »Infrastruktur« geschaffen, so dass die eigentliche Übersetzung auch von Nicht-Programmierern übernommen werden kann. Das Übersetzen in andere Sprachen ist die Lokalisierung (l10n).

Grundlage für die Internationalisierung von WordPress (inkl. Themes und Plugins) ist das GNU-Tool Gettext, das nach folgendem Prinzip funktioniert:

1. Alle Strings, die übersetzt werden sollen, werden im Quellcode mit speziellen Funktionen ausgezeichnet

2. Dem Programm (bzw. Plugin oder Theme) wird einmalig ein Stück Code hinzugefügt, das die zur eingestellten Sprache passende Übersetzung einbindet — sofern vorhanden

3. Die markierten Strings werden mit xgettext extrahiert und in einer Template-Datei gespeichert (Endung .pot)

4. Aus diesem Template wird für jede Sprache eine Datei für die Übersetzungen abgeleitet (Endung .po)

5. Die fertigen Übersetzungsdateien werden kompiliert, d.h. maschinenlesbar gemacht (Endung .mo)

1. Vorbereitung des Codes

Die eigentliche Vorbereitung des Quelltextes wird unter Translating WordPress ganz gut beschrieben. Im Wesentlichen müssen sämtliche übersetzbaren Strings durch eine der folgenden beiden PHP-Funktionen ersetzt werden:

• __($message, $domain) Für die Zeichenkette $message wird innerhalb von $domain eine passende Übersetzung gesucht und zurückgegeben. Ist keine Übersetzung vorhanden, wird $message zurückgegeben.

  Der Parameter $domain ist ebenfalls ein String und stellt einen Namensraum (Namespace) dar, der verhindert, dass identische Texte mit unterschiedlichen Übersetzungen in mehreren Kontexten Konflikte auslösen. Voraussetzung dabei ist selbstverständlich, dass die Domain einen eindeutigen Bezeichner besitzt. Bei Plugins wählt man dafür sinnvollerweise den Namen des Plugins, der für sich ja auch bereits eindeutig sein muss. Bei Themes ist die Wahl dieses Bezeichners insofern weniger kritisch, da nicht mehrere Themes gleichzeitig angewendet werden können. Der Name darf sich nur nicht mit dem eines Plugins überschneiden.

• _e($message, $domain) ist eine verkürzte Schreibweise für echo __($message, $domain)

Zum Einbinden der Übersetzung ergänzt man noch folgenden Code:

• Für Themes (in functions.php):

  load_theme_textdomain('your_domain');

• Für Plugins (wenn das Plugin »foobar« heißt):

  $foobar_domain = 'foobar';
  $foobar_is_setup = 0;
  
  function foobar_setup()
  {
      global $foobar_domain, $foobar_is_setup;
  
      if ($foobar_is_setup) {
          return;
      }
  
      load_plugin_textdomain($foobar_domain, 'wp-content/plugins/foobar');
  }

2. Erstellung der Template-Datei (.pot)

Insbesondere bei diesem Punkt habe ich lange suchen müssen. In der WordPress-Dokumentation steht nur die lapidare Aussage

Generally, you can download a POT file for WordPress, so you shouldn’t have to generate your own.

Wirklich sehr hilfreich! Nach einigem googlen bin ich dann noch auf diesen Hinweis gestoßen:

Get the makepot.php script and execute it like this:

php makepot.php wp-plugin your-plugin-directory

Hier ist der xgettext-Aufruf, den dieses Script im Wesentlichen fabriziert (auszuführen im Verzeichnis des Themes):

xgettext --keyword=__ --keyword=_e --keyword=_c --keyword=__ngettext:1,2 --keyword=__ngettext_noop:1,2 *.php

Ruft man xgettext per Hand auf, muss man noch beachten, dass xgettext (aus historischen Gründen) eine Datei mit der Endung .po erstellt, die noch umbenannt werden muss!

Alle notwendigen Befehle (xgettext, msginit, msgfmt und msgmerge) installiert man übrigens unter Debian bzw. Ubuntu mit

aptitude install gettext

3. Anlegen und Einbinden einer neuen Übersetzung (.po und .mo)

Ab hier ist der Rest wieder einfach. Der Befehl

msginit -l de_DE -o de_DE.po

initialisiert eine neue .po-Datei (hier z.B. für die locale de_DE). Diese kann der Übersetzer nun mit dem Werkzeug seiner Wahl bearbeiten.

Das Kompilieren in ein maschinenlesbares Format erledigt anschließend die Zeile

msgfmt -o de_DE.mo de_DE.po

Die fertige .mo-Datei muss im Theme- bzw. Plugin-Verzeichnis abgelegt werden. Für das Plugin »foobar« muss die fertige Datei allerdings »foobar-de_DE.mo« heißen!

4. Update einer vorhandenen .po-Datei

Kommen nun (z.B. aufgrund einer neuen Version) weitere zu übersetzende Strings hinzu, muss man nicht wieder von vorne anfangen. Es genügt, die Template-Datei mit dem o.g. Aufruf von xgettext neu zu erzeugen. Anschließend werden die neuen Zeilen mit

msgmerge -U de_DE.po messages.pot

in die vorhandene .po-Datei eingefügt. Die Übersetzung und Kompilierung erfolgen dann wieder wie gehabt.

Links zum Thema

• Translating WordPress
• Internationalizing your plugin (gilt auch für Themes)
• I18n for WordPress developers
• Gettext Handbuch

Update: Im 2. Teil stelle ich eine Möglichkeit vor, die Generierung und Aktualisierung der .po- und .mo-Dateien mit make zu automatisieren.