Présentation
Configuration
Fonctionnement
Méthodes des requêtes
URLs protégées
Préfixe des templates
Fichiers de traduction
Utilisation dans les templates
Préfixe aux fichiers d'erreur

Plugin de localisation multilingue

1Présentation

Ce plugin permet deux choses :

Gérer des URLs qui sont préfixées par la langue. Le plugin va donc rediriger automatiquement l'utilisateur vers la page demandée avec /fr/ (par exemple) au début de l'URL.
Charger automatiquement les traductions correspondant à la langue utilisée, pour mettre les chaînes de caractère traduites à disposition des templates.

2Configuration

Dans le fichier etc/temma.php, il faut ajouter le pré-plugin et le configurer :

[
    // chargement du plugin
    'plugins' => [
        '_pre' => [
            '\Temma\Plugins\Language'
        ]
    ],
    // configuration du plugin
    'x-language' => [
        // liste des langues supportées par le site
        'supported' => [ 'fr', 'en', 'de' ],
        // langue par défaut, si le navigateur n'est compatible avec
        // aucune des langues listées ci-dessus
        'default' => 'fr',
        // (optionnel) on peut indiquer de ne pas utiliser les
        // préfixes de template (voir plus bas)
        'templatePrefix' => false,
        // (optionnel) on peut indiquer les URLs pour lesquelles
        // la gestion de la langue n'est pas activée
        'protectedUrls' => [
            '/robots.txt',
            '/sitemap.xml',
        ]
    ],
    // configuration de la vue Smarty
    'x-smarty-view' => [
        'pluginsDir' => '/path/to/project/lib/smarty-plugins'
    ]
]

Lignes 3 à 7 : Configuration des plugins.
- Ligne 5 : Activation du pré-plugin qui prend en charge la gestion des langues.
Lignes 9 à 24 : Configuration du plugin.
- Ligne 11 : Liste des langues supportées sur le site.
- Ligne 14 : Définition de la langue par défaut (utilisée si le navigateur n'est compatible avec aucune des langues listées.
- Lignes 20 à 23 : Définition de la liste des URLs pour lesquelles la gestion de la langue est désactivée.
Lignes 26 à 28 : Configuration de la vue Smarty.
- Ligne 27 : Ajout du répertoire contenant les plugins Smarty fournis par Temma, pour que l'interpréteur Smarty soit capable de trouver l'extension (voir plus bas).

3Fonctionnement

Dans l'exemple de la configuration ci-dessus, on indique que le site possède des traductions en français, anglais et allemand.

Lorsqu'un navigateur va demander une page, il peut se produire deux cas de figure :

Soit l'URL demandée ne commence pas par /fr/, /en/ ni /de/. Dans ce cas, le plugin va rediriger l'utilisateur vers l'URL demandée, en lui ajoutant le préfixe de langue. La langue choisie sera la première supportée par le navigateur qui est aussi supportée par le site (si aucune ne convient, ce sera la langue par défaut du site qui sera utilisée).
Soit l'URL demandée commence par un préfixe de langue. Dans ce cas, le plugin va vérifier que la langue demandée est bien supportée par le site (si ce n'est pas le cas, on se retrouve dans le cas précédent). Si la langue est bien supportée, le plugin va extraire la langue, et modifier toutes les informations relatives au contrôleur, à l'action et aux paramètres, pour faire comme si ce préfixe n'avait pas existé dans l'URL. À côté de ça, le plugin charge le fichier de traductions correspondant, et ajoute un préfixe au chemin menant vers les fichiers de template.

Par exemple, si l'utilisateur demande la page /page/liste/date/5, avec un navigateur qui supporte le français, le plugin va le rediriger vers /fr/page/liste/date/5.

En arrivant sur /fr/page/liste/date/5, le plugin va extraire la langue (fr), va charger le fichier de traduction en français. Ensuite, il va modifier plusieurs choses :

Le contrôleur demandé devient page (et non plus fr).
L'action demandée devient liste (et non plus page).
La liste des paramètres devient ['date', '5'] (et non plus ['liste', 'date', '5']).

Les variables de template $CONTROLLER, $ACTION et $URL sont aussi modifiées en conséquence.

4Gestion des méthodes des requêtes

Si l'URL demandée commence par une information de langue (et que cette langue est autorisée par la configuration), le traitement expliqué ci-dessus s'effectuera toujours.

Par contre, si l'information de langue est absente, la redirection (vers la même URL à laquelle est ajouté le préfixe de langue) ne s'effectue pas si la requête avait une méthode POST ou PUT. Dans ce cas, le plugin ne fait rien et les traitements continuent normalement.

5URLs protégées

Il est possible de définir une liste d'URLs qui ne seront pas gérées par le plugin de langue. Cela est utile si vous avez par exemple des contrôleurs qui génèrent automatiquement le contenu des fichiers robots.txt ou sitemap.xml.

Attention, les URLs doivent commencer par le caractère '/'.

6Préfixe au chemin vers les templates

À moins que la variable de configuration templatePrefix ait été configurée à false, le plugin va modifier le chemin menant aux fichiers de template, en y ajoutant au début un répertoire correspondant à la langue demandée.

Ainsi, si l'URL est /fr/article/liste, le template utilisé sera (par défaut) le fichier templates/fr/article/liste.tpl

Si le contrôleur utilise un autre fichier, le préfixe sera ajouté de toute manière.
Par exemple, si le contrôleur contient la ligne suivante :

$this->_template('cms/content/article_list.tpl');

Temma utilisera le fichier templates/fr/cms/content/article_list.tpl

7Fichiers de traduction

Le plugin charge des fichiers contenant les traductions. Ce sont des fichiers au format INI, placés dans le répertoire etc/lang/ du projet, et nommés en fonction de la langue (fr.ini, en.ini, etc.).

Voici un exemple de fichier fr.ini :

[default]
Controllers="Contrôleurs"
Model="Modèle"
Views="Vues"

[header]
title="Temma : framework PHP simple et performant"
Home="Accueil"
Download="Télécharger"
Community="Communauté"
Examples="Exemples"

[footer]
Designed by="Conception par"

Comme vous pouvez le voir, les chaînes traduites sont classées par sections (ici default, header et footer). Ici encore, les chaînes de base sont en anglais, et on fournit par chacun leur traduction en français.

Important : Si on essyaye de traduire une châine de caractères, mais qu'elle est introuvable dans le fichier de traduction, elle sera utilisée telle quelle.
Dans l'exemple ci-dessus, on peut voir que les chaînes de base sont en anglais, et qu'on a fourni une traduction en français. Il ne sera donc pas nécessaire de fournir un fichier de traduction en anglais.

8Utilisation dans les templates

Dans les templates Smarty, deux variables supplémentaires sont crées par le plugin :

$lang : Contient la langue courante (fr, en, etc.).
$l10n : Contient le tableau des traductions. Ne doit pas être utilisée.

Pour traduire des chaînes de caractères, on utilisera le modificateur l10n :

<h1>{"Model"|l10n}</h1>
<h2>{"Views"|l10n}</h2>

{"header#Home"|l10n}
{"header#Download"|l10n}
{if $lang == 'fr'}
    Bonjour à tous
{else}
    Hello everyone
{/if}

Affiché en française, cela donnera :

<h1>Modèle</h1>
<h2>Vues</h2>

Accueil
Télécharger
    Bonjour à tous

En anglais :

<h1>Model</h1>
<h2>Views</h2>

Home
Download
    Hello everyone

Lignes 1 et 2 : Les chaînes listées dans la section default du fichier de traduction sont utilisables directement.
Lignes 4 et 5 : Les chaînes listées dans les autres sections doivent être préfixées avec le nom de la section, suivi du caractère dièse (#).
Ligne 6 : Il est possible de faire des tests sur la variable $lang pour insérer des textes longs.

9Préfixe aux fichiers d'erreur

Lorsque ce plugin est utilisé, il faut traduire les fichiers d'erreur définis dans la section errorPages du fichier etc/temma.php (voir la documentation).

Les chemins définis dans la configuration prennent alors un préfixe constitué d'un répertoire error-pages, suivi d'un répertoire correspondant à la langue utilisée.

Par exemple, pour le fichier de configuration suivant :

[
    'errorPages' => [
        '404' => 'error404.html'
    ]
]

Si on demande une page qui n'existe pas en langue française (par exemple l'URL /fr/sdsjnzeoizoueh), Temma ira chercher le fichier www/error-pages/fr/error404.html
Si on demande la même page en langue anglaise (par exemple l'URL /en/sdsjnzeoizoueh), Temma ira chercher le fichier www/error-pages/en/error404.html