Wie Sie Ihre Plugins und Themes mit WPML kompatibel machen

Folgen Sie unserer Schritt-für-Schritt-Anleitung, um Ihre Plugins und Themes mit WPML kompatibel zu machen.

Diese Anleitung richtet sich an Theme- und Plugin-Autoren, die bereits an unserem Kompatibilitätsprogramm – Go Global – teilnehmen. Wenn Sie noch nicht teilnehmen, reichen Sie bitte Ihre Bewerbung ein, bevor Sie dieser Anleitung folgen.

So werden Sie WPML-kompatibel

1. Eine Sprachkonfigurationsdatei erstellen

Eine Sprachkonfigurationsdatei teilt WPML mit, welche Texte in Ihrem Plugin oder Theme übersetzt werden sollen (und welche nicht). Dies umfasst Texte in benutzerdefinierten Beitragstypen, Taxonomien, Feldern, Admin-Bildschirmen, Widgets und mehr.

Wenn Sie bereits wissen, wie Sie eine Sprachkonfigurationsdatei erstellen, folgen Sie den unten stehenden Anweisungen, um Ihre Einrichtung zu testen. Andernfalls lesen Sie unsere Anleitung zur Sprachkonfiguration, um zu erfahren, wie Sie eine erstellen.

Testeinrichtung
1. Erstellen Sie einige Beiträge und Taxonomien
2. Senden Sie sie zur Übersetzung
3. Überprüfen Sie, ob sie im Frontend übersetzt erscheinen

2. Strings für die Übersetzung vorbereiten

Strings sind alle Texte, die auf der Website erscheinen und nicht Teil von Beiträgen, Seiten oder Taxonomien sind. Damit WPML Strings in Ihrem Plugin oder Theme übersetzen kann, folgen Sie den unten stehenden Anweisungen für jeden Anwendungsfall.

Verwenden Sie beim Konfigurieren Ihrer Strings das Plugin Multilingual Tools, um zu überprüfen, welche Strings übersetzbar sind und welche eine zusätzliche Konfiguration erfordern.

Fest codierte Strings

Fest codierte Strings müssen mit gettext-Funktionen registriert werden. Erfahren Sie mehr über die Verwendung von gettext und die Vorbereitung Ihres Codes.

Strings in wp_options

Wenn Ihr Plugin oder Theme Strings aus der wp_options-Tabelle verwendet, registrieren Sie diese in der Datei wpml-config.xml.

Wenn Ihre Options-Keys nicht festgelegt sind und Ihr Theme ein Array von Einträgen verwendet, das durch Benutzereingaben wachsen kann, registrieren Sie diese Einträge dynamisch. Sie können dazu die API-Funktionen von WPML verwenden.

Dynamische Strings

Wenn keine der vorherigen Methoden auf Ihre Strings zutrifft, folgen Sie diesen Anleitungen, um Strings für die Übersetzung vorzubereiten:

Testeinrichtung
1. Durchsuchen Sie Ihr Plugin / Theme nach Strings unter WPML → Theme- und Plugin-Lokalisierung
2. Erstellen Sie eine Seite mit Strings
3. Überprüfen Sie, ob die Strings in der String-Übersetzung erscheinen
4. Übersetzen Sie einige Strings und überprüfen Sie, ob sie im Frontend übersetzt erscheinen

3. Benutzerdefinierte Widgets und Blöcke für die Übersetzung registrieren

Wenn Ihr Theme oder Plugin benutzerdefinierte Widgets für Page Builder wie Elementor enthält, müssen Sie diese für die Übersetzung registrieren.

Weitere Informationen zum Registrieren von Page-Builder-Inhalten finden Sie in den folgenden Anleitungen:

Testeinrichtung
1. Erstellen Sie eine Seite mit all Ihren benutzerdefinierten Widgets
2. Senden Sie die Seite zur Übersetzung und überprüfen Sie, ob die Widget-Texte im Erweiterten Übersetzungs-Editor erscheinen
3. Überprüfen Sie, ob die Übersetzungen im Frontend angezeigt werden
4. Wiederholen Sie die Schritte, um verschiedene Widget-Einstellungen zu testen

4. IDs aus verschiedenen Sprachen automatisch abrufen

Wenn Ihr Theme oder Plugin über Funktionen oder Optionen verfügt, die in jeder Sprache unterschiedliche Beitrags-IDs laden, verwenden Sie den Filter wpml_object_id, um die übersetzte Beitrags-ID automatisch abzurufen.

Stellen Sie sich zum Beispiel einen Slider mit Slides in verschiedenen Sprachen vor, von denen jedes eine eindeutige ID hat. Um die richtige Slide-ID in jeder Sprache automatisch zu laden, können wir den Filter wpml_object_id verwenden:

// Loop posts
while (have_posts()): the_post();
$post = get_post( apply_filters( 'wpml_object_id', $post->ID, 'slide' ) );

Testeinrichtung
1. Erstellen Sie den entsprechenden Beitrag / das Template usw. und fügen Sie einen Text-String hinzu
2. Stellen Sie Ihre Funktion so ein, dass dieser Beitrag verwendet wird
3. Übersetzen Sie den Beitrag und legen Sie einen anderen Wert im Text-String fest
4. Überprüfen Sie, ob die Funktion die übersetzte ID im Frontend lädt

5. Kompatibel mit WooCommerce werden

WPML kann WooCommerce-Inhalte mit seinem Add-on WPML Multilingual & Multicurrency for WooCommerce übersetzen. Wenn Ihr Theme oder Plugin WooCommerce-Elemente enthält, folgen Sie unserer Kompatibilitätsanleitung für WPML Multilingual & Multicurrency for WooCommerce, um es mit WPML kompatibel zu machen.

6. Den Admin-Sprachumschalter ein- oder ausblenden

Standardmäßig fügt WPML der WordPress-Admin-Leiste einen Sprachumschalter hinzu. Dieser Sprachumschalter ist für angemeldete Benutzer sowohl im Frontend als auch im Backend sichtbar.

Sprachumschalter in der oberen Admin-Leiste

In einigen Fällen möchten Sie den Sprachumschalter möglicherweise auf sensiblen Seiten ausblenden, z. B. in Ihrem Einstellungsbereich. Fügen Sie dazu den folgenden Code in Ihre Datei functions.php ein:

//Make sure to rename the function before adding to your plugin
add_filter( 'wpml_show_admin_language_switcher', 'compsupp_disable_wpml_admin_lang_switcher' );
 
function compsupp_disable_wpml_admin_lang_switcher( $state ) {
    global $pagenow;
 
    // Add the admin pages that we need to hide the language switcher
    $admin_pages_to_hide_ls = array(
        'admin-page-slug', 'another-admin-page-slug', 'one-more-admin-page-slug'
    );
 
    // We can also have a filter here in case we need to add/remove pages later
    $admin_pages_to_hide_ls = apply_filters( 'compsupp_filter_disable_wpml_lang_switcher_in_admin', $admin_pages_to_hide_ls);
     
    if (
        $pagenow == 'admin.php'
        && isset( $_GET['page'] )
        && in_array( $_GET['page'], $admin_pages_to_hide_ls)
    ) {
        $state = false;
    }
    return $state;
}

Spezielle Funktionen kompatibel machen

Wenn Ihr Theme oder Plugin spezielle Funktionen enthält (wie die Verwendung benutzerdefinierter Tabellen), müssen Sie benutzerdefinierten Code verwenden, um sie mit WPML kompatibel zu machen.

Informationen zur benutzerdefinierten Entwicklung finden Sie in unseren Entwicklerressourcen.

Häufige Probleme & Lösungen

Formular-Labels können nicht übersetzt werden, da sie aus der Datenbank stammen +

Lösung:

$label = esc_html( apply_filters('wpml_translate_single_string', $this->checkout_item->name, 'wpsc', '$this->checkout_item->name .'_checkout_form_label'' ) );

wp_query($args) oder get_posts($args) filtert nicht die korrekten Beitrags-IDs für die aktuelle Sprache +

Lösung:

Wenn Sie wp_query($args) oder get_posts($args) verwenden, müssen Sie den Argumenten „suppress_filters=0“ hinzufügen.

Alle Slides werden in einer Sprache angezeigt +

Lösung:

// Unset not translated slides
foreach( $slides as $k => $slide ) {
	$check = apply_filters( 'wpml_post_language_details', NULL, $slide->ID )
	$slide_language_code = substr( $check['locale'], 0, 2 );

	if( $check['different_language'] ) {
		unset( $slides[$k] );
	}
}

Slide-ID ist in einer Zweitsprache unterschiedlich +

Lösung:

// Loop posts
while (have_posts()): the_post();
$post = get_post( apply_filters( 'wpml_object_id', $post->ID, 'slide' ) );

Slider verwendet eine benutzerdefinierte Admin-Seite und ich muss benutzerdefinierte Feldwerte für Übersetzungen registrieren +

Lösung:

// Adding a new slide code
$slide_id = $this->slide->ID;
$url = $fields['url'];

// Register slide URL to translations
do_action( 'wpml_register_single_string', 'Slider', 'Slide_ID_' . $this->slide->ID, $url);

$this->add_or_update_or_delete_meta($this->slide->ID, 'url', $url);

Eine benutzerdefinierte Taxonomie-ID ist in einer Zweitsprache unterschiedlich +

Lösung:

$taxonomy_id = apply_filters( 'wpml_object_id', $taxonomy_id, 'my_custom_taxonomy' );

Benutzerdefinierte (nicht standardmäßige WordPress-) AJAX-Anfragen geben immer den Inhalt in der Standardsprache zurück +

Lösung:

Wenn Sie benutzerdefinierte AJAX-URLs erstellen, verwenden Sie den Hook wpml_current_language und fügen Sie die aktuelle Sprache als Parameter für die AJAX-URLs hinzu.

$ajax_url = 'http://my-site.com/wp-content/plugins/my-plugin/handle-ajax.php';
$my_current_lang = apply_filters( 'wpml_current_language', NULL ); 
if ( $my_current_lang ) {
	$ajax_url = add_query_arg( 'wpml_lang', $my_current_lang, $ajax_url );
	// $ajax_url will be something like 'http://my-site.com/wp-content/plugins/my-plugin/handle-ajax.php?wpml_lang=es'
}

Wenn Sie AJAX-Anfragen in der Datei handle-ajax.php verarbeiten, verwenden Sie den Hook wpml_switch_language, um die Inhaltssprache zu wechseln, bevor Sie die Inhaltsausgabe generieren.

if ( isset( $_GET[ 'wpml_lang' ] ) ) {
    do_action( 'wpml_switch_language',  $_GET[ 'wpml_lang' ] ); // switch the content language
}

// Run other content queries.

Falsche Verwendung des Wertes „id“ in WP_Query $args[ ‘tax_query’ ][ ‘field’ ] Argument(en) +

Lösung:

Die Verwendung des Arguments „id“ für den Parameter „field“ funktioniert für die Standardsprache, aber nicht für die Zweitsprache. Das Folgende ist ein Beispiel für eine falsche Abfrage:

$args = array(
    'post_type' => 'post',
    'tax_query' => array(
        array(
            'taxonomy' => 'people',
            'field'    => 'id',
            'terms'    => 'bob',
        ),
    ),
);
$query = new WP_Query( $args );

Entwickler sollten den Parameter „field“ korrigieren.

'field'    => 'id',

zu:

'field'    => 'term_id',

Referenz: https://codex.wordpress.org/Class_Reference/WP_Query#Taxonomy_Parameters. Es gibt keinen Wert „id“ für den Parameter „field“. Sein Standardwert ist „term_id“.