# Traduire les emails WooCommerce sans casser les variables dynamiques

> Un email de confirmation de commande traduit affichait des variables non remplacées. Voici la bonne méthode de traduction des templates d'emails WooCommerce.

- Auteur : Clément Hadrot
- Publié le : 2021-12-13
- Mis à jour le : 2021-12-13
- Catégorie : Multilingue
- URL : https://wpmoderne.dev.wordpress-developpement.fr/multilingue/woocommerce-emails-traduction-variables/

## L’essentiel

- Les templates d'emails WooCommerce mélangent texte fixe et variables dynamiques dans le même fichier
- La fonction switch_to_locale détermine la langue réellement utilisée à l'envoi
- Une surcharge de template mal faite casse silencieusement les variables de commande

Un client vendant des accessoires de sport en ligne en français et en néerlandais a reçu une capture d'écran d'un client néerlandophone mécontent : son email de confirmation de commande, correctement traduit dans son texte général, affichait littéralement `{order_number}` à la place du numéro de commande réel, en plein milieu du message. Le développeur précédent avait tenté de traduire le template d'email en dupliquant le fichier PHP et en réécrivant le texte à la main, mais avait cassé au passage la syntaxe de la variable dynamique attendue par WooCommerce.

Ce cas illustre un piège spécifique aux emails WooCommerce : contrairement à un article classique où le texte et les données sont clairement séparés, les templates d'emails mélangent dans un même fichier PHP du texte fixe à traduire et des appels de fonctions PHP qui injectent les données réelles de la commande. Une traduction mal exécutée peut casser ces appels sans provoquer d'erreur PHP visible, simplement un texte de variable resté littéral à l'écran.

## Comprendre la structure d'un template d'email WooCommerce

Les templates d'emails de WooCommerce, situés dans le dossier `woocommerce/templates/emails/` du plugin ou surchargés dans le thème enfant, ne contiennent pas de variables au sens littéral comme `{order_number}`. Il s'agit en réalité d'appels de fonctions PHP, par exemple `echo esc_html( $order->get_order_number() );`, entourés de texte HTML classique traduit avec les fonctions d'internationalisation standards de WordPress comme `esc_html_e()`.

```
<p>
<?php
printf(
    /* translators: %s: numéro de commande */
    esc_html__( 'Merci pour votre commande n° %s.', 'woocommerce' ),
    esc_html( $order->get_order_number() )
);
?>
</p>
```

La confusion du développeur précédent venait probablement d'un template rédigé par un tiers utilisant une syntaxe de type gabarit avec des accolades, mal comprise comme du texte à traduire littéralement plutôt que comme un appel de fonction à préserver intact.

## La bonne méthode : traduire la chaîne, pas le code

Avec WPML, la bonne approche consiste à ne jamais toucher au fichier PHP du template lui-même, mais à laisser le module String Translation détecter la chaîne `'Merci pour votre commande n° %s.'` comme chaîne traduisible, puisqu'elle est correctement entourée de `esc_html__()` avec le domaine de texte `woocommerce`. La traduction se fait alors depuis l'écran de traduction des chaînes, en conservant impérativement le symbole `%s` au bon endroit de la phrase traduite, à l'emplacement grammaticalement correct pour la langue cible.

> L'essentiel à retenir : Les templates d'emails WooCommerce mélangent texte fixe et variables dynamiques dans le même fichier ; La fonction switch_to_locale détermine la langue réellement utilisée à l'envoi ; Une surcharge de template mal faite casse silencieusement les variables de commande

### Vérifier la langue effective au moment de l'envoi

Un autre point technique mérite attention : WooCommerce détermine la langue de l'email envoyé au client au moment précis de l'envoi, généralement en appelant `switch_to_locale()` avec la langue associée à la commande. Il est donc essentiel que la commande elle-même soit correctement associée à la bonne langue, une information généralement enregistrée par le plugin multilingue au moment où le client passe commande depuis la version linguistique correspondante du site.

## Tester avec une vraie commande, pas un aperçu

L'aperçu d'email disponible dans certains outils d'administration ne reflète pas toujours fidèlement la langue réellement utilisée à l'envoi, notamment parce que cet aperçu s'exécute souvent dans le contexte de langue de l'administrateur connecté plutôt que dans celui du client réel. Je recommande systématiquement de passer une commande de test complète depuis chaque version linguistique du site, avec un compte email surveillé, pour vérifier l'email réellement reçu plutôt que de se fier à un aperçu potentiellement trompeur.

- Testez au minimum l'email de confirmation de commande et l'email de changement de statut vers « Terminée ».
- Vérifiez également l'email de réinitialisation de mot de passe du compte client, souvent oublié dans ce type de recette.
- Un email transactionnel envoyé via un service tiers (SMTP externe) doit être testé après configuration de ce service, pas seulement avant.

## Le cas des surcharges de template dans le thème

Quand un thème enfant surcharge un template d'email WooCommerce pour en modifier la mise en page, chaque modification doit impérativement conserver la structure des appels de fonctions dynamiques d'origine. Une comparaison ligne par ligne entre le template d'origine du plugin WooCommerce et la version surchargée du thème enfant, après chaque mise à jour majeure de WooCommerce, évite qu'une nouvelle variable ajoutée par une mise à jour ne soit absente du template surchargé resté figé sur une ancienne version de la structure.

> Je ne considère jamais un email WooCommerce multilingue validé tant qu'il n'a pas été reçu réellement dans une boîte de messagerie de test, avec une vraie commande passée de bout en bout : un aperçu dans l'administration ne suffit pas à garantir le résultat final.

## En résumé

La traduction d'un email WooCommerce ne doit jamais passer par une réécriture manuelle du template PHP, mais par la traduction des chaînes détectées via le module dédié du plugin multilingue, en préservant scrupuleusement la syntaxe des variables dynamiques comme `%s`. Un test avec une commande réelle, reçue dans une boîte de messagerie surveillée pour chaque langue du site, reste la seule vérification qui garantit un résultat fidèle au client final.