PTC
Registrieren Auf Pro upgraden Ihr Konto

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

Fehlen Übersetzungen nach einem PTC-Lauf? Drei Prüfungen finden fast jede Ursache. Prüfen Sie, ob die Zeichenkette PTC erreicht hat, ob der .mo-Dateiname dem entspricht, was WordPress erwartet, und ob die Textdomäne in Ihrem gesamten Code konsistent ist. Diese Anleitung führt durch jede Prüfung in der Reihenfolge, in der Sie sie durchführen sollten.

Dieselbe diagnostische Reihenfolge funktioniert, egal ob Sie mit PTC (Private Translation Cloud), GlotPress oder einem anderen gettext-basierten Werkzeug übersetzt haben. Die Fehlerquellen liegen in der WordPress-i18n-Pipeline selbst begründet, nicht in einem bestimmten Übersetzer.

Bestätigen Sie, dass die Zeichenkette PTC erreicht hat

Die erste Frage ist, ob sich die Zeichenkette in Ihrem PTC-Projekt befindet. Wenn eine Zeichenkette nicht in Ihre .pot-Datei extrahiert wurde, hat PTC sie nie gesehen. Die .po-Datei enthält keine Übersetzung dafür. Das laufende Plugin zeigt den Rückfall auf die Ausgangssprache an.

So prüfen Sie das:

  1. Öffnen Sie die betroffene Zeichenkette im laufenden Plugin und kopieren Sie ihren exakten Text.
  2. Gehen Sie zu Ihrem PTC-Dashboard, öffnen Sie den Tab Translations und suchen Sie nach der Zeichenkette.
  3. Wenn sie dort nicht vorhanden ist, hat PTC sie nie empfangen.

Drei häufige Ursachen folgen.

Ursache 1: die Zeichenkette fehlt in Ihrer POT-Datei

wp i18n make-pot extrahiert nur Zeichenketten innerhalb der erkannten i18n-Funktionen. Das bedeutet __(), _e(), _n(), _x() und die maskierten Varianten, mit der richtigen Textdomäne. Zeichenketten in der falschen Domäne werden übersprungen. Fest codierte Zeichenketten außerhalb einer i18n-Funktion werden übersprungen.

Führen Sie die Extraktion erneut aus und prüfen Sie, ob die Zeichenkette nun in der .pot enthalten ist:

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

Wenn grep die Zeichenkette mit einem msgid zurückgibt, funktioniert die Extraktion. Laden Sie die neue .pot erneut zu PTC hoch und übersetzen Sie erneut. Wenn grep nichts zurückgibt, ist die Zeichenkette fest codiert und nicht in __() eingeschlossen. Das ist Ihr Fehler. Schließen Sie die Zeichenkette ein und extrahieren Sie erneut.

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

Jede übersetzbare Zeichenkette in Ihrem Code benötigt einen Wrapper. Verwenden Sie __(), esc_html__(), _e(), _n() oder _x() mit der korrekten Textdomäne:

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

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

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

  1. Gehen Sie im PTC-Dashboard zu Settings > Monitored Files.
  2. Bearbeiten Sie die betreffende Ressourcendatei und aktivieren Sie "Is this a WordPress project with localizable JavaScript?"

Damit weist PTC an, JavaScript-Dateien nach übersetzbaren Zeichenketten zu durchsuchen. PTC generiert die Übersetzungen neu und öffnet einen neuen Merge Request mit den aktualisierten Dateien.

Stellen Sie anschließend sicher, dass WordPress weiß, wo die .json-Übersetzungsdateien zu laden sind, die PTC erzeugt hat. 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'
);

Damit weist WordPress an, .json-Dateien aus Ihrem Plugin- oder Theme-Ordner zu laden.

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

Wenn sich die Zeichenkette in PTC befindet und die .mo-Datei im Verzeichnis languages/ Ihres Plugins vorhanden ist, das gerenderte Plugin aber weiterhin Englisch anzeigt, lädt WordPress die .mo nicht.

Diagnose 1: ist die Locale der Website korrekt gesetzt? Gehen Sie in wp-admin zu Settings > General > Site Language und bestätigen Sie, dass sie mit Ihrer Zielsprache übereinstimmt. Setzen Sie sie beispielsweise auf "Espanol", um Spanisch zu testen. Wenn die Website auf Englisch eingestellt ist, wird Ihre spanische .mo nie 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 prü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 üblicherweise eine Abweichung im Dateinamen (siehe nächster Abschnitt) oder ein falscher Verzeichnispfad.

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

Diagnose 4: überschreiben Community-Übersetzungen Ihre mitgelieferten Dateien? Standardmäßig priorisiert WordPress Übersetzungsdateien, die in /wp-content/languages/ gespeichert sind. Wenn Ihr Plugin oder Theme Community-Übersetzungen auf WordPress.org besitzt, können diese Dateien die mit Ihrem Projekt mitgelieferten .mo-Dateien überschreiben. Um das zu verhindern, verwenden Sie den load_textdomain_mofile-Filter, um Ihren mitgelieferten Dateipfad zwangsweise zu laden, bevor WordPress das globale Verzeichnis prüft. Projekte mit mehreren Textdomänen (ein Plugin, das ein anderes Plugin einbettet) müssen jede Domäne separat laden. Jede Domäne benötigt ihren eigenen load_plugin_textdomain()- oder load_theme_textdomain()-Aufruf.

Stellen Sie sicher, dass der MO-Dateiname dem WordPress-Suchmuster entspricht

Die .mo-Dateisuche von WordPress folgt einer strengen Namenskonvention. Schon ein Zeichen daneben, und WordPress fällt stillschweigend auf Englisch zurück.

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 durchgespielte 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 vereinfachtes Chinesisch
  • my-plugin-ja.mo für Japanisch (einige Locales haben kein Regionssuffix)

Häufige Fehler:

  • Falsches Textdomänen-Präfix. Wenn der Text Domain-Header Ihres Plugins my-plugin lautet, die .mo aber myplugin-es_ES.mo (ohne Bindestrich) heißt, findet WordPress sie nicht. Das Präfix muss exakt mit dem Wert von Text Domain übereinstimmen.
  • Falscher Locale-Code. es.mo statt 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 den Unterstrich (es_ES), niemals den Bindestrich (es-ES). Das bringt Entwickler zu Fall, 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 /languages lautet und sich Ihre .mo-Dateien in /lang/ befinden, findet WordPress sie nicht.

Prüfen Sie das, indem Sie die von PTC erzeugten 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 korrekt aussehen, die Übersetzungen aber weiterhin nicht geladen werden, führen Sie die oben beschriebene load_plugin_textdomain()-Diagnose aus, um zu bestätigen, dass WordPress das Verzeichnis findet.

Prüfen Sie, ob Ihre Textdomäne in Ihrem gesamten Code konsistent ist

Das ist der stille Killer. Jeder __()-, _e()-, _n()-, _x()-Aufruf in Ihrem Code übergibt eine Textdomäne als letztes Argument. Wenn auch nur ein Aufruf die falsche Domäne übergibt, wird genau diese eine Zeichenkette nicht übersetzt. Jede andere Zeichenkette im Plugin funktioniert einwandfrei.

// 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 durchsuchen:

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

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

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

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

Erkennen Sie dieselben Probleme vor der Auslieferung mit der visuellen KI-Prüfung

Die obige Diagnoseschleife ist reaktiv. Eine Übersetzung fehlt, und Sie machen sich auf die Suche nach der Ursache. Die visuelle KI-Prüfung von PTC erkennt dieselben Probleme vor der Auslieferung. Sie inspiziert das gerenderte Plugin in jeder Zielsprache nach jeder Übersetzungsaktualisierung und meldet zurück, was fehlt oder falsch ist.

Bei einer fest codierten englischen Zeichenkette außerhalb von __() (Ursache 1 oben) sieht die visuelle KI-Prüfung die nicht übersetzte Zeichenkette im gerenderten Plugin. PTC generiert einen einfügebereiten Prompt für Cursor oder Claude Code, um die Zeichenkette in __() einzuschließen. Bei einer Textdomänen-Abweichung (die Prüfung des vorherigen Abschnitts) sieht sie die Zeichenkette nicht übersetzt, während andere Zeichenketten auf demselben Bildschirm übersetzt sind, und meldet die Inkonsistenz.

Wenn Sie die visuelle KI-Prüfung noch nicht aktiviert haben, lesen Sie das Tutorial zu WordPress-Themes und -Plugins zur Einrichtung.

Wenn alle drei Prüfungen bestehen und Übersetzungen weiterhin fehlen

Wenn Sie alle drei Ursachen geprüft haben und Übersetzungen weiterhin nicht angezeigt werden, schreiben Sie eine E-Mail an den PTC-Support mit folgenden Angaben:

  • Die Textdomäne Ihres Plugins.
  • Einen der .mo-Dateinamen (z. B. my-plugin-es_ES.mo).
  • Einen Screenshot des PTC-Dashboards, der die betroffene Zeichenkette mit ihrer Übersetzung zeigt.
  • Die Spracheinstellung der Website aus Settings > General.

Die meisten Fälle "fehlender Übersetzungen" lassen sich auf eine der obigen Ursachen zurückführen. Sonderfälle (bestimmte WordPress-Versionen, MultiSite-Locale-Auflösung, Konflikt mit einem anderen i18n-Plugin) erfordern manchmal einen zweiten Blick.

Halten Sie künftige Releases mit kontinuierlicher Lokalisierung im Einklang

Sobald Ihre Übersetzungen korrekt geladen werden, richten Sie den kontinuierlichen Lokalisierungs-Workflow ein, damit künftige Releases mit Ihren Übersetzungen im Einklang bleiben - automatisch, bei jedem Push auf main.