Le fichier i18n

Fonctionnement

Le fichier i18n.xml permet de faire le lien entre des termes définis de manière générique et leur rendu dans la langue définie sur le moteur d’affichage. Il permet par exemple de gérer l’affichage des éléments du menu ou des titres du sommaire dans la langue choisie par l’utilisateur.

Il faut donc autant de fichier i18n.xml que de langue(s) définie(s) dans l’édition.

Exemple d’un fichier i18n en français :

<!-- Fichier i18n-fr.xml -->
<properties>
    <!-- Menu et sous-menu -->
    <entry key="menu.accueil">Accueil</entry>
    <entry key="menu.sommaire">Sommaire</entry>
    <entry key="menu.meta">Description scientifique</entry>
    <entry key="menu.porte-documents">Porte-documents</entry>

    <!-- Sommaire -->
    <entry key="toc.titre">Recherche par catégories</entry>
    <entry key="toc.ART">Art - Littérature</entry>
    <entry key="toc.DROIT">Droit - Formation professionnelle</entry>
    <entry key="toc.ELEVAGE">Élevage - soins</entry>
    <entry key="toc.EQUITATION">Équitation, courses</entry>
</properties>

Dans la balise entry, l’attribut key contient le terme générique : un seul terme qui se retrouvera dans les différents fichiers i18n des différentes langues. En revanche, le texte à l’intérieur des balises entry change en fonction de la langue définie par l’utilisateur sur MaX.

Deux fichiers existent par défaut dans le cœur de MaX, pour des éditions en français et en anglais :

• Pour une édition en français : [projet-]MaX/ui/i18n/i18n-fr.xml
• Pour une édition en anglais : [projet-]MaX/ui/i18n/i18n-en.xml

Pour surcharger les fichiers XML, il faut créer un fichier i18n[-langueLocale].xml dans le dossier [projet-]editions/[edition]/ui/i18n (par exemple i18n-fr.xml ou i18n-en.xml).

=> Pour chaque nouveau fichier i18n, le préfixe utilisé doit correspondre au code ISO alpha-2 de la langue utilisée (ici fr et en).

Ces fichiers sont ensuite transformés par la feuille XSL i18n.xsl, qui se trouve dans le dossier [projet-]MaX/ui/xsl/core.

Pour que les éléments du i18n soient pris en compte, il est nécessaire de créer, dans le dossier fragments de chaque édition, un dossier correspondant à la langue du i18n (en respectant toujours les codes de la norme ISO).
Par exemple : [projet-]editions/[edition]/fragments/fr pour une édition en français.

Le nom donné à ce dossier sera celui accolé au nom du fichier i18n.xml. Pour un dossier fragments/en, on aura un fichier ui/i18n/i18n-en.xml.

Pour chaque page HTML statique (accueil, contact, bibliographie...), il faudra créer autant de fichiers avec l’extension .frag.html que de langue(s) définie(s).
Par exemple, pour une édition en français et en anglais qui propose une page Contact, on placera un fichier contact.frag.html, rédigé en français, dans le dossier fragments/fr et un fichier contact.frag.html, rédigé en anglais, dans le dossier fragments/en.

Modifier la langue à afficher par défaut

Par défaut, lors de l’arrivée sur le site de l’édition, MaX affiche le contenu du fichier i18n-fr.xml, et les fragments du dossier fragments/fr.

Pour modifier ce comportement et afficher une autre langue par défaut, il faut ajouter le paramètre @lang au fichier de configuration [mon-edition]_config-inc.xml, dans le dossier [projet-]editions/[mon-edition].

Par exemple, pour une version par défaut en anglais :

 <edition xml:id="mon-edition" dbpath="monedition" 
 env="ead" prettyName="My edition in EAD" lang="en">

La valeur de l’attribut @lang doit correspondre au code ISO de la langue utilisée (ici en), qui sera également le nom du dossier dans le dossier fragments et le préfixe du fichier i18n.xml.

Ce paramètre de l’attribut @lang est facultatif : s’il n’est pas ajouté, MaX affiche par défaut la version en français.

Exemples

Définir l’affichage du menu

Pour définir l’affichage du menu en fonction de la langue, dans les balises <id> du fichier menu.xml, on déclare des termes génériques ("accueil", "sommaire"...).

<!-- Exemple d’un fichier menu.xml -->
<menu>
    <entry type="main">
        <id>accueil</id>
        <target>accueil.html</target>
    </entry>
    <entry type="main">
        <id>sommaire</id>
        <target>sommaire.html</target>
    </entry>
</menu>

Ces termes génériques doivent ensuite être déclarés dans les balises <entry> des différents fichiers i18n.xml, pour définir le texte à afficher dans chaque langue.

Ce qui donnera dans les deux fichiers i18n.xml, en français et en anglais :

<!-- Exemple d’un fichier i18n-fr.xml -->
<properties>
    <entry key="menu.accueil">Accueil</entry>
    <entry key="menu.sommaire">Sommaire</entry>
</properties>

<!-- Exemple d’un fichier i18n-en.xml -->
<properties>
    <entry key="menu.accueil">Home</entry>
    <entry key="menu.sommaire">Summary</entry>
</properties>

Définir l’affichage du sommaire

Pour définir le titre de la page de sommaire d’une édition en fonction de la langue, on déclare un terme générique dans une balise <xsl:value-of>, dans le fichier toc.xsl. Par exemple, "toc.title".

<!-- Exemple d’un fichier toc.xsl -->
<xsl:template match="/">
  <div id="toc">
    <h1>
      <xsl:value-of select="max:i18n($project,'toc.title',$locale)"/>
    </h1>
  </div>
</xsl:template>

Ce terme générique doit ensuite être déclaré dans une balise <entry> des différents fichiers i18n.xml. Ce qui donnera dans les deux fichiers i18n.xml, en français et en anglais :

<!-- Exemple d’un fichier i18n-fr.xml -->
<properties>
    <entry key="toc.titre">Cadre de classement</entry>
</properties>

<!-- Exemple d’un fichier i18n-en.xml -->
<properties>
    <entry key="toc.titre">File plan</entry>
</properties>