PTC
Registrieren Upgrade auf Pro Ihr Konto

Werden WordPress-Plugin-Übersetzungen nicht angezeigt? Fehlende Übersetzungen beheben

Fehlen nach einem PTC-Durchlauf Übersetzungen? Vier Prüfungen finden fast jede Ursache. Prüfen Sie, ob der String die PTC erreicht hat, ob der Dateiname der .mo den Erwartungen von WordPress entspricht und ob die Text Domain in Ihrem Code konsistent ist. Dieser Leitfaden geht jede Prüfung in der Reihenfolge durch, in der sie durchgeführt werden sollte.

Dieselbe Diagnosereihenfolge funktioniert unabhängig davon, ob Sie mit der PTC (Private Translation Cloud), GlotPress oder einem anderen gettext-basierten Tool übersetzt haben. Die Fehlerquellen sind in der WordPress-i18n-Pipeline systembedingt und liegen nicht an einem bestimmten Übersetzer.

Bestätigen Sie, dass der String die PTC erreicht hat

Die erste Frage ist, ob sich der String in Ihrem PTC-Projekt befindet. Wenn ein String nicht in Ihre .pot-Datei extrahiert wurde, hat die PTC ihn nie gesehen. Die .po-Datei enthält keine Übersetzung dafür. Das ausgeführte Plugin zeigt den Fallback der Ausgangssprache an.

So prüfen Sie das:

  1. Öffnen Sie den betroffenen String im ausgeführten Plugin und kopieren Sie seinen genauen Text.
  2. Gehen Sie zu Ihrem PTC-Dashboard, öffnen Sie den Tab Translations und suchen Sie nach dem String.
  3. Wenn er nicht dort ist, hat die PTC ihn nie erhalten.

Es folgen drei häufige Ursachen.

Ursache 1: Der String fehlt in Ihrer POT-Datei

wp i18n make-pot extrahiert nur Strings innerhalb der erkannten i18n-Funktionen. Das bedeutet __(), _e(), _n(), _x() und die Escaped-Varianten mit der richtigen Text Domain. Strings in der falschen Domain werden übersprungen. Hartcodierte Strings außerhalb einer i18n-Funktion werden übersprungen.

Führen Sie die Extraktion erneut aus und überprüfen Sie, ob der String nun in der .pot ist:

wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin
grep "Save Changes" languages/my-plugin.pot

Wenn grep den String mit einem msgid zurückgibt, funktioniert die Extraktion. Laden Sie die neue .pot wieder in die PTC hoch und übersetzen Sie erneut. Wenn grep nichts zurückgibt, ist der String hartcodiert und nicht in __() eingeschlossen. Das ist Ihr Fehler. Schließen Sie den String ein und extrahieren Sie ihn erneut.

Ursache 2: Der Text ist nicht in eine gettext-Funktion eingeschlossen

Jeder übersetzbare String in Ihrem Code benötigt einen Wrapper. Verwenden Sie __(), esc_html__(), _e(), _n() oder _x() mit der korrekten Text Domain:

__( 'Hello, world!', 'your-plugin' );

Ursache 3: JavaScript-Strings wurden nicht als übersetzbar markiert

Wenn Ihr Plugin übersetzbaren Text in JavaScript enthält:

  1. Gehen Sie im PTC-Dashboard zu Einstellungen > Überwachte Dateien.
  2. Bearbeiten Sie die entsprechende Ressourcendatei und aktivieren Sie „Is this a WordPress project with localizable JavaScript?“

Dadurch wird die PTC angewiesen, JavaScript-Dateien nach übersetzbaren Strings zu durchsuchen. Die PTC generiert die Übersetzungen neu und öffnet einen neuen Merge Request mit den aktualisierten Dateien.

Stellen Sie dann sicher, dass WordPress weiß, wo die von der PTC erstellten .json-Übersetzungsdateien geladen werden sollen. Rufen Sie wp_set_script_translations() mit dem korrekten Pfad auf:

// For plugins
wp_set_script_translations(
    'script-handle',
    'text-domain',
    plugin_dir_path( __FILE__ ) . 'languages'
);

// For themes
wp_set_script_translations(
    'script-handle',
    'text-domain',
    get_template_directory() . '/languages'
);

Dadurch wird WordPress angewiesen, .json-Dateien aus Ihrem Plugin- oder Theme-Ordner zu laden.

Bestätigen Sie, dass WordPress Ihre .mo-Datei lädt

Wenn sich der String in der PTC befindet und die .mo-Datei im languages/-Verzeichnis Ihres Plugins existiert, das gerenderte Plugin aber immer noch Englisch anzeigt, kann WordPress die .mo-Datei nicht laden.

Diagnose 1: Ist die Locale der Website korrekt eingestellt? Gehen Sie in wp-admin zu Einstellungen > Allgemein > Sprache der Website und bestätigen Sie, dass sie mit Ihrer Zielsprache übereinstimmt. Stellen Sie sie beispielsweise auf „Español“ ein, um Spanisch zu testen. Wenn die Website auf Englisch ist, wird Ihre spanische .mo-Datei niemals geladen. Das ist kein Fehler.

Diagnose 2: Wird load_plugin_textdomain() tatsächlich ausgeführt? Fügen Sie eine temporäre Debug-Zeile hinzu:

add_action( 'init', function() {
    $loaded = load_plugin_textdomain(
        'my-plugin',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages'
    );
    error_log( 'my-plugin textdomain loaded: ' . var_export( $loaded, true ) );
} );

Laden Sie eine Seite neu und überprüfen Sie Ihr PHP-Fehlerprotokoll. loaded: true bedeutet, dass WordPress eine .mo-Datei für die aktuelle Locale gefunden und geladen hat. loaded: false bedeutet, dass dies nicht der Fall war. Die Ursache ist meist ein nicht übereinstimmender Dateiname (siehe nächster Abschnitt) oder ein falscher Verzeichnispfad.

Diagnose 3: Stimmt das Hook-Timing? load_plugin_textdomain() muss am init-Hook ausgeführt werden. Das ist der kanonische Hook, damit Übersetzungen auf Strings angewendet werden, die während der normalen Anfrageverarbeitung ausgegeben werden.

Diagnose 4: Überschreiben Community-Übersetzungen Ihre gebündelten Dateien? Standardmäßig priorisiert WordPress Übersetzungsdateien, die in /wp-content/languages/ gespeichert sind. Wenn Ihr Plugin oder Theme von der Community bereitgestellte Übersetzungen auf WordPress.org hat, können diese Dateien die mit Ihrem Projekt gebündelten .mo-Dateien überschreiben. Um dies zu verhindern, verwenden Sie den load_textdomain_mofile-Filter, um das Laden Ihres gebündelten Dateipfads zu erzwingen, bevor WordPress das globale Verzeichnis überprüft. Projekte mit mehreren Text Domains (ein Plugin, das ein anderes Plugin einbettet) erfordern, dass jede Domain separat geladen wird. Jede Domain benötigt ihren eigenen load_plugin_textdomain()- oder load_theme_textdomain()-Aufruf.

Stellen Sie sicher, dass der MO-Dateiname mit dem WordPress-Suchmuster übereinstimmt

Die Dateisuche nach .mo in WordPress folgt einer strengen Namenskonvention. Schon bei einer Abweichung von einem Zeichen führt WordPress stillschweigend einen Fallback auf Englisch durch.

Die Konvention hängt davon ab, wo Sie die Datei ablegen:

Speicherort Muster Beispiel
/languages/ des Plugins {text-domain}-{locale}.mo my-plugin-de_DE.mo
/languages/ des Themes {locale}.mo de_DE.mo
Globales Verzeichnis (/wp-content/languages/...) {text-domain}-{locale}.mo my-theme-de_DE.mo

Einige praktische Beispiele:

  • my-plugin-es_ES.mo für Spanisch (Spanien)
  • my-plugin-fr_FR.mo für Französisch (Frankreich)
  • my-plugin-pt_BR.mo für Portugiesisch (Brasilien)
  • my-plugin-zh_CN.mo für Chinesisch (vereinfacht)
  • my-plugin-ja.mo für Japanisch (einige Locales haben kein Regionssuffix)

Häufige Fehler:

  • Falsches Text-Domain-Präfix. Wenn der Text Domain-Header Ihres Plugins my-plugin lautet, die .mo aber den Namen myplugin-es_ES.mo (ohne Bindestrich) hat, wird WordPress sie nicht finden. Das Präfix muss exakt mit dem Wert von Text Domain übereinstimmen.
  • Falscher Locale-Code. es.mo anstelle von es_ES.mo. WordPress verwendet regionale Locale-Codes. es_ES, es_MX und es_AR sind unterschiedliche Dateien. Ein bloßer Sprachcode funktioniert nur, wenn keine regionale Datei existiert.
  • Bindestrich vs. Unterstrich. Locale-Codes verwenden Unterstriche (es_ES), niemals Bindestriche (es-ES). Dies ist eine Stolperfalle für Entwickler, die Locale-Codes aus Browser-Accept-Language-Headern oder BCP-47-Quellen kopieren, wo der Bindestrich Standard ist.
  • Falsches Verzeichnis. Der Domain Path-Header muss auf das Verzeichnis verweisen, das Ihre .mo-Dateien enthält. Wenn Domain Path auf /languages lautet und sich Ihre .mo-Dateien in /lang/ befinden, wird WordPress sie nicht finden.

Überprüfen Sie dies, indem Sie die von der PTC generierten Dateien mit der Locale abgleichen, die Ihre Website verwendet:

ls plugins/my-plugin/languages/
# my-plugin-es_ES.mo
# my-plugin-es_ES.po
# my-plugin-fr_FR.mo
# my-plugin-fr_FR.po

Wenn die Namen richtig aussehen, die Übersetzungen aber immer noch nicht geladen werden, führen Sie die obige load_plugin_textdomain()-Diagnose aus, um zu bestätigen, dass WordPress das Verzeichnis findet.

Prüfen Sie, ob Ihre Text Domain in Ihrem Code konsistent ist

Dies ist der lautlose Killer. Jeder __()-, _e()-, _n()- und _x()-Aufruf in Ihrem Code übergibt eine Text Domain als letztes Argument. Wenn auch nur ein Aufruf die falsche Domain übergibt, wird dieser eine String nicht übersetzt. Jeder andere String im Plugin wird einwandfrei funktionieren.

// Correct - matches the plugin's Text Domain
$correct = __( 'Save Changes', 'my-plugin' );

// Wrong - text domain typo; this string is never translated
$wrong = __( 'Save Changes', 'myplugin' );  // missing hyphen

// Wrong - copy-pasted from another plugin
$wrong = __( 'Save Changes', 'other-plugin' );

// Wrong - WordPress core domain; works for core strings but not yours
$wrong = __( 'Save Changes', 'default' );

Finden Sie Inkonsistenzen, indem Sie Ihre Codebasis mit grep durchsuchen:

grep -rE "__\(|_e\(|_n\(|_x\(" --include="*.php" .

Sehen Sie sich das letzte Argument jedes Treffers an. Sie sollten alle die Text Domain Ihres Plugins sein. Wenn Sie Tippfehler oder Copy-Paste-Fehler finden, beheben Sie diese und führen Sie wp i18n make-pot erneut aus, um die .pot-Datei zu aktualisieren.

Für JavaScript-Code, der @wordpress/i18n verwendet, gilt dieselbe Regel. wp_set_script_translations() in PHP muss ebenfalls die übereinstimmende Domain übergeben:

wp_set_script_translations( 'my-plugin-editor', 'my-plugin', '...' );
//                                                ^^^^^^^^^^^
//                                                Must match the JS calls

Erkennen Sie dieselben Fehler vor der Veröffentlichung mit AI Visual QA

Die obige Diagnoseschleife ist reaktiv. Eine Übersetzung fehlt, Sie begeben sich auf die Suche nach der Ursache. Die AI Visual QA der PTC erkennt dieselben Fehler, bevor sie veröffentlicht werden. Sie inspiziert das gerenderte Plugin in jeder Zielsprache nach jedem Übersetzungsupdate und meldet zurück, was fehlt oder falsch ist.

Bei einem hartcodierten englischen String außerhalb von __() (Ursache 1 oben) sieht die AI Visual QA den unübersetzten String im gerenderten Plugin. Die PTC generiert einen einsatzbereiten Prompt für Cursor oder Claude Code, um den String in __() einzuschließen. Bei einer nicht übereinstimmenden Text Domain (die Prüfung im vorherigen Abschnitt) sieht sie den String unübersetzt, während andere Strings auf demselben Bildschirm übersetzt sind, und meldet die Inkonsistenz.

Wenn Sie die AI Visual QA noch nicht aktiviert haben, lesen Sie das Tutorial für WordPress-Themes und -Plugins zur Einrichtung.

Wenn alle vier Prüfungen bestanden sind und Übersetzungen immer noch fehlen

Wenn Sie alle vier Prüfungen durchgeführt haben und die Übersetzungen immer noch nicht angezeigt werden, senden Sie eine E-Mail an den PTC-Support mit:

  • Der Text Domain Ihres Plugins.
  • Einem der .mo-Dateinamen (z. B. my-plugin-es_ES.mo).
  • Einem Screenshot des PTC-Dashboards, der den betroffenen String mit seiner Übersetzung zeigt.
  • Der Spracheinstellung der Website unter Einstellungen > Allgemein.

Die meisten Fälle von „fehlenden Übersetzungen“ lassen sich auf eine der oben genannten Ursachen zurückführen. Randfälle (spezifische WordPress-Versionen, MultiSite-Locale-Auflösung, Konflikt mit einem anderen i18n-Plugin) erfordern manchmal einen zweiten Blick.

Halten Sie zukünftige Releases mit kontinuierlicher Lokalisierung synchron

Sobald Ihre Übersetzungen korrekt geladen werden, richten Sie den Workflow der kontinuierlichen Lokalisierung ein, damit zukünftige Releases mit Ihren Übersetzungen synchron bleiben – automatisch bei jedem Push zu main.