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 est destiné 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 des types de publication personnalisés, des taxonomies, des champs, des écrans d’administration, des 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 s’affichent traduits sur l’interface publique

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

Les chaînes de texte 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 de texte de votre extension ou thème, suivez les instructions ci-dessous pour chaque cas d’utilisation.

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

Chaînes de texte codées en dur

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

Chaînes de texte dans wp_options

Si votre extension ou thème utilise des chaînes de texte 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 la saisie de l’utilisateur, enregistrez ces entrées dynamiquement. Vous pouvez utiliser les fonctions de l’API de WPML pour le faire.

Chaînes de texte dynamiques

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

Configuration de test
1. Analysez votre extension / thème pour trouver des chaînes de texte dans WPML → Localisation des thèmes et des extensions
2. Créez une page avec des chaînes de texte
3. Vérifiez si les chaînes de texte apparaissent dans Traduction de chaînes
4. Traduisez quelques chaînes de texte et vérifiez qu’elles s’affichent 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 des 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 widget

4. Récupérez automatiquement les ID de 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, prenons l’exemple d’un slider avec des diapositives dans différentes langues, chacune avec 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é 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 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 obtenir des 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 diapositive est différent dans une langue secondaire +

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 les 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 langue secondaire +

Solution :

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

Les requêtes AJAX personnalisées (non standard à 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.

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

// Run other content queries.

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 elle ne fonctionne pas pour la langue secondaire. 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',

en :

'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 ».