Il est important d’envoyer des e-mails aux utilisateurs de votre site dans la langue de leur choix. À cet effet, WPML propose une API permettant d’enregistrer la langue préférée de l’utilisateur pendant qu’il utilise le site, puis d’appliquer cette préférence lors de l’envoi d’e-mails à ce dernier.
Ce document explique aux auteurs d’extensions et de thèmes comment intégrer leurs produits à la fonction standard wp_mail() de WordPress dans le contexte de la langue préférée.
Quand devez-vous envoyer des e-mails localisés par utilisateur ?
Voici des exemples illustrant quelques cas typiques où vous devez envoyer des e-mails dans la langue préférée de l’utilisateur :
- Vous êtes un administrateur de site qui envoie une newsletter aux abonnés : l’administrateur du site est français et affiche une interface de newsletter en français. Résultat : tous les e-mails seront envoyés en français. Comme vos abonnés viennent du monde entier, beaucoup ne comprendront pas cet e-mail.
- Vous gérez un site de réseau social : les membres de ce site peuvent publier leurs photos. D’autres membres peuvent aimer et mettre en favoris ces photos. Lorsqu’ils les aiment, l’auteur de l’image en est informé par e-mail. Imaginez maintenant ce scénario :
- Mathias, qui est allemand, a publié sa photo.
- Son ami Pierre, qui est français, tombe sur la photo de Mathias et clique sur le bouton J’aime.
- Étant donné que lors de cette action, Pierre affichait la page en français, Mathias recevra une notification par e-mail en français.
- Vous gérez un site e-commerce : si un produit est temporairement indisponible, les utilisateurs peuvent laisser leur e-mail pour être informés de son retour en stock. Un visiteur japonais laisse son e-mail sous certains produits. Ensuite, l’administrateur du site, qui est espagnol, met à jour la disponibilité. Résultat : le client japonais reçoit un e-mail automatique « Le produit x est de nouveau disponible » en espagnol, et non en japonais.
Il existe de nombreux autres exemples similaires, et vous êtes la personne la mieux placée pour savoir si cela posera un problème pour votre extension ou votre thème.
Dans tous ces cas, nous devons trouver un moyen d’enregistrer la langue préférée du destinataire, puis de passer temporairement à cette langue lors de l’envoi des e-mails.
Encapsuler la fonction wp_mail() avec du code spécifique à WPML
Lors de l’envoi d’e-mails, vous devez ajouter trois étapes supplémentaires au code de votre extension ou de votre thème :
- Passez au contexte de langue préféré par le destinataire de l’e-mail.
- Exécutez ensuite tout votre code pour envoyer réellement l’e-mail.
- Rétablissez la langue du site.
La deuxième étape est probablement prête à ce stade. La seule chose à faire est d’ajouter deux lignes supplémentaires, spécifiques à WPML : il vous suffit d’ajouter les lignes en gras.
$email = get_option('receiver-email');
// Switch language context…
do_action('wpml_switch_language_for_email', $email);
// your code for sending email:
$subject = __('Hello, World!', 'text-domain');
$message = __('This is our newsletter', 'text-domain');
wp_mail($email, $subject, $message);
// switch language back
do_action('wpml_restore_language_from_email');
Comme vous pouvez le constater, les modifications sont mineures, mais vous devez garder à l’esprit les deux points importants suivants.
1. Changez la langue avant de récupérer le tout premier contenu de l’e-mail
N’oubliez pas que vous changez de langue pour traduire le contenu de l’e-mail. C’est pourquoi vous devez veiller à définir la bonne langue avant de récupérer tout contenu d’e-mail (le sujet ou le contenu du message).
Le code suivant ne fonctionnera pas :
$email = my_func_to_get_receiver_email();
$subject = my_func_to_get_title(); // will come in site’s lang
$message = my_func_to_get_msg_body(); // will come in site’s lang
do_action('wpml_switch_language_for_email', $email);
wp_mail($email, $subject, $message);
do_action('wpml_restore_language_from_email');
À la place, vous devez utiliser :
$email = my_func_to_get_receiver_email();
do_action('wpml_switch_language_for_email', $email);
$subject = my_func_to_get_title(); // will come in receiver’s lang
$message = my_func_to_get_msg_body(); // will come in receiver’s lang
wp_mail($email, $subject, $message);
do_action('wpml_reset_language_after_mailing');
2. N’envoyez pas d’e-mails à un tableau de destinataires
La fonction wp_mail() permet de transmettre $email sous forme de tableau de paramètres d’e-mails. Malheureusement, cela est interdit si vous souhaitez rendre le contenu des e-mails traduisible.
Donc, si vous avez un code qui ne fonctionne pas, comme celui-ci :
$emails = my_func_get_emails_array(); // array(email1, email2...)
do_action('wpml_switch_language_for_email', $emails); // will not work
$subject = my_func_to_get_title();
$message = my_func_to_get_msg_body();
do_action('wpml_restore_language_from_email');
Vous devez le réécrire de cette façon :
$emails = my_func_get_emails_array(); // array(email1, email2...)
foreach($emails as $email) :
do_action('wpml_switch_language_for_email', $email); // now is ok
$subject = my_func_to_get_title();
$message = my_func_to_get_msg_body();
do_action('wpml_restore_language_from_email');
endforeach;
Enregistrer la langue du destinataire
Informations de langue pour les utilisateurs de WP
Si vos destinataires sont enregistrés en tant qu’utilisateurs WordPress standards, vous n’avez pas besoin d’enregistrer les informations de langue ni de créer un hook. Vous pouvez simplement informer vos utilisateurs qu’ils peuvent définir leur langue préférée dans l’interface d’administration de WordPress, sous Profils->Votre profil.
Ces informations sont stockées dans un champ méta d’utilisateur classique. Si, pour une raison quelconque, vous souhaitez les récupérer, vous pouvez utiliser cet extrait de code pratique :
$user = get_user_by( 'email', $email );
if ( $user && isset( $user->ID ) ) {
$lang = get_user_meta( $user->ID, 'icl_admin_language', true );
}
Lorsque les destinataires ne sont pas des utilisateurs réguliers de WP
Chaque fois que votre extension ou votre thème enregistre une adresse e-mail, vous devez également enregistrer la langue préférée du destinataire. Vous n’avez besoin d’aucun emplacement ou type de données spécifique pour cela. La seule chose que vous ayez à faire est d’ajouter un filtre qui renverra les informations de langue. Le nom du filtre est wpml_user_language.
L’exemple de code que vous devez implémenter pourrait ressembler à ceci :
add_filter(‘wpml_user_language’, ‘my_recipients_language’, 10, 2);
function my_recipient_language($lang, $email) {
return get_language_from_my_database($email); // implement it in your plugin/theme
}
Widget de langue
Si vous fournissez une interface publique avec un panneau de configuration pour vos abonnés, vous pouvez leur demander leur langue à l’aide du hook d’action suivant :
do_action('wpml_user_language_switcher', array('mail'=>'mail@example.com') );
Veuillez noter que vous devez remplacer mail@example.com par l’adresse e-mail réelle d’un abonné actuel.
Ce code affichera une liste déroulante contenant les langues disponibles. Lorsqu’un abonné en sélectionne une, cette valeur sera envoyée au serveur via un appel AJAX.
Ensuite, vous devez enregistrer ces données dans les tables de votre base de données. Pour ce faire, ajoutez un hook pour le filtre wpml_user_language_switcher_save, comme ceci :
add_filter('wpml_user_language_switcher_save', 'my_func', 10, 3);
function my_func($saved, $email, $language) { // your code to save email - language pair, i.e.:
save_language_in_my_database($email, $language);
// if you saved data correctly, return true
return true;
}
Si votre filtre ne renvoie pas la valeur true, ou si vous n’avez aucun filtre pour cela, WPML essaiera d’enregistrer les informations de langue dans la table des métadonnées de l’utilisateur (voir le chapitre suivant).
Envoi d’e-mails à des adresses non enregistrées
Parfois, vous devez envoyer des e-mails à des adresses qui ne figurent dans aucune table de base de données. Étant donné que les destinataires ne sont pas dans votre base de données, vous n’enregistrez pas non plus leurs préférences de langue.
Dans ces cas, WPML s’attend à ce que le code de langue soit disponible dans l’une de ces trois variables globales :
$_POST['wpml_user_email_language']$_GET['wpml_user_email_language']$GLOBALS['wpml_user_email_language']
Comment traduire les e-mails
La traduction du contenu des e-mails s’effectue de la même manière que la traduction de n’importe quelle autre chaîne de votre site. Pour des informations plus détaillées sur ce sujet, veuillez consulter notre page de documentation sur la Traduction de chaînes.
En résumé, assurez-vous que les éléments suivants sont appliqués à toutes les chaînes utilisées comme contenu d’e-mail (sujet ou corps du message) :
- S’il s’agit de chaînes statiques, assurez-vous qu’elles sont localisées avec les fonctions gettext _e() ou __()).
- Si elles sont enregistrées dans la table d’options de WordPress et récupérées à l’aide de la fonction get_option(), vous devez « informer » WPML qu’elles sont également traduisibles. Cela se fait à l’aide du fichier de configuration de la langue.
Si ces conditions sont remplies dans votre extension ou votre thème, les utilisateurs pourront les traduire sur la page WPML->Traduction de chaînes.
Exemple pratique
Pour voir un exemple plus pratique des informations présentées sur cette page, veuillez consulter notre article de blog sur l’utilisation de l’intégration de l’API de messagerie de WPML avec l’extension Sensei.