Outils pour utilisateurs

Outils du site


Panneau latéral

ref:core:internationalisation_de_l_interface

Ceci est une ancienne révision du document !


Contenu en cours de rédaction / validation

Attention : le contenu de cette page n'est valide qu'à partir de la version 3.5.0 de RBS Change.

Internationalisation de l'interface

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.

Clefs et fichiers d'internationalisation

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.

Variables de substitution

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.

Structure d'un fichier d'internationalisation

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.

Ré-utilisation de clefs

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)

Clef HTML

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>

Surcharge des fichiers d'internationalisation

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.

Compilation

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

Utilisations

Dans un code PHP

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);

Dans un gabarit PHPTal

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

Dans le backoffice

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).

Formatages

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

Nom Description
uc UpperCase : met en majuscules
ucf UpperCaseFirst : met en majuscules la première lettre
ucw UpperCaseWord : met en majuscule la première lettre de chaque mot
lc LowerCase : met en minuscules
attr Attribute : échappe pour le contexte d'un attribut HTML
js JavaScript : échappe les caractères pour le contexte d'une chaîne JavaScript
html HTML : échappe pour un contexte HTML
lab Label : rajoute ':' en fin de chaîne. Pour le Français, rajoute ' :'
text (Plain) Text : version texte brut ; n'a une action que si la traduction est définie dans le format HTML
space Space : rajoute un espace en début et fin de clef
etc Etc : rajoute un “…” en fin de chaine

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

ref/core/internationalisation_de_l_interface.1318325495.txt.gz · Dernière modification: 2017/01/19 14:54 (modification externe)