Übersetzungen¶

Die Textdomain¶

Die Textdomain des Themes ist twtheme. Alle übersetzbaren Zeichenketten laufen über die WordPress-Funktionen:

__('Save modules', 'twtheme');
esc_html__('Modules saved.', 'twtheme');
_n('%s module', '%s modules', $count, 'twtheme');

Ein Child-Theme benutzt seine eigene Textdomain und lädt sie selbst:

add_action('after_setup_theme', 'projekt_setup', 20);
function projekt_setup(): void
{
    load_child_theme_textdomain('projekt', get_stylesheet_directory() . '/languages');
}

Die Dateien¶

Bearbeitet wird ausschließlich die .po. Alles andere entsteht daraus.

Die JSON-Dateien sind nötig, weil der Blockeditor seine Zeichenketten im JavaScript übersetzt und dafür ein eigenes Format braucht.

Der Ablauf¶

1. Neue Zeichenketten einsammeln¶

npm run i18n:pot

Durchsucht das Theme und schreibt languages/twtheme.pot. Ausgenommen sind node_modules, assets, source und includes/engine/assets — dort stehen gebaute Dateien, deren Zeichenketten schon aus den Quellen kommen.

Setzt WP-CLI voraus.

2. Übersetzen¶

Die neuen Einträge aus der .pot in languages/twtheme-de_DE.po übertragen und ausfüllen. Dafür genügt ein Texteditor; bequemer ist ein Werkzeug wie Poedit.

Für viele Einträge auf einmal ist msgmerge der Weg:

msgmerge --previous --backup=off -U languages/twtheme-de_DE.po languages/twtheme.pot
msgfmt --check --statistics -o /dev/null languages/twtheme-de_DE.po

msgmerge übernimmt exakte Treffer unverändert und markiert nur dort fuzzy, wo es keinen exakten, aber einen ähnlichen msgid findet — also genau dort, wo sich der englische Ausgangstext geändert hat. --previous schreibt den alten msgid als #| msgid daneben, sodass sichtbar ist, was sich geändert hat. Die Zahl hinter translated darf gegenüber vorher nicht fallen.

msgfmt schreibt fuzzy-Einträge nicht in die .mo. Sie sind damit unwirksam, bis jemand die Markierung entfernt.

3. Bauen¶

npm run i18n:build

Erzeugt in einem Durchgang alles Übrige:

Setzt msgfmt aus den Gettext-Werkzeugen voraus. Auf macOS über Homebrew:

brew install gettext

4. Ins Languages-Verzeichnis kopieren¶

Damit WordPress die neuen Übersetzungen sieht, müssen sie im Languages-Verzeichnis der Installation liegen. Dafür gibt es einen Knopf in der Admin-Bar: TWtheme → Update language strings.

Er kopiert .po, .mo und die JSON-Dateien an ihren Platz.

Die Einzelschritte¶

Falls nur ein Teil gebraucht wird:

npm run i18n:pot    # Vorlage neu erzeugen
npm run i18n:php    # nur die .l10n.php
npm run i18n:json   # nur die JSON-Dateien

Wenn eine Übersetzung nicht erscheint¶

Der Reihe nach prüfen:

1. Steht die Zeichenkette in der .po und ist msgstr gefüllt?
2. Ist npm run i18n:build gelaufen?
3. Ist Update language strings in der Admin-Bar ausgeführt?
4. Bei Texten im Editor: Gibt es eine passende JSON-Datei für den Skript-Handle?

Der vierte Punkt ist die häufigste Ursache bei Blocktexten. Die JSON-Dateien tragen den Skript-Handle im Namen; ändert sich der Handle, muss npm run i18n:json erneut laufen.

Englische Zeichenketten¶

Unter scripts/ liegen i18n-apply-en.mjs und i18n-apply-en.py. Sie sind Hilfsmittel für die englische Fassung und nicht Teil des normalen Ablaufs.

Was der Code sagt und was der Anwender sieht¶

Die Zeichenketten im Code sind englisch, die Übersetzung ist deutsch. Das erklärt einen Umstand, der beim Nachschlagen auffällt: Ein Modul heißt im Code maintenance und trägt den Namen Maintenance Mode, während die Oberfläche Wartungsmodus zeigt.

Diese Dokumentation nennt bei Modulen und Blöcken beides — den technischen Slug zum Suchen im Code und die Beschriftung zum Wiederfinden im Backend.

Mehrsprachige Seiten¶

Für mehrsprachige Projekte gibt es eine Polylang-Anbindung in includes/plugins/polylang.php. Sie bringt den Shortcode [twtheme_language_switcher] und zwei Filter mit:

Der zweite ist wichtig für Konfigurations-Inhaltstypen wie Slider oder Modals: Deren Felder sollen in allen Sprachen gleich sein, nicht je Sprache gepflegt werden.

Weiter¶

• Build-Kette
• Entwicklungsumgebung