Traduire un module PrestaShop attaché à un hook personnalisé

Introduction

Lorsqu'on développe un module PrestaShop greffé sur un hook personnalisé, la gestion des traductions peut rapidement devenir un casse-tête. Entre la syntaxe Smarty spécifique, les fichiers de traduction générés automatiquement et les subtilités du back-office, plusieurs pièges guettent le développeur. Ce guide détaille la méthode complète pour rendre un module multilingue, quelle que soit la version de PrestaShop utilisée.

Syntaxe Smarty pour les chaînes traductibles

La balise `{l}` : règle fondamentale

Dans les fichiers .tpl de votre module, chaque chaîne de texte destinée à être traduite doit utiliser la balise Smarty {l} avec deux paramètres obligatoires :

{l s='Ma chaîne à traduire' mod='nom_du_module'}

• **`s`** : la chaîne source (généralement en français ou en anglais)
• **`mod`** : le nom technique du module, identique au nom du dossier dans `/modules/`

Le paramètre mod est essentiel : il indique à PrestaShop dans quel fichier de traduction chercher la correspondance. Sans lui, la traduction ne sera jamais trouvée.

Exemple concret dans un template

<div class="module-custom-block">
  <h3>{l s='Nos engagements' mod='mymodule'}</h3>
  <p>{l s='Livraison offerte dès 50 euros d achat' mod='mymodule'}</p>
  <a href="{$link->getPageLink('contact')}">
    {l s='Contactez-nous' mod='mymodule'}
  </a>
</div>

Erreur classique : la double accolade

Une erreur fréquente consiste à imbriquer les accolades Smarty de manière incorrecte :

{* ❌ INCORRECT — provoque une erreur de parsing Smarty *}
<p>{{l s='ma_chaine' mod='mymodule'}}</p>

{* ✅ CORRECT — une seule paire d'accolades *}
<p>{l s='ma_chaine' mod='mymodule'}</p>

La double accolade {{ n'est pas une syntaxe Smarty valide et provoquera soit une erreur d'affichage, soit un rendu brut de la balise sans traduction.

Gérer les apostrophes dans les chaînes

Un piège redoutable qui provoque souvent une page blanche (WSOD — White Screen of Death) : l'utilisation d'apostrophes non échappées dans les chaînes de traduction.

Le problème

{* ❌ PROVOQUE UNE PAGE BLANCHE *}
{l s='L'offre du moment' mod='mymodule'}

L'apostrophe dans L'offre ferme prématurément la chaîne Smarty, ce qui génère une erreur fatale PHP.

Les solutions

Solution 1 — Échappement avec antislash :

{l s='L\'offre du moment' mod='mymodule'}

Solution 2 — Reformuler la chaîne (recommandé) :

{l s='Offre du moment' mod='mymodule'}

Cette seconde approche est préférable car elle évite les problèmes d'échappement en cascade, notamment lorsque la chaîne contient plusieurs apostrophes.

Solution 3 — Utiliser les guillemets doubles pour délimiter (PrestaShop 1.7+) :

{l s="L'offre du moment" mod='mymodule'}

Diagnostic d'une page blanche liée aux traductions

Si vous obtenez une page blanche après avoir ajouté des chaînes traductibles :

1. Activez le mode debug dans `/config/defines.inc.php` :

define('_PS_MODE_DEV_', true);

1. Consultez les logs PHP (`/var/log/` ou via le panneau d'hébergement)
2. Recherchez une erreur de type `Smarty Compiler` pointant vers votre fichier `.tpl`
3. Vérifiez chaque apostrophe dans vos chaînes `{l s='...'}`

Traduire depuis le back-office

Méthode PrestaShop 1.6 / 1.7

1. Rendez-vous dans **Localisation → Traductions**
2. Dans la section **Modifier les traductions**, sélectionnez :

- Type : Traductions des modules installés

- Module : votre module

- Langue : la langue cible

1. Cliquez sur **Modifier**
2. PrestaShop affiche toutes les chaînes détectées dans les fichiers `.tpl` du module
3. Saisissez les traductions et enregistrez

Méthode PrestaShop 8.x

Le processus reste identique dans PrestaShop 8, accessible via :

International → Traductions → Modifier les traductions

La différence majeure en version 8.x est le support natif du nouveau système de traduction basé sur le composant Symfony Translation. Pour les modules utilisant Smarty (hooks front-office classiques), la méthode traditionnelle avec {l} reste fonctionnelle.

Pour les modules modernes utilisant Twig (back-office PS 1.7+/8.x), la syntaxe diffère :

{# Syntaxe Twig pour les modules back-office #}
{{ 'Ma chaîne à traduire'|trans({}, 'Modules.Mymodule.Admin') }}

Fichiers de traduction : où sont-ils stockés ?

Structure classique (Smarty)

Les traductions sont stockées dans le dossier du module :

/modules/mymodule/
├── translations/
│   ├── fr.php
│   ├── en.php
│   ├── de.php
│   └── es.php
├── views/
│   └── templates/
│       └── hook/
│           └── perso.tpl
└── mymodule.php

Le fichier fr.php contient des entrées de ce type :

<?php

global $_MODULE;
$_MODULE = array();
$_MODULE['<{mymodule}prestashop>perso_abc123'] = 'Ma chaîne traduite en français';

La clé est générée automatiquement par PrestaShop à partir du nom du module, du fichier template et d'un hash MD5 de la chaîne source.

Structure moderne (Symfony Translation, PS 8.x)

Pour les modules exploitant le nouveau système :

/modules/mymodule/
├── translations/
│   ├── fr-FR/
│   │   └── ModulesMymoduleShop.fr-FR.xlf
│   └── en-GB/
│       └── ModulesMymoduleShop.en-GB.xlf

Hooks personnalisés et traductions

Lorsque votre module est attaché à un hook personnalisé (créé via registerHook avec un nom custom), le mécanisme de traduction reste identique. Le point clé est que PrestaShop scanne les fichiers .tpl du module indépendamment du hook sur lequel il est greffé.

Enregistrer un hook personnalisé

public function install()
{
    return parent::install()
        && $this->registerHook('displayCustomBlock')
        && $this->registerHook('header');
}

public function hookDisplayCustomBlock($params)
{
    return $this->display(__FILE__, 'views/templates/hook/custom_block.tpl');
}

Template avec traductions

{* views/templates/hook/custom_block.tpl *}
<section class="custom-block">
  <h2>{l s='Titre de mon bloc personnalise' mod='mymodule'}</h2>
  <p>{l s='Description du bloc avec du contenu multilingue' mod='mymodule'}</p>
</section>

Les chaînes apparaîtront dans la section de traduction du back-office au même titre que celles des hooks standard.

Bonnes pratiques

1. Nommer les clés de manière descriptive

{* ❌ Peu clair *}
{l s='txt1' mod='mymodule'}

{* ✅ Descriptif *}
{l s='Free shipping on orders over 50 euros' mod='mymodule'}

Utilisez des phrases complètes en anglais ou en français comme clés : elles servent de documentation et de fallback si la traduction est absente.

2. Utiliser les variables Smarty dans les traductions

{l s='Livraison gratuite des %s euros' sprintf=[$threshold] mod='mymodule'}

Évitez la concaténation de chaînes traduites — elle casse l'ordre des mots dans certaines langues.

3. Vider le cache après modification

Après avoir modifié les traductions dans le back-office, videz le cache PrestaShop :

• **Back-office** : Paramètres avancés → Performances → Vider le cache
• **Manuellement** : supprimer le contenu de `/var/cache/prod/` et `/var/cache/dev/`

4. Exporter les traductions

Pensez à exporter vos traductions pour les sauvegarder. En PrestaShop 8.x :

php bin/console translation:export mymodule fr-FR

Résolution des problèmes courants

SymptômeCause probableSolution Page blancheApostrophe non échappée dans `{l s='...'}`Échapper avec `\'` ou reformuler Chaîne non traduiteParamètre `mod` manquant ou incorrectVérifier que `mod='nom_exact_du_module'` Traduction absente du back-officeFichier `.tpl` non scannéVider le cache, sauvegarder le module Double accolades affichéesSyntaxe `{{l ...}}`Utiliser une seule paire `{l ...}` Traduction non prise en compteCache SmartySupprimer `/var/cache/` ou désactiver le cache en dev