WordPress-Internationalisierung: So übersetzen Sie Themes und Plugins

Machen Sie Ihr WordPress-Theme oder -Plugin bereit für die Übersetzung. Dieser Leitfaden behandelt Textdomains, Gettext-Funktionen, die POT-Generierung und den Lademechanismus, der den Benutzern die Übersetzungen anzeigt. PTC (Private Translation Cloud) übersetzt anschließend die Ressourcendateien und prüft das gerenderte Theme oder Plugin visuell in jeder Sprache.

Dieser Leitfaden richtet sich an Entwickler, die den Code schreiben. Wenn Sie bereits eine POT- oder PO-Datei haben und diese nur übersetzen müssen, besuchen Sie die Seite für PO-Dateien für den 3-Schritte-Workflow.

Am Ende dieses Leitfadens wird Ihr Theme oder Plugin:

• gemäß den WordPress-Codierungsstandards korrekt internationalisiert sein.
• durch PTC in über 40 Sprachen übersetzbar sein.
• über WordPress.org Language Packs verteilbar sein.
• bei jedem Release mit der visuellen Übersetzungsprüfung von PTC verifizierbar sein.

Was ist WordPress-Internationalisierung?

Internationalisierung (i18n) ist die Arbeit, Ihren Code so vorzubereiten, dass er übersetzt werden kann. Lokalisierung (l10n) ist der nächste Schritt. Sie erstellt die tatsächlichen übersetzten Strings für bestimmte Sprachen.

Für WordPress-Themes und -Plugins bedeutet i18n drei Dinge:

• Jeden für den Benutzer sichtbaren String in Gettext-Funktionen einschließen, damit WordPress diese zur Laufzeit austauschen kann.
• Eine Textdomain definieren, die Ihre Übersetzungen mit Ihrem Projekt verknüpft.
• Eine POT-Datei generieren, mit der Übersetzer (oder PTC) arbeiten.

Sobald diese Arbeit erledigt ist, haben Sie alles, was Sie brauchen, um übersetzte PO-, MO-, JSON- und .l10n.php-Dateien für jede Sprache zu erstellen.

PTC übersetzt POT-Dateien in MO, JSON und .l10n.php für WordPress

In jedem WordPress-Übersetzungs-Workflow tauchen fünf Dateiendungen auf. PTC übersetzt von .pot (Ihrer Quelle) in .po, .mo, .json und .l10n.php für jede Zielsprache. Jedes Format hat eine spezifische Rolle:

• POT (Portable Object Template). Die aus Ihrem Code generierte Quelldatei. Sie listet jeden übersetzbaren String auf, ohne dass Übersetzungen beigefügt sind. Diese übergeben Sie an PTC.
• PO (Portable Object). Eine Kopie der POT mit hinzugefügten Übersetzungen für eine bestimmte Sprache. Es handelt sich um Klartext, der für Menschen lesbar ist. PTC liefert eine PO pro Zielsprache zurück.
• MO (Machine Object). Die kompilierte Binärversion einer PO. WordPress liest zur Laufzeit MO-Dateien, da diese schneller laden als PO-Text.
• JSON. Das JavaScript-Äquivalent zu MO. WordPress kann MO nicht aus JavaScript lesen, daher erstellt die Build-Pipeline JSON-Dateien für browserseitige Strings.
• .l10n.php. Eine neuere Alternative zu MO, eingeführt in WordPress 6.5. Sie lädt schneller und verbraucht weniger Speicher. WordPress wählt sie automatisch aus, wenn sie neben der MO-Datei existiert.

Aktivieren Sie .l10n.php für neue Projekte. Es ist auf den unterstützten WordPress-Versionen strikt besser als MO.

Warum Community-Übersetzung nicht ausreicht

WordPress.org bietet Community-Übersetzungen über GlotPress an. In der Praxis deckt dies nur einen kleinen Bruchteil dessen ab, was die meisten Plugins und Themes benötigen. Eine Analyse von mehr als 60.000 WordPress-Plugins und -Themes ergab, dass Community-Übersetzungen weniger als 5 % des Übersetzungsbedarfs in 40 Sprachen abdecken.

Zwei strukturelle Probleme erklären diese Lücke:

• Freiwillige sind in den meisten Regionen knapp. Nur eine Handvoll Plugins mit massiven Nutzerzahlen ziehen Übersetzer an. Bei den meisten ist das nicht der Fall.
• Übersetzungen können Monate oder Jahre dauern, bis sie erscheinen, falls sie überhaupt erscheinen. Wenn Sie möchten, dass Benutzer Ihr Plugin oder Theme vom ersten Tag an in ihrer Sprache sehen, können Sie sich nicht auf die Community verlassen.

Dieser Leitfaden setzt voraus, dass Sie eine konsistente, vollständige Übersetzungsabdeckung nach einem von Ihnen kontrollierten Zeitplan wünschen. Das ist es, was PTC liefert.

Vorbereitung Ihres WordPress-Themes oder -Plugins für die Übersetzung

Eine falsche Textdomain oder ein nicht eingeschlossener String bedeuten, dass dieser Text niemals in Ihrer übersetzten Ausgabe erscheinen wird. Die Details zählen.

Schritt 1: Definieren Sie Ihre Textdomain und den Domain-Pfad

Jedes Theme oder Plugin benötigt eine Textdomain. Die Textdomain ist eine eindeutige Kennung, die WordPress mitteilt, welche Übersetzungsdateien zu Ihrem Projekt gehören. Sie muss exakt mit Ihrem Plugin- oder Theme-Slug übereinstimmen.

Deklarieren Sie diese im Header der Hauptdatei Ihres Plugins:

<?php
/**
 * Plugin Name: My Plugin
 * Description: An example plugin.
 * Version: 1.0.0
 * Text Domain: my-plugin
 * Domain Path: /languages
 */

Oder in der style.css Ihres Themes:

/*
Theme Name: My Theme
Text Domain: my-theme
Domain Path: /languages
*/

Der Domain-Pfad teilt WordPress mit, wo Ihre Übersetzungsdateien relativ zum Plugin- oder Theme-Verzeichnis liegen. /languages ist der Standard.

Schritt 2: Schließen Sie Ihre PHP-Strings in Gettext-Funktionen ein

Jeder String, den Sie übersetzbar machen möchten, muss in eine der Gettext-Funktionen von WordPress eingeschlossen werden. Zur Laufzeit suchen diese Funktionen nach der korrekten Übersetzung. Wenn keine gefunden wird, greifen sie auf den ursprünglichen String zurück.

Einfache Strings. Verwenden Sie __(), wenn Sie einen String zurückgeben müssen. Für die HTML-Ausgabe verwenden Sie die Escaped-Varianten. Die WordPress-Codierungsstandards empfehlen echo esc_html__() gegenüber _e(). Die Escaped-Form macht das Escaping der Ausgabe explizit und verhindert XSS am Punkt der Ausgabe:

// Return a translated string
$label = __( 'Settings', 'my-plugin' );

// Echo a translated string, escaped for HTML
echo esc_html__( 'Settings saved.', 'my-plugin' );

Strings mit Variablen. Verketten Sie keine Variablen in Strings. Übersetzer sehen nur Fragmente und können Wörter für Sprachen mit anderer Syntax nicht umstellen. Verwenden Sie printf() oder sprintf() mit einem Platzhalter. Fügen Sie einen Übersetzerkommentar hinzu, damit die Übersetzer wissen, was %s darstellt:

printf(
    /* translators: %s: the user's display name */
    esc_html__( 'Welcome back, %s.', 'my-plugin' ),
    esc_html( $display_name )
);

Pluralformen. Englische Plurale sind einfach (one comment, two comments). In anderen Sprachen ist dies komplizierter. Verwenden Sie _n(), um jede Pluralregel zu handhaben, die WordPress kennt:

printf(
    esc_html( _n( '%s comment', '%s comments', $count, 'my-plugin' ) ),
    number_format_i18n( $count )
);

Strings, die Kontext benötigen. Manche Wörter bedeuten je nach Einsatzort unterschiedliche Dinge. Verwenden Sie _x(), um Übersetzern den benötigten Kontext zu geben:

// "Export" as a noun (the file) vs. a verb (the action)
echo esc_html_x( 'Export', 'button label', 'my-plugin' );

Schritt 3: Internationalisieren Sie Ihre JavaScript-Strings

WordPress stellt das Paket wp-i18n zur Verfügung, damit Sie in JavaScript dieselben Gettext-Funktionen wie in PHP verwenden können. Wenn Sie Ihr Skript registrieren, deklarieren Sie wp-i18n als Abhängigkeit:

wp_register_script(
    'my-plugin-script',
    plugins_url( 'js/app.js', __FILE__ ),
    array( 'wp-i18n' ),
    '1.0.0',
    true
);

Dann in Ihrer JavaScript-Datei:

const { __, _n, sprintf } = wp.i18n;

const message = __( 'Settings saved.', 'my-plugin' );

Wenn Sie einen Bundler wie Webpack verwenden, installieren Sie @wordpress/babel-plugin-makepot. Es extrahiert übersetzbare Strings aus Ihrem Bundle als Teil Ihres Builds.

Schritt 4: Generieren Sie Ihre POT-Datei

Sobald Ihre Strings eingeschlossen sind, generieren Sie eine POT-Datei. Die POT ist die Quelldatei, mit der PTC (oder jeder Übersetzer) arbeitet. Sie enthält jeden übersetzbaren String, aber keine Übersetzungen.

wp i18n make-pot . languages/my-plugin.pot

WP-CLI scannt Ihre PHP-, JavaScript- und block.json-Dateien nach Gettext-Aufrufen. Es kompiliert diese in eine einzige POT-Datei. Wenn Ihr Team Composer verwendet, fügen Sie diesen Befehl als Composer-Skript hinzu. Das hält die Nutzung von WP-CLI im Team konsistent, ohne dass eine globale Installation erforderlich ist.

Die vollständige wp i18n-Befehlssuite deckt den Rest der Pipeline ab:

Sie benötigen kein Poedit. Alles in diesem Workflow läuft über WP-CLI und PTC. WP-CLI übernimmt die POT-Generierung und die MO/JSON-Kompilierung. PTC übernimmt die Übersetzung und liefert jedes von WordPress benötigte Dateiformat zurück. Poedit ist ein nützlicher Desktop-Editor für manuelle Übersetzungen, aber er ist nicht Teil dieses Workflows.

Übersetzen von POT-Dateien mit PTC

PTC wurde speziell für WordPress-Entwickler entwickelt. Starten Sie mit einer POT-Datei und erhalten Sie produktionsreife Übersetzungsdateien zurück. Die kostenlose 30-Tage-Testphase deckt bis zu 20.000 Wörter in zwei Sprachen ab.

Richten Sie Ihr erstes Übersetzungsprojekt ein

Laden Sie Ihre POT-Datei hoch. Wählen Sie aus, welche Ausgabeformate Sie benötigen. PTC liefert jede Kombination aus:

• .po-Dateien für jede Zielsprache.
• .mo-Dateien, kompiliert und versandbereit.
• .json-Dateien für Ihre JavaScript-Strings.
• .l10n.php-Dateien für schnelleres Laden unter WordPress 6.5+.

Der Einrichtungsassistent bittet Sie, Ihr Theme oder Plugin zu beschreiben. PTC nutzt die Beschreibung, um Übersetzungen mit der richtigen Tonalität und dem richtigen Kontext zu generieren. Fügen Sie in dieser Phase markenspezifische Begriffe zum Glossar hinzu. Das Glossar hält Namen, Funktionsbezeichnungen und jede andere Terminologie über alle Sprachen hinweg konsistent.

PTC analysiert beim Hochladen die Gettext-Struktur. Es erkennt Platzhalter (%s, %1$s, %d), Pluralformen (durch _n() extrahierte Einträge mit ihrem Plural-Forms-Header) und Kontexte (_x()-Einträge mit msgctxt). Anschließend generiert es die korrekten Pluralkategorien pro Sprache. Polnisch erhält one / few / many / other. Japanisch erhält nur other. Arabisch erhält sechs Formen.

Wechsel zur kontinuierlichen Lokalisierung

Sobald Ihre ersten Dateien übersetzt sind, wechseln Sie zu Pay-As-You-Go. Verbinden Sie PTC mit Ihrem GitHub-, GitLab- oder Bitbucket-Repository. Von diesem Zeitpunkt an laden Sie Dateien nicht mehr manuell hoch:

# .github/workflows/translate.yml
name: Regenerate POT for PTC
on:
  push:
    branches: [main]
    paths:
      - 'languages/my-plugin.pot'
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate POT
        run: |
          wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin
      - name: Trigger PTC translation
        run: |
          curl -X POST https://api.ptc.wpml.org/v1/projects/${{ secrets.PTC_PROJECT_ID }}/sync \
            -H "Authorization: Bearer ${{ secrets.PTC_API_KEY }}"

Sie haben zwei Möglichkeiten, dies zu automatisieren. Mit der Git-Integration überwacht PTC Ihr Repository und öffnet einen Pull Request mit aktualisierten Übersetzungen, wann immer sich die Quelldatei ändert. Um die Übersetzung stattdessen innerhalb Ihres eigenen CI-Jobs auszuführen, verwenden Sie das PTC CLI – es lädt die geänderte Datei hoch, wartet auf den Abschluss der Übersetzung und lädt die übersetzten Dateien herunter. Fertige Workflow-Vorlagen für GitHub Actions, GitLab CI und Bitbucket Pipelines finden Sie im Leitfaden zur CI/CD-Pipeline-Einrichtung.

Beide Abläufe liefern einen Pull Request oder einen Download mit den aktualisierten .po-, .mo-, .json- und .l10n.php-Dateien. Weitere Informationen finden Sie in der PTC-API-Referenz für den vollständigen Webhook und die REST-API.

Ob Sie .mo-Dateien in Ihr Repository committen, hängt von der Team-Richtlinie ab. Viele Plugins generieren diese stattdessen zum Zeitpunkt des Releases. Die CI-Integration von PTC erstellt sie bei jedem Übersetzungslauf. Checken Sie diese nur ein, wenn Sie übersetzte Dateien in der Versionshistorie haben möchten.

Laden von Übersetzungen in WordPress

Wenn Sie die übersetzten Dateien vorliegen haben, platzieren Sie diese korrekt und teilen Sie WordPress mit, wo sie zu finden sind. Zuerst muss der Dateiname korrekt gewählt werden. WordPress sucht nach Übersetzungsdateien nach einem bestimmten Benennungsmuster. Ein Dateiname, der nicht übereinstimmt, führt dazu, dass die Datei nicht geladen wird.

Die richtigen Dateinamen wählen

Locale-Codes folgen dem Format sprache_LAND. de_DE ist Deutsch (Deutschland). fr_FR ist Französisch (Frankreich). pt_BR ist Portugiesisch (Brasilien). zh_CN ist vereinfachtes Chinesisch. Das WordPress-Übersetzungsportal listet alle unterstützten Locales auf.

Der erwartete Dateiname hängt davon ab, wo Sie die Datei platzieren:

Themes verwenden eine kürzere Benennungskonvention, wenn Dateien innerhalb des Themes gebündelt sind. Im globalen Sprachverzeichnis verwenden sowohl Plugins als auch Themes das Muster {text-domain}-{locale}.

Laden von Übersetzungen für Plugins (PHP)

Registrieren Sie Übersetzungen bei WordPress über den init-Hook. Verwenden Sie nicht plugins_loaded. Dies löst in aktuellen WordPress-Versionen eine Deprecation-Warnung aus:

add_action( 'init', function () {
    load_plugin_textdomain(
        'my-plugin',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages/'
    );
} );

Laden von Übersetzungen für Themes (PHP)

Verwenden Sie load_theme_textdomain(), eingehängt in after_setup_theme:

add_action( 'after_setup_theme', function () {
    load_theme_textdomain( 'my-theme', get_template_directory() . '/languages' );
} );

Laden von JavaScript-Übersetzungen

Rufen Sie nach der Registrierung Ihres Skripts (Schritt 3 oben) wp_set_script_translations() auf. WordPress lädt dann die JSON-Übersetzungen für dieses Skript-Handle:

add_action( 'init', function () {
    wp_set_script_translations(
        'my-plugin-script',
        'my-plugin',
        plugin_dir_path( __FILE__ ) . 'languages'
    );
} );

Überprüfung des Ladevorgangs

1. Stellen Sie Ihre WordPress-Website-Sprache auf eine Ziel-Locale ein. Die Einstellung finden Sie unter Einstellungen > Allgemein > Sprache der Website.
2. Laden Sie das Frontend und die Admin-Seiten neu, die Ihr Plugin oder Theme rendert.
3. Strings, die in __() oder esc_html__() eingeschlossen sind, sollten in der neuen Sprache erscheinen.

Falls etwas fehlt, lesen Sie WordPress-Plugin-Übersetzungen werden nicht angezeigt? Fehlende Übersetzungen beheben für die häufigsten Ursachen.

Rechts-nach-links-Sprachen und bidirektionale Layouts

Der Übersetzungs-Workflow ist für Rechts-nach-links-Sprachen (RTL) derselbe. Arabisch, Hebräisch, Persisch und Urdu nutzen dieselbe POT/PO/MO-Pipeline.

Der zusätzliche Schritt besteht darin, sicherzustellen, dass Ihr Theme RTL-Styles unterstützt. WordPress lädt automatisch eine rtl.css-Datei, falls diese in Ihrem Theme-Verzeichnis existiert. Verwenden Sie die Funktion is_rtl(), um bedingt RTL-spezifische Styles oder Skripte anzuwenden.

Lokalisierung von Daten, Zahlen und Währungen

Ein übersetzter String ist nicht alles. Daten, Zahlen und Währungen müssen ebenfalls der Locale des Benutzers folgen. Verwenden Sie die integrierten Formatierungsfunktionen von WordPress anstelle der nativen PHP-Funktionen:

• date_i18n() formatiert Daten gemäß der aktiven Locale.
• number_format_i18n() formatiert Zahlen mit Locale-bewussten Dezimal- und Tausendertrennzeichen.

Diese Funktionen sind nicht Teil des Workflows für Übersetzungsdateien. Sie sind wichtig für eine vollständig lokalisierte Benutzererfahrung.

Internationalisierung von Block-Editor-Blöcken (Gutenberg)

Blöcke fügen der Standard-Pipeline zwei zusätzliche Schritte hinzu:

• JavaScript-Übersetzungen benötigen eine .json-Datei pro Locale. Generieren Sie diese aus der .po mit wp i18n make-json.
• Das Editor-Skript des Blocks benötigt wp_set_script_translations() in PHP. Dies teilt WordPress mit, dem Block die JSON-Datei bereitzustellen.

Die vom Block gerenderte Ausgabe im Frontend verwendet dieselben __()-Aufrufe wie Ihr übriges PHP. Hier ist kein zusätzlicher Aufwand nötig.

Übersetzung Ihrer README und des WordPress.org-Eintrags

Ihre readme.txt ist keine Ressourcendatei. WP-CLI wird sie beim Generieren einer POT-Datei nicht erfassen. Um sie zu übersetzen, nutzen Sie die Funktion Paste to Translate von PTC. Fügen Sie den Inhalt ein, wählen Sie Ihre Zielsprachen und laden Sie das Ergebnis herunter. Kunden-E-Mails, die vom Plugin gesendet werden, und die Beschreibung der WordPress.org-Plugin-Seite werden auf dieselbe Weise übersetzt, alles im selben Projekt, damit die Terminologie konsistent bleibt.

Wenn Ihr Plugin oder Theme auf WordPress.org gelistet ist, erscheint die übersetzte Beschreibung auf dem Tab „Details“ des Plugins in der Sprache des Benutzers. Um Übersetzungen dort live zu schalten, folgen Sie dem WordPress.org-Importprozess.

Plugin-Benutzerinhalte mit der PTC-API übersetzen

Plugins, die benutzergenerierte Daten speichern (Forum-Plugins, Review-Plugins, Kommentar-Plugins), können diese Inhalte bei Eingang übersetzen. Die PTC-REST-API übersetzt Benutzerbeiträge, Kommentare und Rezensionen auf Abruf mit Bearer-Token-Authentifizierung unter Verwendung desselben Glossars und derselben Markenstimme wie Ihre .po-Dateien.

Visuelle Übersetzungsprüfung Ihres gerenderten Themes oder Plugins – Release ohne manuelle QA pro Sprache

Eine übersetzte .po-Datei ist notwendig, aber nicht ausreichend. Das übersetzte Theme oder Plugin muss noch verifiziert werden:

• Ein übersetztes Label könnte im Deutschen über eine Schaltfläche auf der Einstellungsseite hinauslaufen (Überlauf).
• „Submit“ könnte im Französischen als Substantiv übersetzt werden, obwohl die Admin-Aktion ein Verb erforderte.
• Ein hartcodierter englischer String außerhalb von __() wird unabhängig davon, in wie vielen Sprachen Sie ausliefern, unübersetzt gerendert.

Die visuelle Übersetzungsprüfung von PTC ersetzt den manuellen QA-Durchgang. WordPress-Themes und -Plugins werden im Browser gerendert (sowohl wp-admin als auch das Frontend). Die richtige Variante hierfür ist die Browser-Erweiterung.

Installieren Sie diese einmal. Zeichnen Sie einen Rundgang durch Ihr Theme oder Plugin auf einer Testseite auf. Decken Sie Einstellungsseiten, Admin-Aktionen und die Frontend-Ausgabe ab. PTC spielt die Aufzeichnung nach jedem Übersetzungs-Update in jeder Zielsprache ab. Es erfasst jeden Bildschirm und meldet zwei Arten von Korrekturen zurück:

• Korrekturen in den .po-Dateien, wenn PTC diese kontrolliert. PTC übersetzt eine falsche Bedeutung neu, wählt ein kürzeres Synonym, das auf eine Schaltfläche passt, oder generiert eine Pluralform neu.
• Prompts für Cursor oder Claude Code, wenn das Problem in Ihrem PHP- oder JavaScript-Code liegt. Beispiele hierfür sind ein fehlender __()-Wrapper, ein hartcodierter englischer String oder ein durch Verkettung aufgebauter Satz, der sprintf( __( ... ) ) verwenden sollte.

Sie liefern pro Release ein verifiziertes, mehrsprachiges Plugin aus. Der Aufwand für die manuelle QA entfällt.

Preise: 30-Tage-Testphase, dann Pay-As-You-Go

Die kostenlose Testphase deckt 20.000 Wörter in 2 Sprachen ab, ohne dass eine Kreditkarte erforderlich ist. Wenn die Testphase endet, bietet PTC Pay-As-You-Go an. Kein Abonnement. Keine Mindestverpflichtung. Die ersten 500 Wörter pro Monat sind kostenlos. Sie zahlen nur für den Rest. Die Preisseite enthält einen Kostenrechner. Melden Sie sich mit einer Firmen-E-Mail-Adresse für eine erweiterte Business-Testphase an.

Bereit, ein verifiziertes Plugin oder Theme auszuliefern?

PTC generiert die Übersetzungen und prüft das gerenderte Plugin. Sie bestätigen das Ergebnis und veröffentlichen es. Der gesamte Kreislauf läuft ohne manuelle QA ab:

1. Generieren Sie Ihre .pot-Datei mit wp i18n make-pot.
2. Laden Sie diese bei PTC hoch und erhalten Sie in wenigen Minuten .po-, .mo-, .l10n.php- und .json-Dateien zurück.
3. Installieren Sie die Browser-Erweiterung, um das laufende Plugin in jeder Zielsprache zu verifizieren.

Starten Sie Ihre kostenlose 30-Tage-Testphase – 20.000 Wörter geschenkt, keine Kreditkarte erforderlich.

Verwandte Themen:

• PO-Dateien online mit KI übersetzen – die kanonische Seite für die PO/POT-Übersetzung.
• GlotPress vs. PTC für die Übersetzung von WordPress-Plugins/Themes – wann Sie Community-Übersetzung vs. PTC wählen sollten.
• WordPress-Plugin-Übersetzungen werden nicht angezeigt? Fehlende Übersetzungen beheben – Leitfaden zur Fehlerbehebung.
• So importieren Sie Theme- und Plugin-Übersetzungen in WordPress.org – CLPTE-Prozess und eine schnellere Alternative.
• PTC-API-Referenz – REST-Endpunkte für die CI-Integration.