Gérer les traductions dans les templates Smarty PrestaShop

Introduction

Lorsqu'on développe un module ou qu'on personnalise un thème PrestaShop, la gestion des traductions dans les fichiers .tpl est un passage obligé. La balise Smarty {l} est l'outil central du système d'internationalisation de PrestaShop, mais son fonctionnement recèle quelques subtilités qui piègent régulièrement les développeurs — notamment l'impossibilité d'y injecter directement des variables Smarty.

Cet article détaille les différentes approches pour rendre vos templates multilingues, du mécanisme natif {l} aux alternatives plus avancées comme sprintf et les paramètres dynamiques.

Comprendre la balise `{l}` de PrestaShop

Fonctionnement de base

La balise {l} est un plugin Smarty enregistré par PrestaShop. Elle sert à marquer une chaîne comme traduisible afin qu'elle soit collectée par le système de traduction du back-office.

{l s='Add to cart'}

Le paramètre s contient la chaîne source (généralement en anglais). PrestaShop recherche ensuite la traduction correspondante dans la langue active de la boutique.

Point crucial : la valeur de s doit être une chaîne littérale, pas une variable Smarty. Le parseur de traduction de PrestaShop scanne les fichiers TPL de manière statique pour extraire les chaînes traduisibles. Une variable comme {l s=$maVariable} ne sera jamais détectée lors de l'extraction.

Traductions dans un module

Pour les templates de modules, le paramètre mod est indispensable. Sans lui, PrestaShop ne saura pas dans quel contexte chercher la traduction :

{l s='My custom text' mod='mon_module'}

La valeur de mod doit correspondre exactement au nom technique du module (le nom du dossier dans /modules/).

Traductions dans un thème (PrestaShop 1.7+)

Depuis PrestaShop 1.7, les templates de thème utilisent le paramètre d (domain) à la place de mod :

{l s='My custom text' d='Shop.Theme.Actions'}

Les domaines de traduction suivent une convention hiérarchique (Shop.Theme.*, Shop.Forms.*, Modules.MonModule.*, etc.).

Méthode recommandée : le workflow de traduction natif

La façon la plus propre de gérer le multilingue dans vos templates est d'exploiter le workflow natif de PrestaShop :

Étape 1 : Déclarer vos chaînes en anglais

Écrivez toutes vos chaînes en anglais dans le fichier TPL :

{* Module *}
{l s='Free shipping on orders over 50€' mod='mon_module'}

{* Thème (PS 1.7+) *}
{l s='Free shipping on orders over 50€' d='Shop.Theme.Checkout'}

Étape 2 : Traduire via le back-office

Rendez-vous dans International > Traductions et sélectionnez :

• **Type de traduction :** « Traductions de modules installés » (pour un module) ou « Traductions du thème » (pour un thème)
• **Module / Thème :** sélectionnez le vôtre
• **Langue :** la langue cible

PrestaShop affiche alors toutes les chaînes détectées avec un champ pour saisir la traduction. Ce mécanisme fonctionne parce que PrestaShop scanne le contenu des paramètres s dans vos fichiers .tpl.

Étape 3 : Vider le cache

Après avoir sauvegardé vos traductions, videz le cache de PrestaShop pour que les modifications prennent effet :

• **Back-office :** Paramètres avancés > Performances > Vider le cache
• **Ligne de commande (PS 8.x) :** `php bin/console cache:clear`

Injecter des valeurs dynamiques dans les traductions

Si vous devez inclure une valeur variable dans une chaîne traduite — par exemple un nom de produit ou un montant — la balise {l} offre un mécanisme de substitution via sprintf.

PrestaShop 1.6

Utilisez le paramètre sprintf :

{l s='Welcome, %s! You have %d items in your cart.' sprintf=[$customer_name, $cart_count] mod='mon_module'}

PrestaShop 1.7 / 8.x

La syntaxe recommandée utilise des placeholders nommés avec le paramètre sprintf sous forme de tableau associatif :

{l
  s='Welcome, [1]%name%[/1]! You have %count% items in your cart.'
  sprintf=['%name%' => $customer_name, '%count%' => $cart_count]
  d='Modules.MonModule.Shop'
}

Cette approche résout élégamment le problème initial : on n'injecte pas de variable dans s, mais on utilise des placeholders que sprintf remplace à l'exécution.

Alternative : les conditions Smarty pour le multilingue

Dans certains cas très spécifiques — par exemple du contenu HTML riche qui ne se prête pas bien au système de traduction — on peut recourir aux conditions Smarty basées sur la langue active :

{if $language.id == 1}
  <p>Bienvenue sur notre boutique !</p>
{elseif $language.id == 2}
  <p>Welcome to our shop!</p>
{else}
  <p>Willkommen in unserem Shop!</p>
{/if}

Attention : cette méthode est un dernier recours. Elle présente plusieurs inconvénients majeurs :

• Les traductions ne sont pas centralisées dans le back-office
• L'ajout d'une nouvelle langue impose de modifier le code
• Les identifiants de langue sont susceptibles de varier d'une installation à l'autre
• Le template devient rapidement illisible avec de nombreuses langues

Pour un code maintenable et professionnel, privilégiez systématiquement la balise {l} avec sprintf.

Bonnes pratiques pour les traductions PrestaShop

1. Toujours écrire les chaînes source en anglais

L'anglais est la langue de référence dans l'écosystème PrestaShop. Écrire vos chaînes en anglais garantit la compatibilité avec les outils de traduction communautaires et facilite la collaboration internationale.

2. Exporter vos traductions

Utilisez le système d'export de PrestaShop pour sauvegarder vos traductions. En PrestaShop 8.x, les traductions sont stockées dans la base de données (table ps_translation) et peuvent être exportées au format XLF.

3. Utiliser les domaines de traduction (PS 1.7+)

Les domaines (d='Shop.Theme.Actions') organisent vos traductions par contexte fonctionnel. Respectez la convention de nommage officielle pour maintenir la cohérence.

4. Ne jamais concaténer des chaînes traduites

Évitez absolument ce pattern :

{* ❌ MAUVAISE PRATIQUE *}
{l s='Bonjour' mod='mon_module'} {$name}

Préférez :

{* ✅ BONNE PRATIQUE *}
{l s='Hello %s' sprintf=[$name] mod='mon_module'}

La concaténation casse la structure grammaticale dans les langues où l'ordre des mots diffère du français ou de l'anglais.

5. Fichiers de traduction dans les modules

Pour distribuer un module avec ses traductions pré-remplies, créez les fichiers dans le dossier translations/ de votre module :

modules/mon_module/
├── translations/
│   ├── fr.php    (PS 1.6)
│   └── fr-FR/    (PS 1.7+, format XLF ou XLIFF)

Migration vers PrestaShop 8.x : ce qui change

PrestaShop 8.x poursuit la transition vers le système de traduction Symfony. Les points d'attention :

• **Nouveaux domaines :** le catalogue de domaines de traduction s'est enrichi. Consultez la documentation officielle pour les correspondances.
• **Format XLIFF :** les fichiers de traduction utilisent désormais le format `.xlf` (standard Symfony).
• **Console Symfony :** la commande `php bin/console translation:extract` permet d'extraire automatiquement les chaînes traduisibles.
• **Rétrocompatibilité :** la balise `{l s='' mod=''}` reste fonctionnelle dans les modules, mais `{l s='' d=''}` est recommandé pour tout nouveau développement.

Résumé des syntaxes par version

VersionModuleThèmeVariables dynamiques PS 1.6`{l s='...' mod='nom'}``{l s='...'}``sprintf=[$var]` PS 1.7`{l s='...' mod='nom'}``{l s='...' d='Shop.Theme.*'}``sprintf=['%key%' => $var]` PS 8.x`{l s='...' d='Modules.Nom.*'}``{l s='...' d='Shop.Theme.*'}``sprintf=['%key%' => $var]`