Compatibilité Joomla!

Si vous cherchez à développer des extensions Joomla pour un site multilingue vous aurez besoin de la fonction JText issue de l'API Joomla!.  Grâce à cette fonction on peut ajouter des termes traduisibles dans plusieurs langues que l'on inclut directement dans le code PHP mais aussi Javascript.

Définition de la chaine de texte

On commence par traduire le terme dans le fichier INI de l'extension. Côté visiteur on trouvera les fichiers de langue dans le dossier

[SITE]/language/[TAG]/TAG.EXTENSION.ini

Exemple avec le module login en anglais :

[SITE]/language/en-GB/en-GB.mod_login.ini

On ajoute le terme à traduire dans le fichier ini :

KEY = "Ma clé"

Côté administrator on trouvera les fichiers de langue dans

[SITE]/administrator/language/[TAG]/TAG.EXTENSION.ini

Ajout du terme avec JText en PHP

En PHP c'est très simple, on ajoute la fonction JText :

<?php echo JText::_('KEY'); ?>

Le terme qui s'affichera à l'écran sera 'Ma clé' si la traduction est trouvée dans le fichier de langue.

Ajout du terme avec JText en Javascript

Pou insérer un texte traduit dans une chaine javascript on peut procéder de deux manières :

• Ajouter une déclaration <script> en php en utilisant la fonction JText précédente. A utiliser si on ne veut qu'ajouter quelques lignes de javascript dans la page
• Utiliser une fonction PHP pour stocker la variable en Javascript pour pouvoir ensuite l'utiliser dans des fichiers externes

Ajout d'une déclaration javascript

Dans la feuille PHP on peut ajouter des lignes de code Javascript grâce à la fonction addScriptDeclaration issue de l'API Joomla.

$doc = JFactory::getDocument();         
$doc ->addScriptDeclaration('var MonTexte=\''.JText::_('KEY',true).'\';');

On injecte donc une ligne de code Javascript dans l'entête de la page de Joomla où on retrouvera le résultat du JText :

var MonTexte=Ma clé

On peut renseigner l'attribut TRUE qui permet d'échaper les apostrophes. Admettons que vous avez une traduction qui comporte des ' , vous aurez une erreur javascript. Merci à Christophe Avonture le papa de AllEvents pour l'info.

Sans le paramètre TRUE votre code renverra

var MonTexte=\'Il était une fois dans l'ouest\';

alors qu'avec le paramètre TRUE on obtient

var MonTexte=\'Il était une fois dans l\'ouest\';

Utilisation dans un fichier externe

Imaginons que l'on ait un fichier Javascript de plusieurs centaines de ligne que l'on appelle dans la page. Il n'est pas envisageable de faire comme précédemment pour ajouter des traductions dans le code. Il existe donc une extension de JText qui permet de définir une variable traduite et de la stocker dans le script.

Dans votre page PHP vous devez d'abord déclarer la variable à stocker :

JText::script('KEY');

Cette fonction va récupérer la traduction de KEY et la stocker en javascript dans la page. On peut ensuite l'appeler à partir de notre fichier :

alert(Joomla.JText._('KEY', 'Texte par défaut');

Le deuxième paramètre est le texte par défaut qui sera utilisé si aucune traduction n'est trouvée par le système.

Voilà, on a fait le tour de la fonction JText, vous n'avez plus d'excuses pour ajouter les traductions pour le multilingue à vos extensions et sites Joomla.