Chaque texte ou chaîne que vous voulez traduire est associée à une clé, un code. Ces associations sont stockées dans des fichiers "properties". Chaque fichier properties étant attribué à une langue et un encodage de caractère. La langue et l'encodage par défaut sont configurés dans le fichier de config de votre application : ce sont les paramètres locale et charset, que vous pouvez récupérer en faisant

  $lang = $GLOBALS['gJConfig']->locale;

Mais vous n'aurez pas à utiliser ce paramètre, sauf utilisation particulière. En effet, pour récupérer une chaîne dans la langue courante, il suffit d'appeler jLocale::get('selecteurDeLocale'), ou dans les templates d'utiliser la syntaxe @selecteurDeLocale@ (voir la page sur les templates).

Ce sont des fichiers contenant des traductions. Ils sont situés dans le répertoire locales des modules. Ce répertoire a une organisation spécifique. Il contient des sous répertoires pour chaque langue. Exemple :locales/fr_FR/, locales/en_US/, etc. Et dans chacun de ces sous-répertoires, il y a les fichiers properties correspondant à la langue.

Noms des fichiers ¶

Contenu des fichiers ¶

title.offlineElements = éléments à traiter
title.onlineElements = éléments en ligne
buttons.save = Enregistrer
buttons.ok=Valider
buttons.cancel=Annuler
buttons.search=Rechercher

title.offlineElements = elements to check
title.onlineElements = online elements

buttons.save = Save
buttons.ok=Ok
buttons.cancel=Cancel
buttons.search=Search

intro=ceci est un trés tres\
long texte qui fait\
plusieurs lignes
foo=bar

intro=ceci est un très très\
 long texte qui fait\nplusieurs lignes\nfoo=bar

foo= \w

mon.beau.titre.de.paragraphe.html = <strong>Mon Titre de paragraphe</strong>

Pour récupérer une chaîne, il faut utiliser la méthode statique get de jLocale. Cette méthode accepte en premier argument un sélecteur de locale, qui a cette structure : module~codefichier.clechaine. la partie "module~" est facultative s'il s'agit d'un fichier se trouvant dans le module courant.

Pour récupérer par exemple la valeur de buttons.save dans foo.ISO-8859-1.properties situé dans le module "bar" :

  $chaine = jLocale::get("bar~foo.buttons.save");

Dans un template cela donnerait par exemple :

  <input type="button" value="{@bar~foo.buttons.save@}" />

Note : pour l'utilisation dans les templates, voir les possibilités dans la page sur les templates

Il peut être utile d'avoir des chaînes localisées dans lesquelles on veut insérer des valeurs dynamiquement. Par exemple, imaginons que voulez écrire :

   Vous allez sur le site http://foo.com et vous cliquez sur la rubrique voiture

Vous voulez pouvoir changer l'url du site et le nom de la rubrique. Vous pouvez alors passer les données en paramètres à jLocal :

  $chaine = jLocale::get("bar~foo.phrase", array('http://foo.com', 'voiture'));

Et dans le fichier properties, vous mettez un %s partout où vous voulez insérer des valeurs dynamiques :

   phrase = Vous allez sur le site %s et vous cliquez sur la rubrique %s

Et il faut donner les paramètres dans l'ordre d'apparition des %s. En fait, la chaîne est traité par la fonction sprintf de php, donc vous avez toutes les possibilités syntaxiques de sprintf.

En particulier, il se peut que l'ordre d'insertion des paramètres change d'une langue à une autre. Plutôt donc que de modifier l'ordre des paramètres quand vous appelez jLocale, vous indiquez quel paramètre va à quel endroit dans la chaîne localisée, au moyen de la syntaxe %x$s où x est un nombre d'ordre.

   phrase = Vous allez sur le site %1$s et vous cliquez sur la rubrique %2$s

En anglais (même si ce n'est pas la véritable traduction, c'est juste pour l'exemple) ça pourrait donner ça :

   phrase = Clic on the %2$s section, when you go on the %1$s web site.

Ainsi le premier paramètre ira à l'emplacement de %1$s, le deuxième à la place de %2$s etc...

Par contre, dans un template, vous ne pouvez pas utiliser la notion "@foo@" quand il faut des paramètres. Vous devez alors utiliser le plugin jlocale :

   <p>{jlocale "bar~foo.phrase", array('http://foo.com', 'voiture')}</p>

Jelix fourni un plugin pour le coordinateur qui permet de changer la langue dynamiquement. C'est le plugin autolocale (qui est situé dans lib/jelix/plugins/coord/). (voir la section sur les plugins de coordinateur).

Pour cela, le plugin regarde si un paramètre est présent dans l'url, indiquant la nouvelle langue à prendre en compte, et utilisera cette langue durant le reste de la visite. En fait le nouveau code langue est stocké dans une variable de session, et le plugin modifie l'option de configuration locale une fois la configuration lue (le fichier de configuration n'est donc pas modifié).

Aussi c'est totalement transparent pour vous. Pour connaître la langue à tout moment, il suffit de faire comme d'habitude :

  $lang = $GLOBALS['gJConfig']->locale;

Pour utiliser le plugin, copiez le fichier lib/jelix/plugins/coord/autolocale/autolocale.coord.ini.php.dist dans var/config/ en le renommant autolocale.coord.ini.php.

Les trois paramètres importants dans ce fichier sont :

enableUrlDetection= on
urlParamNameLanguage=lang
availableLanguageCode = fr_FR,en_US

Il faut bien sûr activer la détection de la langue dans l'url avec le paramètre enableUrlDetection. availableLanguageCode permet d'indiquer la liste des code des langues disponibles sur le site, ainsi les autres codes langues ne seront pas possibles. Le paramètre urlParamNameLanguage contient le nom du paramètre de l'url qui contiendra le code langue à utiliser. Aussi, vous pouvez mettre des liens sur votre site qui permettent à l'utilisateur de changer la langue. Exemple :

  <a href="index.php?lang=fr_FR">français</a>
  <a href="index.php?lang=en_EN">english</a>

Bien sûr, si vous utilisez le moteur d'url significant, il est possible que vous définissiez des urls significatives spécifiques pour chaque langue.

Enfin, il faut activer le plugin. Pour cela, dans la configuration de jelix, mettez dans la section coordplugins :

[coordplugins]
autolocale = autolocale.coord.ini.php

Dans certains cas, pour éviter d'avoir trop de chaînes locales, il peut s'avérer intéressant de traduire un template complet.

Pour cela il suffit de placer le template qui nécessite l'internationalisation dans un sous-répertoire du répertoire templates. Comme pour les fichiers de locales un sous-répertoire est nécessaire pour chaque langue (Exemple : templates/fr_FR/, templates/en_US/).

Le plugin autolocale (voir paragraphe du dessus), permet aussi de détecter automatiquement la langue en fonction du navigateur.

Pour cela, il suffit de mettre le paramètre useDefaultLanguageBrowser à on dans la configuration du plugin. Et quand l'internaute arrive pour la première fois sur le site, le plugin détecte la langue utilisée dans son navigateur et donc active la bonne langue dans jelix (si bien sûr, ce code langue est l'un de ceux que vous aurez indiqué dans availableLanguageCode).