Internationalisation de l'interface [RBS Change]

Cette page est en lecture seule. Vous pouvez afficher le texte source, mais ne pourrez pas le modifier. Contactez votre administrateur si vous pensez qu'il s'agit d'une erreur.
**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" :
<code xml>
<?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>
</code>

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'' :

<code xml>
<?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>
</code>

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 :

<code xml>
<?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>
</code>

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

<sxh xml; highlight: [3]; gutter: false>
<?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>
</sxh>

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 [[#Formatages|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 :
<code xml>
<i18n>
  <key id="result-title" format="html"><![CDATA[Votre recherche sur <em class="highlight">{terms}</em> a mené à {count} résultats]]></key>
</i18n>
</code>
==== 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'' :

<code bash>
change.php compile-locales
</code>

===== 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''
<code php>
$translated = LocaleService::getInstance()->transFO("m.mymodule.fo.my-key");
</code>

La méthode ''transFO()'' prend deux arguments optionnels : le tableau des [[#Formatages|formateurs]] et le tableau des [[#Variables de substitution|substitutions]].

Exemple : traduction de la clef ''m.mymodule.fo.my-key'', utilisant les formateurs "html" et "label" :
<code php>
$formatters = array("html", "label");
$translated = LocaleService::getInstance()->transFO("m.mymodule.fo.my-key", $formatters);
</code>

Exemple : traduction de la clef ''m.mymodule.fo.mail-sent'', en utilisant le formateur "html" et en définissant "email" = "johndoe@rbs.fr" :
<code php>
$substitutions = array("email" => "johndoe@rbs.fr");
$translated = LocaleService::getInstance()->transFO("m.mymodule.fo.mail-sent", array("html"), substitutions);
</code>

==== Dans un gabarit PHPTal  ====

Le préfixe PHPTal ''[[ref:phptal:internationalisation#trans|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 ''[[ref:phptal:internationalisation#trans|trans]]'' et la méthode ''transBO()'' de ''LocaleService'', qui s'utilise comme [[#Dans un code PHP|transFO()]] (depuis un code PHP)
  * Pour traduire dans la langue de travail, on utilise ''[[ref:phptal:internationalisation#trans|trans]]'' (depuis PHPTal) et la méthode ''[[#Dans un code PHP|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 [[#Dans un code PHP|contexte PHP]] et dans un [[#Dans un gabarit PHPTal|contexte PHPTal]].
Outils pour utilisateurs

Outils du site

Outils de la page

Outils de la page
