Comment rendre vos extensions et vos thèmes compatibles avec WPML

Suivez notre guide étape par étape pour rendre vos extensions et thèmes compatibles avec WPML.

Ce guide s’adresse aux auteurs de thèmes et d’extensions qui ont déjà rejoint notre programme de compatibilité – Go Global. Si vous ne l’avez pas encore rejoint, veuillez soumettre votre candidature avant de suivre ce guide.

Comment devenir compatible avec WPML

1. Créez un fichier de configuration de langue

Un fichier de configuration de langue indique à WPML quels textes traduire (et lesquels ne pas traduire) dans votre extension ou thème. Cela inclut les textes dans les types de publication personnalisés, les taxonomies, les champs, les écrans de l’interface d’administration, les widgets et plus encore.

Si vous savez déjà comment créer un fichier de configuration de langue, suivez les instructions ci-dessous pour tester votre configuration. Sinon, consultez notre guide de configuration de langue pour apprendre à en créer un.

Configuration de test
1. Créez quelques articles et taxonomies
2. Envoyez-les à la traduction
3. Vérifiez qu’ils apparaissent traduits sur l’interface publique

2. Préparez les chaînes pour la traduction

Les chaînes sont tous les textes qui apparaissent sur le site et qui ne font pas partie des articles, des pages ou des taxonomies. Pour permettre à WPML de traduire les chaînes dans votre extension ou thème, suivez les instructions ci-dessous pour chaque cas d’utilisation.

Pendant que vous configurez vos chaînes, utilisez l’extension Multilingual Tools pour vérifier quelles chaînes sont traduisibles et lesquelles nécessitent une configuration supplémentaire.

Chaînes codées en dur

Les chaînes codées en dur doivent être enregistrées avec les fonctions gettext. Apprenez-en plus sur l’utilisation de gettext et la préparation de votre code.

Chaînes dans wp_options

Si votre extension ou thème utilise des chaînes de la table wp_options, enregistrez-les dans le fichier wpml-config.xml.

Si vos clés d’option ne sont pas fixes et que votre thème utilise un tableau d’entrées qui peut s’agrandir avec les saisies de l’utilisateur, enregistrez ces entrées dynamiquement. Vous pouvez utiliser les fonctions de l’API de WPML pour ce faire.

Chaînes dynamiques

Si aucune des méthodes précédentes ne s’applique à vos chaînes, suivez ces guides pour préparer les chaînes pour la traduction :

Configuration de test
1. Analysez votre extension / thème pour trouver des chaînes dans WPML → Localisation des thèmes et des extensions
2. Créez une page avec des chaînes
3. Vérifiez si les chaînes apparaissent dans Traduction de chaînes
4. Traduisez quelques chaînes et vérifiez qu’elles apparaissent traduites sur l’interface publique

3. Enregistrez les widgets et blocs personnalisés pour la traduction

Si votre thème ou extension inclut des widgets personnalisés pour les constructeurs de pages, comme Elementor, vous devez les enregistrer pour la traduction.

Consultez les guides suivants pour en savoir plus sur l’enregistrement du contenu des constructeurs de pages :

Configuration de test
1. Créez une page avec tous vos widgets personnalisés
2. Envoyez la page à la traduction et vérifiez que les textes des widgets apparaissent dans l’Éditeur de traduction avancé
3. Vérifiez que les traductions s’affichent sur l’interface publique
4. Répétez les étapes pour tester différents paramètres de widgets

4. Récupérez automatiquement les ID dans différentes langues

Si votre thème ou extension possède des fonctionnalités ou des options qui chargent différents ID d’articles dans chaque langue, utilisez le filtre wpml_object_id pour récupérer automatiquement l’ID de l’article traduit.

Par exemple, considérez un slider avec des diapositives dans différentes langues, chacune ayant un ID unique. Pour charger automatiquement l’ID de diapositive correct dans chaque langue, nous pouvons utiliser le filtre wpml_object_id :

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

Configuration de test
1. Créez l’article / le modèle pertinent, etc., et ajoutez une chaîne de texte
2. Configurez votre fonctionnalité pour utiliser cet article
3. Traduisez l’article et définissez une valeur différente dans la chaîne de texte
4. Vérifiez que la fonctionnalité charge l’ID traduit sur l’interface publique

5. Devenez compatible avec WooCommerce

WPML peut traduire le contenu de WooCommerce avec son module complémentaire WPML Multilingual & Multicurrency for WooCommerce. Si votre thème ou extension contient des éléments WooCommerce, suivez notre guide de compatibilité de WPML Multilingual & Multicurrency for WooCommerce pour le rendre compatible avec WPML.

6. Affichez ou masquez le sélecteur de langue de l’interface d’administration

Par défaut, WPML ajoute un sélecteur de langue à la barre d’administration de WordPress. Ce sélecteur est visible pour les utilisateurs connectés, à la fois sur l’interface publique et sur l’interface d’administration.

Sélecteur de langue dans la barre d’administration supérieure

Dans certains cas, vous souhaiterez peut-être masquer le sélecteur de langue sur des pages sensibles, comme votre zone de paramètres. Pour ce faire, ajoutez le code suivant à votre fichier functions.php :

//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;
}

Rendre les fonctionnalités spéciales compatibles

Si votre thème ou extension inclut des fonctionnalités spéciales (comme l’utilisation de tables personnalisées), vous devrez utiliser du code personnalisé pour les rendre compatibles avec WPML.

Consultez nos ressources pour les développeurs pour plus d’informations sur le développement personnalisé.

Problèmes courants et solutions

Les étiquettes de formulaire ne peuvent pas être traduites car elles proviennent de la base de données +

Solution :

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

wp_query($args) ou get_posts($args) ne filtre pas les ID d’articles corrects pour la langue actuelle +

Solution :

Si vous utilisez wp_query($args) ou get_posts($args), vous devez ajouter « suppress_filters=0 » aux arguments.

Toutes les diapositives sont affichées dans une seule langue +

Solution :

// 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] );
	}
}

L’ID de la diapositive est différent dans une deuxième langue +

Solution :

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

Le slider utilise une page d’administration personnalisée et je dois enregistrer des valeurs de champs personnalisés pour les traductions +

Solution :

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

L’ID d’une taxonomie personnalisée est différent dans une deuxième langue +

Solution :

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

Les requêtes AJAX personnalisées (non standard de WordPress) renvoient toujours le contenu de la langue par défaut +

Solution :

Lors de la création d’URL AJAX personnalisées, utilisez le hook wpml_current_language et ajoutez la langue actuelle comme paramètre pour les URL AJAX.

$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'
}

Lors du traitement des requêtes AJAX dans le fichier handle-ajax.php, avant de générer la sortie du contenu, utilisez le hook wpml_switch_language pour changer la langue du contenu. Fermez la portée de la langue lorsque vous avez terminé. Depuis WPML 5.0, les changements de langue s’imbriquent, chaque changement nécessite donc sa propre restauration.

if ( ! empty( $_GET[ 'wpml_lang' ] ) ) {
    // Opens a language scope. Only a non-empty language code switches the language.
    do_action( 'wpml_switch_language', sanitize_text_field( $_GET[ 'wpml_lang' ] ) );

    try {
        // Run other content queries.
    } finally {
        // Closes the scope that the call above opened.
        do_action( 'wpml_switch_language', null );
    }
}

Mauvaise utilisation de la valeur « id » dans le ou les arguments WP_Query $args[ ‘tax_query’ ][ ‘field’ ] +

Solution :

L’utilisation de l’argument « id » pour le paramètre « field » fonctionne pour la langue par défaut, mais cela ne fonctionne pas pour la deuxième langue. Voici un exemple de requête incorrecte :

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

Les développeurs doivent corriger le paramètre « field ».

'field'    => 'id',

par :

'field'    => 'term_id',

Référence : https://codex.wordpress.org/Class_Reference/WP_Query#Taxonomy_Parameters. Il n’y a pas de valeur « id » pour le paramètre « field ». Sa valeur par défaut est « term_id ».