WordPress Internationalisierung: Wie man WordPress Themes und Plugins übersetzt

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

Bevor Sie etwas übersetzen können, müssen Sie Ihren Code korrekt einrichten. Das bedeutet, eine Textdomain zu definieren, alle benutzerseitigen Zeichenfolgen in gettext-Funktionen einzuschließen und eine POT-Datei zu generieren.

Nichts davon ist kompliziert, aber die Details zählen. Eine nicht übereinstimmende Textdomain oder eine nicht eingeschlossene Zeichenfolge bedeutet, dass dieser Text niemals in Ihrer übersetzten Ausgabe erscheinen wird.

Jedes Theme oder Plugin benötigt eine Textdomain. Es handelt sich um eine eindeutige Kennung, die WordPress mitteilt, welche Übersetzungsdateien zu Ihrem Projekt gehören, und sie sollte exakt mit Ihrem Plugin- oder Theme-Slug übereinstimmen.

Deklarieren Sie diese im Header der Hauptdatei Ihres Plugins:

/**
 * Plugin Name: My Plugin
 * Text Domain: my-plugin
 * Domain Path: /languages
 */

/**
 * Plugin Name: My Plugin
 * 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
*/

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

Der Domain-Pfad teilt WordPress mit, wo sich Ihre Übersetzungs Dateien relativ zum Plugin- oder Theme-Verzeichnis befinden. Das Verzeichnis /languages ist der Standard.

Jede Zeichenfolge, die Sie übersetzbar machen möchten, muss in eine der gettext-Funktionen von WordPress eingeschlossen werden. Zur Laufzeit suchen diese Funktionen nach der korrekten Übersetzung und greifen auf die ursprüngliche Zeichenfolge zurück, falls keine Übersetzung gefunden wird.

Einfache Zeichenfolgen

Verwenden Sie __(), wenn Sie eine Zeichenfolge zurückgeben müssen. Für die HTML-Ausgabe (was fast immer der Fall ist), verwenden Sie die escaped Varianten:

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

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

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

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

Die WordPress-Codierungsstandards empfehlen echo esc_html__() gegenüber _e(), da es das Escaping der Ausgabe explizit macht. Es ist eine gute Angewohnheit, dies konsequent anzuwenden.

Zeichenfolgen mit Variablen

Wenn Sie eine Variable direkt in einen String verketten, sehen Übersetzer nur die Fragmente, nicht den vollständigen Satz. Das macht eine korrekte Übersetzung unmöglich, insbesondere in Sprachen mit abweichender Wortstellung. Verwenden Sie stattdessen printf() oder sprintf() mit einem Placeholder und fügen Sie einen Übersetzerkommentar hinzu, damit diese wissen, was %s darstellt:

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

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

Pluralformen

Im Englischen sind Pluralformen einfach: one comment, two comments. Andere Sprachen sind da nicht so unkompliziert. Einige haben je nach Zahl mehrere Pluralformen. Verwenden Sie _n(), um dies korrekt zu handhaben, egal in welche Sprache Ihr Plugin übersetzt wird:

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

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

Zeichenfolgen, die Kontext benötigen

Manche Wörter haben je nach Einsatzort unterschiedliche Bedeutungen. Verwenden Sie _x(), um Übersetzern den Kontext zu geben, den sie für eine korrekte Übersetzung benötigen:

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

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

WordPress stellt das Paket wp-i18n zur Verfügung, damit Sie in JavaScript dieselben gettext-Funktionen wie in PHP verwenden können. Deklarieren Sie bei der Registrierung Ihres Skripts wp-i18n als Abhängigkeit:

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

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

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

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

Wenn Sie einen Bundler wie Webpack verwenden, nutzen Sie @wordpress/babel-plugin-makepot, um übersetzbare Zeichenfolgen als Teil Ihres Build-Prozesses aus Ihrem Bundle zu extrahieren.

Sobald Sie Ihre Zeichenfolgen eingeschlossen haben, müssen Sie eine POT-Datei (Portable Object Template) generieren. Dies ist die Quelldatei, mit der PTC (oder jeder Übersetzer) arbeitet. Sie enthält alle Ihre übersetzbaren Zeichenfolgen, aber noch keine Übersetzungen.

Führen Sie diesen Befehl im Stammverzeichnis Ihres Plugins oder Themes aus:

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

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

WP-CLI scannt Ihre PHP-, JavaScript- und block.json-Dateien nach gettext-Aufrufen und kompiliert diese in eine einzige POT-Datei. Wenn Sie Composer verwenden, können Sie dies als Composer-Skript hinzufügen, damit der Befehl innerhalb Ihres Teams konsistent bleibt und keine globale WP-CLI-Installation erfordert.

Die vollständige wp i18n-Suite enthält alles Weitere, was Sie später im Workflow benötigen: