Internationalisation du code
Table des matières
PHPBoost étant un projet d'ambition internationale, le code du logiciel en lui-même doit être indépendant de la langue de l'utilisateur. Toutes les textes, expressions et autres utilisés dans le code source étant spécifiques à une langue doivent être stockés dans des variables, variables dont les valeurs sont chargées à partir d'un fichier langue. C'est ainsi que pour traduire un module, il suffit de créer un fichier contenant toutes les expressions écrites dans la langue cible et le module fonctionnera dans cette nouvelle langue
Les langues d'un module sont stockées dans le répertoire lang placé à la racine du module. Ce répertoire contient un dossier par langue dont le nom est le nom anglais de la langue. Par exemple pour le français vous trouverez un dossier /french avec dans celui-ci un fichier php contenant la déclaration d'un tableau associatif. Ce dernier associe à chaque identifiant d'expression l'expression écrite dans la langue correspondante au fichier. L'identifiant étant invariable de la langue de l'utilisateur, il est utilisé dans le code pour identifier une expression et le noyau y associera automatiquement l'expression dans la langue de l'utilisateur.
Voici un exemple de déclaration :
Par convention, les identifiants des expressions sont écrits en anglais.
Les fichiers langue des modules doivent être placés dans le dossier lang placé dans le dossier de votre module.
Dans ce dossier, il y aura un sous-dossier par langue supportée par le module. Par exemple, si nous voulons faire en sorte qu'un module soit utilisable en anglais et en français, nous créons deux dossiers english et french.
Vous devez placer dans ces sous-dossiers le fichier contenant les traductions dans la langue correspondante. Ce fichier s'appelle nommodule_langue.php. En supposant que le module s'appelle mymodule, on doit créer les fichiers /mymodule/lang/french/mymodule_french.php et /mymodule/lang/english/mymodule_english.php.
Le fichier mymodule_french.php contient par exemple :
Alors que le fichier mymodule_english.php contient :
Les fichiers des différentes langues doivent contenir les traductions de toutes les traductions. Autrement dit, ils doivent tous contenir les mêmes entrées.
Attention lors des mises à jour d'un module, il faudra que les fichiers langues soient tous mis à jour pour être utilisables.
Le noyau est à même de prendre en charge la sélection et le chargement des fichiers langue. Il prendra de préférence la langue de l'utilisateur, mais il se peut qu'elle n'existe pas, et dans ce cas-là il fera en sorte d'en charger une autre.
Le chargement se fait avec la fonction
Maintenant que votre module est prêt à être internationalisé, il faut adapter son code en conséquence. Ainsi, aucune expression dépendant de la langue de l'utilisateur ne doit être présente dans les templates du module. Utilisez plutôt des variables template pour faire cela.
Une fois que vous avez chargé votre fichier langue, vous pouvez directement accéder aux variables que vous avez définies. L'exemple suivant le montre :
Ce code affichera Bonjour tout le monde ! si l'utilisateur a choisi le français dans son profil, alors qu'il affichera Hello world! pour les anglophones.
Enjeux & principe de la solution
PHPBoost étant un projet d'ambition internationale, le code du logiciel en lui-même doit être indépendant de la langue de l'utilisateur. Toutes les textes, expressions et autres utilisés dans le code source étant spécifiques à une langue doivent être stockés dans des variables, variables dont les valeurs sont chargées à partir d'un fichier langue. C'est ainsi que pour traduire un module, il suffit de créer un fichier contenant toutes les expressions écrites dans la langue cible et le module fonctionnera dans cette nouvelle langue
La solution choisie dans PHPBoost
Les langues d'un module sont stockées dans le répertoire lang placé à la racine du module. Ce répertoire contient un dossier par langue dont le nom est le nom anglais de la langue. Par exemple pour le français vous trouverez un dossier /french avec dans celui-ci un fichier php contenant la déclaration d'un tableau associatif. Ce dernier associe à chaque identifiant d'expression l'expression écrite dans la langue correspondante au fichier. L'identifiant étant invariable de la langue de l'utilisateur, il est utilisé dans le code pour identifier une expression et le noyau y associera automatiquement l'expression dans la langue de l'utilisateur.
Voici un exemple de déclaration :
Code PHP :
$MODULE_LANG = array(); $MODULE_LANG['hello_world'] = 'Bonjour tout le monde !';
Par convention, les identifiants des expressions sont écrits en anglais.
Emplacement des fichiers langue
Les fichiers langue des modules doivent être placés dans le dossier lang placé dans le dossier de votre module.
Dans ce dossier, il y aura un sous-dossier par langue supportée par le module. Par exemple, si nous voulons faire en sorte qu'un module soit utilisable en anglais et en français, nous créons deux dossiers english et french.
Vous devez placer dans ces sous-dossiers le fichier contenant les traductions dans la langue correspondante. Ce fichier s'appelle nommodule_langue.php. En supposant que le module s'appelle mymodule, on doit créer les fichiers /mymodule/lang/french/mymodule_french.php et /mymodule/lang/english/mymodule_english.php.
Le fichier mymodule_french.php contient par exemple :
Code PHP :
$MODULE_LANG = array(); $MODULE_LANG['hello_world'] = 'Bonjour tout le monde !';
Alors que le fichier mymodule_english.php contient :
Code PHP :
$MODULE_LANG = array(); $MODULE_LANG['hello_world'] = 'Hello world!';
Les fichiers des différentes langues doivent contenir les traductions de toutes les traductions. Autrement dit, ils doivent tous contenir les mêmes entrées.
Attention lors des mises à jour d'un module, il faudra que les fichiers langues soient tous mis à jour pour être utilisables.
Charger un fichier langue
Le noyau est à même de prendre en charge la sélection et le chargement des fichiers langue. Il prendra de préférence la langue de l'utilisateur, mais il se peut qu'elle n'existe pas, et dans ce cas-là il fera en sorte d'en charger une autre.
Le chargement se fait avec la fonction
load_module_lang($module);. Il suffit de lui donner en paramètre le nom du module pour lequel on souhaite charger la langue.
Écrire du code internationalisable
Maintenant que votre module est prêt à être internationalisé, il faut adapter son code en conséquence. Ainsi, aucune expression dépendant de la langue de l'utilisateur ne doit être présente dans les templates du module. Utilisez plutôt des variables template pour faire cela.
Une fois que vous avez chargé votre fichier langue, vous pouvez directement accéder aux variables que vous avez définies. L'exemple suivant le montre :
Code PHP :
//Chargement des expressions du module (à faire une fois dans la page) load_module_lang('module'); //On utilise l'expression correspondant à hello_world dans la langue de l'utilisateur echo $MODULE_LANG['hello_world'];
Ce code affichera Bonjour tout le monde ! si l'utilisateur a choisi le français dans son profil, alors qu'il affichera Hello world! pour les anglophones.