i18n für WordPress-Themes und -Plugins: Code übersetzbar machen

Machen Sie ein WordPress-Theme oder -Plugin übersetzbar: Text Domain, __() und _n(), eine POT-Datei mit WP-CLI, laden Sie dann .mo-, .json- und .l10n.php-Dateien.

Lokalisiere diese App mit der PTC ins Deutsche und Spanische.

Machen Sie Ihr WordPress-Theme oder -Plugin bereit für die Übersetzung. Dieser Leitfaden behandelt Text Domains, gettext-Funktionen, die POT-Generierung und den Lademechanismus, der den Benutzern Übersetzungen anzeigt. Die PTC (Private Translation Cloud) übersetzt dann die Ressourcendateien und überprüft das gerenderte Theme oder Plugin in jeder Sprache visuell.

Möchten Sie eine von Ihnen betriebene WordPress-Website übersetzen und nicht selbst geschriebenen Code? Verwenden Sie das WPML.

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, gehen Sie zur PO-Dateien-Seite für den 3-Schritte-Workflow.

Am Ende dieses Leitfadens wird Ihr Theme oder Plugin:

• Korrekt nach den WordPress-Programmierstandards internationalisiert sein.
• Von der PTC in 40+ Sprachen übersetzbar sein.
• Über WordPress.org-Sprachpakete verteilbar sein.
• Bei jedem Release mit der visuellen Übersetzungsprüfung der PTC verifizierbar sein.

Was ist WordPress-Internationalisierung?

Internationalisierung (i18n) ist die Arbeit, Ihren Code so vorzubereiten, dass er übersetzt werden kann. Die 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 benutzerseitigen String in gettext-Funktionen einschließen, damit WordPress ihn zur Laufzeit austauschen kann.
• Eine Text Domain definieren, die Ihre Übersetzungen an Ihr Projekt bindet.
• Eine POT-Datei generieren, mit der Übersetzer (oder die PTC) arbeiten.

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

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

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

• POT (Portable Object Template). Die Quelldatei, die aus Ihrem Code generiert wird. Sie listet jeden übersetzbaren String ohne angehängte Übersetzungen auf. Diese übergeben Sie der PTC.
• PO (Portable Object). Eine Kopie der POT-Datei mit hinzugefügten Übersetzungen für eine bestimmte Sprache. Klartext, menschenlesbar. Die PTC gibt eine PO-Datei pro Zielsprache zurück.
• MO (Machine Object). Die kompilierte Binärversion einer PO-Datei. WordPress liest MO-Dateien zur Laufzeit, da sie 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, die in WordPress 6.5 eingeführt wurde. 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 bei den unterstützten WordPress-Versionen strikt besser als MO.

Warum Community-Übersetzungen nicht ausreichen

WordPress.org bietet Community-Übersetzungen über GlotPress an. In der Praxis deckt dies jedoch 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 Locales knapp. Eine Handvoll Plugins mit riesigen Nutzerbasen zieht Übersetzer an. Die meisten tun das nicht.
• Es kann Monate oder Jahre dauern, bis Übersetzungen erscheinen, wenn sie überhaupt erscheinen. Wenn Sie möchten, dass Nutzer Ihr Plugin oder Theme vom ersten Tag an in ihrer Sprache sehen, können Sie sich nicht auf die Community verlassen.

Dieser Leitfaden geht davon aus, dass Sie eine konsistente, vollständige Übersetzungsabdeckung nach einem Release-Zeitplan wünschen, den Sie kontrollieren. Genau das liefert die PTC.

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

Eine nicht übereinstimmende Text Domain oder ein nicht eingeschlossener String bedeutet, dass dieser Text niemals in Ihrer übersetzten Ausgabe erscheinen wird. Die Details sind wichtig.

Schritt 1: Definieren Sie Ihre Text Domain und den Domain Path

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

Deklarieren Sie sie 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 Path teilt WordPress mit, wo sich Ihre Übersetzungsdateien relativ zum Stammverzeichnis des Plugins oder Themes befinden. /languages ist der Standard.

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

Jeder String, der übersetzbar sein soll, muss in eine der gettext-Funktionen von WordPress eingeschlossen werden. Zur Laufzeit suchen diese Funktionen die korrekte Übersetzung heraus. Wird keine gefunden, greifen sie auf den ursprünglichen String als Fallback zurück.

Einfache Strings. Verwenden Sie __(), wenn Sie einen String zurückgeben müssen. Verwenden Sie für die HTML-Ausgabe die maskierten Varianten. Die WordPress-Programmierstandards empfehlen echo esc_html__() gegenüber _e(). Die maskierte Form macht das Maskieren der Ausgabe explizit und verhindert XSS am Ausgabepunkt:

// 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 Übersetzer wissen, wofür %s steht:

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

Pluralformen. Englische Pluralformen sind einfach (one comment, two comments). Andere Sprachen sind es nicht. 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. Einige Wörter bedeuten je nach Verwendungsort 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 verwenden können, die Sie in PHP nutzen. 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 als Teil Ihres Builds aus Ihrem Bundle.

Schritt 4: Generieren Sie Ihre POT-Datei

Sobald Ihre Strings eingeschlossen sind, generieren Sie eine POT-Datei. Die POT-Datei ist die Quelldatei, mit der die 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 sie in eine einzige POT-Datei. Wenn Ihr Team Composer verwendet, fügen Sie diesen Befehl als Composer-Skript hinzu. Das hält die WP-CLI-Nutzung im gesamten Team ohne globale Installation konsistent.

Die vollständige Befehlssuite für wp i18n deckt den Rest der Pipeline ab:

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

POT-Dateien mit der PTC übersetzen

Die PTC wurde speziell für WordPress-Entwickler entwickelt. Starten Sie mit einer POT-Datei und erhalten Sie produktionsreife Übersetzungsdateien zurück. Die 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, welche Ausgabeformate Sie benötigen. Die PTC gibt eine beliebige Kombination aus Folgendem zurück:

• .po-Dateien für jede Zielsprache.
• .mo-Dateien, kompiliert und bereit zur Veröffentlichung.
• .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. Die PTC nutzt die Beschreibung, um Übersetzungen mit der richtigen Tonalität und dem passenden Kontext zu generieren. Fügen Sie in dieser Phase markenspezifische Begriffe zum Glossar hinzu. Das Glossar hält Namen, Funktionsbezeichnungen und jegliche andere Terminologie über alle Sprachen hinweg konsistent.

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

Wechseln Sie zur kontinuierlichen Lokalisierung

Sobald Ihre ersten Dateien übersetzt sind, führen Sie ein Upgrade auf Pay-As-You-Go durch. Verbinden Sie die PTC mit Ihrem GitHub-, GitLab- oder Bitbucket-Repository. Ab diesem Zeitpunkt laden Sie Dateien nicht mehr manuell hoch.

Committen Sie eine .ptc-config.yml, die Ihre Quelldatei benennt und angibt, wohin die Übersetzungen gehören:

# .ptc-config.yml
source_locale: en
files:
  - file: languages/my-plugin.pot
    output: languages/my-plugin-{{lang}}.po
    additional_translation_files:
      - type: mo
        path: languages/my-plugin-{{lang}}.mo

Fügen Sie dann die PTC Translate action zu Ihrem Workflow hinzu. Sie trägt eine gepinnte Version der PTC-CLI in sich, sodass Ihr Build zur Laufzeit nichts herunterlädt:

# .github/workflows/translate.yml
name: Regenerate POT for PTC
on:
  push:
    branches: [main]
    paths:
      - 'languages/my-plugin.pot'
  workflow_dispatch: {}

jobs:
  translate:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - name: Generate POT
        run: |
          wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin
      - uses: OnTheGoSystems/ptc-action@v1
        with:
          api-token: ${{ secrets.PTC_API_TOKEN }}
          create-pr: true

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

Beide Workflows liefern einen Merge Request oder Download mit den aktualisierten .po-, .mo-, .json- und .l10n.php-Dateien. Weitere Informationen zum vollständigen Webhook und zur REST-API finden Sie in der PTC-API-Referenz.

Ob Sie .mo-Dateien in Ihr Repository committen, hängt von den Richtlinien Ihres Teams ab. Viele Plugins generieren sie stattdessen zum Release-Zeitpunkt. Die CI-Integration der PTC erstellt sie bei jedem Übersetzungsdurchlauf. Checken Sie sie nur ein, wenn Sie übersetzte Dateien in der Versionshistorie haben möchten.

Übersetzungen in WordPress laden

Sobald Sie die übersetzten Dateien haben, platzieren Sie sie korrekt und teilen Sie WordPress mit, wo sie zu finden sind. Der Dateiname steht an erster Stelle. WordPress sucht nach Übersetzungsdateien anhand eines bestimmten Benennungsmusters. Ein Dateiname, der nicht übereinstimmt, führt dazu, dass die Datei nicht geladen wird.

Die richtigen Dateinamen wählen

Locale-Codes folgen dem Format language_COUNTRY. de_DE ist Deutsch (Deutschland). fr_FR ist Französisch (Frankreich). pt_BR ist Portugiesisch (Brasilien). zh_CN ist Chinesisch (vereinfacht). Das WordPress-Übersetzungsportal listet jedes unterstützte Locale 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}.

Übersetzungen für Plugins laden (PHP)

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

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

Übersetzungen für Themes laden (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' );
} );

JavaScript-Übersetzungen laden

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'
    );
} );

Das Laden überprüfen

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

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

Ihre Übersetzungen zu den Benutzern bringen: zwei Wege

Sobald die PTC Ihre Dateien übersetzt hat, veröffentlichen Sie sie auf einem von zwei Wegen.

Weg 1: Veröffentlichen Sie Übersetzungen über WordPress.org-Sprachpakete (CLPTE)

Gesamtdauer: 4–6 Tage.

Schritt 1: Erstellen Sie ein CLPTE-Konto

Die Rolle des CLPTE (Cross-Locale Project Translation Editor) ermöglicht es Ihnen, Übersetzungen im Namen Ihres Themes oder Plugins für jede Zielsprache über ein einziges Konto einzureichen. Ein reguläres Übersetzungsredakteur-Konto gilt pro Sprache; der CLPTE nicht.

Wenn Sie bereits ein Konto auf WordPress.org haben, stoßen Sie möglicherweise auf das Problem, dass Ihr neues CLPTE-Konto deaktiviert wird. WordPress erlaubt keine mehreren Konten. Um dies zu beheben, senden Sie eine E-Mail an forum-password-resets@wordpress.org und erklären Sie, dass Sie versuchen, ein CLPTE-Konto zu erstellen. Es hilft sowohl, dem Moderator die relevante Polyglots-Dokumentation mitzuteilen, als auch das Polyglots-Team in Slack anzupingen.

Geschätzte Dauer: ~3–5 Tage (einschließlich Wartezeit, falls Ihr neues Konto deaktiviert wird).

Schritt 2: Beantragen Sie CLPTE-Zugriff im Polyglots-Blog

Sobald Ihr Konto aktiviert ist, posten Sie eine Anfrage im WordPress.org-Polyglots-Blog. Folgen Sie deren Vorlage:

PTE/CLPTE Request

Plugin URL: https://wordpress.org/plugins/my-plugin/
Authors / Editors: @your-wp-username
Type of request: CLPTE

Sie erhalten eine Benachrichtigung, wenn Ihre Anfrage genehmigt wird.

Geschätzte Dauer: ~1 Tag (Das globale Polyglots-Team prüft Anfragen in Schüben).

Schritt 3: Importieren Sie die übersetzten .po-Dateien

1. Melden Sie sich mit Ihrem CLPTE-Konto bei https://translate.wordpress.org/ an.
2. Gehen Sie zur Übersetzungsprojekt-Seite Ihres Plugins oder Themes (zum Beispiel translate.wordpress.org/projects/wp-plugins/{your-plugin-slug}/).
3. Öffnen Sie das lokale Projekt für jede Sprache, die Sie übersetzt haben.
4. Scrollen Sie nach unten und klicken Sie auf Übersetzungen importieren.
5. Laden Sie Ihre .po- (oder .mo-) Datei hoch.
6. Markieren Sie die importierten Strings im Übersetzungseditor als „current“ (aktuell). Genehmigte Strings fließen in die nächste Sprachpaket-Generierung ein (normalerweise täglich).
7. Wiederholen Sie dies für jede Zielsprache. Jedes Locale hat seine eigene Übersetzungsseite.

Geschätzte Dauer: ~10–30 Minuten pro Sprache.

Nach einem Sprachpaket-Zeitfenster von 24–48 Stunden beginnen Websites, auf denen Ihr Plugin läuft, die neuen Übersetzungen durch die automatischen Sprachpaket-Updates von WordPress zu erhalten. Benutzer sehen keine Aufforderung zum Upgrade. Die Übersetzungen erscheinen einfach.

Was der CLPTE für Sie tun wird und was nicht

• Sie können keine bestehenden Community-Übersetzungen ersetzen. Nur unübersetzte Strings werden importiert. Das Aktualisieren einer bestehenden Community-Übersetzung erfordert den Standardprozess und das Warten auf die Prüfung durch das Locale-Team.
• Updates erfordern manuelle Uploads für jedes Release. Jedes neue Release bedeutet eine neue Runde von Uploads.
• Die Kontoerstellung und -genehmigung dauern in der Regel insgesamt 4–6 Tage.

Weg 2: Bündeln Sie die .mo-Dateien in Ihrem Plugin oder Theme

Wenn Ihre Übersetzungen schneller live gehen müssen, als es der CLPTE zulässt, oder wenn Sie sich lieber nicht auf die Verteilungs-Pipeline von WordPress.org verlassen möchten, bündeln Sie die .mo-Dateien direkt in Ihrem Plugin- oder Theme-Release. Gesamtdauer: 15–30 Minuten.

Schritt 1: Fügen Sie die .mo-Dateien zum /languages/-Verzeichnis hinzu

Platzieren Sie Ihre kompilierten .mo-Dateien im /languages/-Verzeichnis Ihres Plugins oder Themes, damit WordPress sie beim Laden Ihrer Text Domain findet:

my-plugin/
├─ my-plugin.php
├─ readme.txt
├─ languages/
│  ├─ my-plugin-es_ES.mo
│  ├─ my-plugin-es_ES.po
│  ├─ my-plugin-fr_FR.mo
│  ├─ my-plugin-fr_FR.po
│  ├─ my-plugin-de_DE.mo
│  └─ my-plugin-de_DE.po

Verwenden Sie dieselbe Text Domain in den Namen Ihrer Übersetzungsdateien und Ihren load_plugin_textdomain()- oder load_theme_textdomain()-Aufrufen.

Schritt 2: Bevorzugen Sie Ihre gebündelten Dateien gegenüber Community-Übersetzungen

Standardmäßig priorisiert WordPress Community-Übersetzungen von WordPress.org gegenüber gebündelten Übersetzungen. Um sicherzustellen, dass Ihr Plugin oder Theme stattdessen die gebündelten .mo-Dateien verwendet, fügen Sie den Filter load_textdomain_mofile hinzu.

Für Plugins fügen Sie dies in Ihre Haupt-Plugin-Datei ein (z. B. my-plugin.php):

function my_plugin_load_embedded_translation_file( $mofile, $domain ) {
    if ( 'my-domain' === $domain && false !== strpos( $mofile, WP_LANG_DIR . '/plugins/' ) ) {
        $locale = apply_filters( 'plugin_locale', determine_locale(), $domain );
        $local_mofile = WP_PLUGIN_DIR . '/' . dirname( plugin_basename( __FILE__ ) ) .
                        '/languages/' . $domain . '-' . $locale . '.mo';

        if ( file_exists( $local_mofile ) ) {
            return $local_mofile;
        }
    }
    return $mofile;
}
add_filter( 'load_textdomain_mofile', 'my_plugin_load_embedded_translation_file', 10, 2 );

Für Themes fügen Sie dies in die functions.php Ihres Themes ein:

function my_theme_load_embedded_translation_file( $mofile, $domain ) {
    if ( 'my-domain' === $domain && false !== strpos( $mofile, WP_LANG_DIR . '/themes/' ) ) {
        $locale = apply_filters( 'theme_locale', determine_locale(), $domain );
        $local_mofile = get_template_directory() . '/languages/' . $locale . '.mo';

        if ( file_exists( $local_mofile ) ) {
            return $local_mofile;
        }
    }
    return $mofile;
}
add_filter( 'load_textdomain_mofile', 'my_theme_load_embedded_translation_file', 10, 2 );

Bestätigen Sie auch, dass Ihr Plugin oder Theme die Text Domain am richtigen Hook lädt:

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

Schritt 3: Überprüfen Sie, ob die gebündelten Übersetzungen auf einer Test-Website geladen werden

Installieren Sie Ihr Plugin oder Theme auf einer Test-Website und stellen Sie WordPress auf eine der Sprachen um, die Sie bereitgestellt haben:

1. Gehen Sie zu Einstellungen > Allgemein > Sprache der Website und wählen Sie eine Sprache aus, deren .mo-Datei sich in Ihrem /languages/-Ordner befindet.
2. Laden Sie eine Seite oder einen Bildschirm, der Strings enthält, von denen Sie wissen, dass sie übersetzt sind.
3. Bestätigen Sie, dass die Strings in der richtigen Sprache erscheinen und mit den von Ihnen hinzugefügten Übersetzungen übereinstimmen.

Wenn Sie immer noch alte Community-Übersetzungen sehen, überprüfen Sie das Snippet in Schritt 2. Es muss WordPress korrekt auf Ihre gebündelten .mo-Dateien verweisen.

Committen Sie die .mo-Dateien, taggen Sie ein Release und pushen Sie es wie gewohnt über SVN zu wordpress.org.

Der Kompromiss zwischen Geschwindigkeit und kanonischer Verteilung

• Pro: sofort verfügbar. Neue Übersetzungen sind live in dem Moment, in dem Benutzer Ihr Plugin aktualisieren (oder es zum ersten Mal installieren). Keine mehrtägige Wartezeit auf den CLPTE. Kein Genehmigungszyklus durch das Polyglots-Team.
• Pro: Sie kontrollieren den Workflow. Der Übersetzungszyklus entspricht exakt Ihrem Release-Zyklus.
• Pro: keine Abhängigkeit vom Plugin-Badge. Übersetzungen funktionieren, unabhängig davon, ob Ihr Plugin CLPTE-Berechtigungen hat oder nicht.
• Contra: Die Dateigröße des Plugins wächst. Jede .mo ist klein (typischerweise 5–50 KB), aber 20 Sprachen fügen dem Download ~500 KB hinzu.
• Contra: kein Auto-Update von Übersetzungen zwischen Plugin-Releases. Mit CLPTE werden auf wordpress.org aktualisierte Übersetzungen innerhalb von 48 Stunden an Benutzer verteilt, selbst wenn Sie kein neues Release veröffentlichen. Beim Bündeln werden Übersetzungen nur aktualisiert, wenn Sie ein neues Release veröffentlichen.
• Contra: kein „Übersetzt“-Badge. WordPress.org zeigt ein Translation-Completion-Badge auf Plugin-Einträgen basierend auf der Sprachpaket-Abdeckung an, nicht auf gebündelten .mo-Dateien. Bündelung allein bringt Ihnen dieses Badge nicht ein.

Welcher Weg passt zu Ihrem Release-Zyklus?

Der duale Ansatz ist üblich: Bündeln Sie MO-Dateien für die sofortige Verfügbarkeit und reichen Sie sie beim CLPTE für die kanonische Verteilung ein. Benutzer erhalten die gebündelten Übersetzungen beim Update; das Language-Pack-Overlay aktualisiert sie zwischen den Releases.

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 verwenden dieselbe POT/PO/MO-Pipeline.

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

Datumsangaben, Zahlen und Währungen lokalisieren

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

• date_i18n() formatiert Datumsangaben entsprechend dem aktiven Locale.
• number_format_i18n() formatiert Zahlen mit locale-abhängigen Dezimal- und Tausendertrennzeichen.

Diese Funktionen sind nicht Teil des Übersetzungsdatei-Workflows. Sie sind wichtig für ein vollständig lokalisiertes Erlebnis.

Block-Editor-Blöcke (Gutenberg) internationalisieren

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. Das teilt WordPress mit, das JSON an den Block auszuliefern.

Die vom Block gerenderte Ausgabe im Frontend verwendet dieselben __()-Aufrufe wie Ihr restliches PHP. Hier ist keine zusätzliche Arbeit erforderlich.

Ihre README und Ihren WordPress.org-Eintrag übersetzen

Ihre readme.txt ist keine Ressourcendatei. WP-CLI wird sie beim Generieren einer POT-Datei nicht erfassen. Um sie zu übersetzen, verwenden Sie die Funktion Paste to Translate der PTC. Fügen Sie den Inhalt ein, wählen Sie Ihre Zielsprachen und laden Sie das Ergebnis herunter. Kundenorientierte E-Mails, die vom Plugin gesendet werden, und die Beschreibung der WordPress.org-Plugin-Seite werden auf dieselbe Weise übersetzt, alle 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. Damit die Übersetzungen dort live gehen, folgen Sie dem WordPress.org-Importprozess.

Benutzerinhalte von Plugins mit der PTC-API übersetzen

Plugins, die nutzergenerierte Daten speichern (Foren-Plugins, Bewertungs-Plugins, Kommentar-Plugins), können diese Inhalte übersetzen, sobald sie eintreffen. Die PTC-REST-API übersetzt Benutzerbeiträge, Kommentare und Bewertungen bei Bedarf mit Bearer-Token-Authentifizierung, wobei dasselbe Glossar und dieselbe Markenstimme wie bei Ihren .po-Dateien verwendet werden.

Visuelle Übersetzungsprüfung Ihres gerenderten Themes oder Plugins – veröffentlichen Sie ohne manuelle QA pro Sprache

Eine übersetzte .po-Datei ist notwendig, aber nicht ausreichend. Das übersetzte Theme oder Plugin erfordert weiterhin eine Überprüfung:

• Ein übersetztes Label kann auf Deutsch über einen Button auf der Einstellungsseite hinausragen.
• „Submit“ könnte im Französischen als Substantiv übersetzt werden, wenn die Admin-Aktion ein Verb benötigte.
• Ein hardcodierter englischer String außerhalb von __() wird unübersetzt dargestellt, unabhängig davon, in wie vielen Sprachen Sie veröffentlichen.

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

Installieren Sie sie einmal. Zeichnen Sie einen Rundgang durch Ihr Theme oder Plugin auf einer Test-Website auf. Decken Sie Einstellungsseiten, Admin-Aktionen und die Ausgabe im Frontend ab. Die PTC spielt die Aufzeichnung nach jedem Übersetzungsupdate in jeder Zielsprache erneut ab. Sie erfasst jeden Bildschirm und meldet zwei Arten von Korrekturen zurück:

• Korrekturen in den .po-Dateien, wenn die PTC diese kontrolliert. Die PTC übersetzt eine falsche Bedeutung neu, wählt ein kürzeres Synonym, das auf einen Button 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 hardcodierter englischer String oder ein durch Verkettung gebildeter Satz, der sprintf( __( ... ) ) verwenden sollte.

Sie veröffentlichen pro Release ein verifiziertes, mehrsprachiges Plugin. Der Restaufwand der manuellen QA entfällt.

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

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

Bereit, ein verifiziertes Plugin oder Theme zu veröffentlichen?

Die PTC generiert die Übersetzungen und überprü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 sie in die PTC hoch und erhalten Sie .po-, .mo-, .l10n.php- und .json-Dateien in wenigen Minuten zurück.
3. Installieren Sie die Browser-Erweiterung, um das laufende Plugin in jeder Zielsprache zu überprüfen.

Starten Sie Ihre 30-Tage-Testphase – 20.000 Wörter auf unsere Kosten, keine Kreditkarte erforderlich.

Verwandte Themen:

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

Zuletzt aktualisiert: 11. November 2026