Documentation
Plugin de localisation multilingue
Table des matières ▼
Pré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.
Configuration
Dans le fichier temma.json, 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).
Fonctionnement
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.
Gestion 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.
URLs 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 '/'.
Pré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
Fichiers 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.
Utilisation 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 :
{"Model"|l10n}
{"Views"|l10n}
{"header#Home"|l10n}
{"header#Download"|l10n}
Affiché en française, cela donnera :
Modèle
Vues
Accueil
Télécharger
- 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 (#).
Pré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 temma.json (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
Précédent : | Plugin de cache |
Suivant : | Helper attribut d'authentification |
Table des matières
- Migration : Comment passer de Temma 1.x à la version 2
- Installation : Télécharger Temma et l'installer pour démarrer votre projet Web
- Configuration : Toutes les directives de configuration du fichier etc/temma.json et les variables d'environnement utilisables en option
- Bibliothèques externes : Comment utiliser des bibliothèques de fonctions externes
- Routage : Le système de routage par défaut de Temma, et le routage avancé
- Log : Utilisation du système de log, gestion par niveaux de criticité
- Contrôleurs : Pièces essentiels de votre application Web
- Vues : Templates Smarty ou exports JSON/CSV/RSS/iCal/INI
- Injection de dépendances : La colonne vertébrale de vos développements applicatifs
- Sessions : Extension des sessions utilisateurs gérées par PHP
- Sources de données : Pour gérer l'accès aux données de manière unifiée
- Modèle : Comment utiliser les DAO pour accéder aux bases de données
- Flux d'exécution : Comment gérer le flux d'exécution, entre les plugins et le contrôleur
- Plugins : Comment utiliser les plugins, et écrire les vôtres pour modulariser votre code
- Attributs : Comment filtrer l'accès aux contrôleurs et aux actions
- Tests : Pour écrire des tests d'intégration automatisés.
- Interface en ligne de commande : Pour créer des scripts exécutables en ligne de commande, initialisés automatiquement par Temma
-
Helpers :
Objets proposés par Temma pour vous aider dans plusieurs circonstances
- Scripts en ligne de commande
-
Contrôleur + plugin
- Auth : Contrôleur et plugin servant à gérer l'authentification des utilisateurs
- Plugins
- Attributs
-
Plugins Smarty
- urlize : Modificateur transformant un texte en URL
- filenamize : Modificateur transformant un texte en nom de fichier
- nbsp : Modificateur transformant des espaces en espaces non sécables
-
Objets utilitaires
- ANSI : Pour mettre en forme les textes écrits sur la sortie standard
- BaseConvert : Pour faire des conversions de bases numériques
- DataFilter : Pour filtrer et valider des données
- Email : Pour envoyer des emails
- HTMLCleaner : Pour nettoyer un flux HTML provenant d'un éditeur WYSIWYG
- IniExport : Pour exporter des données au format INI
- Json : Pour lire des flux JSON pouvant contenir des commentaires
- Lock : Pour verrouiller l'accès à un fichier, ou l'exécution du script PHP courant
- Registry : Pour stocker proprement des variables globales
- Smarty : Pour traiter des templates Smarty en dehors de la vue
- Term : Gestion des terminaux (TTY)
- Text : Différents traitements sur les chaînes de caractères
- Timer : Pour gérer des chronomètres