RBS Change permet l'internationalisation de l'interface utilisateur : le code utilise des “clefs” qui sont interprétées et remplacées par leur traduction dans la langue courante.

Une clef est composée de caractères alphanumériques et des caractères '.' et '-'.

Les traductions des clefs sont dans des fichiers XML, dont le chemin est déduit de la clef et de la langue demandée : ainsi à la clef m.mymodule.fo.mykey et à la langue française correspond le fichier modules/mymodule/i18n/fo/fr_FR.xml, qui doit contenir la traduction de la clef “mykey”.

Plus précisément, selon qu'une clef commence par “m.”, “t.” ou “f.”, le fichier d'internationalisation est dans le dossier “modules/”, “themes/” ou “framework/”. Le reste de la clef correspond à des sous-dossiers, le caractère '.' étant remplacé par '/' :

• La clef m.<moduleName>.folder1.folder2.some-key correspond au fichier modules/<moduleName>/i18n/folder1/folder2/<lang>.xml
• La clef t.<themeName>.folder1.folder2.some-key correspond au fichier themes/<themeName>/i18n/folder1/folder2/<lang>.xml
• La clef f.folder1.folder2.some-key correspond au fichier framework/i18n/folder1/folder2/<lang>.xml

N.B. : notez le sous-dossier i18n qui est présent dans tous les chemins.

Les clefs peuvent contenir des variables qui peuvent être remplacées dynamiquement lors de la traduction de la clef. Une variable est entourée d'accolades.

Dans l'exemple suivant, la clef m.mymodule.fo.confirm-sent utilise la variable “email” :

<?xml version="1.0" encoding="utf-8"?>
<i18n baseKey="m.mymodule.fo" lcid="fr_FR">
  <key id="confirm-sent">Un mail de confirmation a été envoyé à {email}</key>
</i18n>

Voyez l'utilisation de variables de substitution dans un contexte PHP et dans un contexte PHPTal.

La structure d'un fichier d'internationalisation est relativement simple : sous un élément racine <i18n/>, on trouve des éléments <key/> pour chaque clef que le fichier défini. L'attribut id de l'élément <key/> correspond à la dernière partie de la clef, son contenu est la valeur de la clef.

L'attribut baseKey de l'élément <i18n /> correspond au chemin menant au dossier contenant le fichier tandis que l'attribut lcid correspond au code ISO-639 de la langue suivi du code ISO-3166 du pays.

Ainsi l'exemple suivant correspond au fichier modules/mymodule/fo/fr_FR.xml, qui définit la valeur française de deux clefs : m.mymodule.fo.my-key et m.mymodule.fo.my-other-key :

<?xml version="1.0" encoding="utf-8"?>
<i18n baseKey="m.mymodule.fo" lcid="fr_FR">
  <key id="my-key">Ma clef en Français</key>
  <key id="my-other-key">Mon autre clef en Français</key>
</i18n>

Les versions anglaises de ces clefs sont définie dans le fichier modules/mymodule/i18n/fo/en_GB.xml, … etc.

Un fichier peut inclure les clefs définies dans un autre fichier avec l'élément <include />, l'attribut id indiquant le fichier à importer.

Un fichier d'internationalisation d'un document pourra par exemple inclure le fichier de son document parent et profiter des traductions déjà définies, avec la possibilité de redéfinir certaines des traductions.

Avec modules/mymodule/i18n/document/parentdocument/fr_FR.xml contenant :

<?xml version="1.0" encoding="utf-8"?>
<i18n baseKey="m.mymodule.document.parentdocument" lcid="fr_FR">
  <key id="label">Libellé</key>
  <key id="creationdate">Date de création</key>
</i18n>

Le fichier modules/mymodule/i18n/document/childdocument/fr_FR.xml :

<?xml version="1.0" encoding="utf-8"?>
<i18n baseKey="m.mymodule.document.childdocument" lcid="fr_FR">
  <include id="m.mymodule.document.parentdocument" />
  <key id="label">Libellé surchargé</key>
  <key id="childProperty">Ma propriété</key>
</i18n>

Définira les traductions suivantes :

• m.mymodule.document.childdocument.label, valant “Libellé surchargé” (traduction redéfinie)
• m.mymodule.document.childdocument.creationdate, valant “Date de création” (traduction héritée)
• m.mymodule.document.childdocument.childProperty, valant “Ma propriété” (traduction spécifique)

Par défaut, le format d'une clef est “texte brut”. Lorsque la clef contient de l'HTML que l'on veut préserver, on donne la valeur “html” à l'attribut format de l'élément <key/>. Le formateur "html" n'aura alors plus d'effet, ce qui permettra d'insérer de l'HTML “traduit” dans un gabarit PHPTal par exemple.

Exemple : clef m.solrsearch.frontoffice.result-title, utilisée pour générer le titre HTML d'une page de résultat de recherche :

<i18n>
  <key id="result-title" format="html"><![CDATA[Votre recherche sur <em class="highlight">{terms}</em> a mené à {count} résultats]]></key>
</i18n>

Les fichiers d'internationalisation peuvent être surchargés dans le dossier override/. Le contenu est alors l'union des deux fichiers, le fichiers du dossier override ayant priorité sur le fichier original.

Lorsqu'un fichier d'internationalisation est modifié, il doit être chargé en base de données, en exécutant la Change compile-locales :

change.php compile-locales

Depuis le code PHP, la traduction de clef dans la langue du contexte se fait avec la méthode transFO() du service LocaleService.

Exemple : traduction de la clef m.mymodule.fo.my-key

$translated = LocaleService::getInstance()->transFO("m.mymodule.fo.my-key");

La méthode transFO() prend deux arguments optionnels : le tableau des formateurs et le tableau des substitutions.

Exemple : traduction de la clef m.mymodule.fo.my-key, utilisant les formateurs “html” et “label” :

$formatters = array("html", "label");
$translated = LocaleService::getInstance()->transFO("m.mymodule.fo.my-key", $formatters);

Exemple : traduction de la clef m.mymodule.fo.mail-sent, en utilisant le formateur “html” et en définissant “email” = “johndoe@rbs.fr” :

$substitutions = array("email" => "johndoe@rbs.fr");
$translated = LocaleService::getInstance()->transFO("m.mymodule.fo.mail-sent", array("html"), substitutions);

Le préfixe PHPTal trans permet la traduction de clefs depuis un gabarit PHPTal.

Dans le contexte du backoffice, il faut savoir distinguer la langue de l'interface backoffice (sélectionnée lors de l'identification) de la langue de travail (Menu “Outils > Choisir ma langue de travail”) :

• Pour traduire des clefs dans la langue de l'interface, on utilise transui (depuis PHPtal) qui s'utilise comme trans et la méthode transBO() de LocaleService, qui s'utilise comme transFO() (depuis un code PHP)
• Pour traduire dans la langue de travail, on utilise trans (depuis PHPTal) et la méthode transFO() de LocalService (depuis PHP).

Une fois traduites, les clefs peuvent être formatées. Voici la liste des formateurs, cumulables :

Voyez l'utilisation des formateurs dans un contexte PHP et dans un contexte PHPTal.