Tutoriels

Installation du framework Premiers pas Mises à jour du framework Gérer les utilisateurs Gestion des textes et des langues Gestion des erreurs Créer ses classes & librairies

Classes & librairies

DSM.class.php DSMUser.class.php DSMMessage.class.php Libraire LJ Librairies internes

Gestion des textes et des langues

Introduction

Le framework intègre une fonctionnalité qui est très utile et simple à comprendre : la gestion automatique des langues. Cette dernière va vous permettre de gérer toutes vos strings suivant leurs langues.

La seconde fonctionalité dont ce tutoriel traitera, c'est la possibilité de gérer vos strings avec du BBCode

Traduire son site

Cette section a pour but de vous faire comprendre comment traduire dans différentes langues votre site. C'est à dire, pour les même textes, comment vous allez les écrire dans des langues différentes.

Les différentes langues gérées

La première chose à savoir, et c'est probablement la chose la plus importante concernant la gestion des langues, c'est qu'une chaîne de caractère (un mot, une phrase, un texte complet) sera desormais contenu dans un fichier ressource. Vos chaînes seront donc stockées dans un fichier qui se trouve quelque part dans le dossier resources.

Ces fichiers ressources contenant de nombreuses chaînes de caractères sont des fichiers de type XML. Un fichier de langue en XML est stocké dans le dossier resources/langs/"yourlang".

Avant d'aller plus loin dans la théorie, on va prendre un exemple : la page d'administration du framework possède de nombreuses chaînes de caractères qui ont été traduites en deux langues, le français et l'anglais. Pour gérer ces différentes langues, j'ai créé deux dossiers dans le dossier resources/langs. Le dossier resources/langs/fr, et le dossier resources/langs/en. Dans chacun de ces dossiers, il y a un fichier admin.xml, l'un où les chaînes de caractères sont écrits en français, l'autre en anglais.

Structure des fichiers XML

La structure des fichiers XML est très simple. Tout d'abord, toutes vos données doivent être stockés dans la balise resource. Cette balise contient trois attributs :

  • type : Cela définit le type de ressource contenu dans le fichier, ici c'est très simple, c'est du text. Mettez donc text
  • lang : Ici on met la langue des chaînes de caractères contenues dans le fichier. Par exemple, pour l'anglais on met en.
  • encoding : Enfin on renseigne l'encoding du fichier afin que les chaînes de caractères soient correctement interprétés. Il est conseillé de mettre le même encoding que votre site

Il faut ensuite ouvrir une balise page ou category pour enfin ajouter des strings.

L'architecture en cascade appliqué aux strings

Pour chaque page de votre site, on va créer une balise page dans laquelle on va ajouter toutes les chaînes de la page. Pour cela, on précise l'attribut name de la balise page avec l'adresse de la page. Cette adresse, c'est l'adresse relative du dossier de dev de la page dans le dossier dev. Pour faire plus clair, la page admin/control.php de votre site possède toutes ses chaînes de caractères spécifiques à l'intérieur d'une balise page avec comme valeur de l'attribut name l'adresse admin/control.

Néanmoins, un problème se pose. Sur chaque page nous avons des chaînes de caractères en commun : comme les titres des menus, l'en-tête, etc. Si on s'en tient à ce qui vous a été expliqué plus tôt, il va falloir ré-écrire ces chaînes pour chaque nouvelle page dans le fichier XML.

Par exemple, imaginons la chaîne de caractère chihuaha, elle a été ajoutée pour la page profil. Si l'on se trouve sur la page profil/gestion, la chaîne chihuahua est disponible. Toutefois, elle n'est pas disponible sur la page admin.

Pour une chaîne de caractère qui doit être disponible pour tout le dossier de développement, il faut mettre l'attribut name vide.

Définir une chaîne de caractère

Une fois que vous avez créé votre fichier xml, définit correctement sa structure (balise resource et page), il faut définir les chaînes de caractères. On le fait avec la balise string. Vous ouvrez une balise string, ajoutez votre chaîne de caractère, et fermez votre balise string.

Enfin, au sein de chacune des balises strings, ajoutez l'attribut id. La valeur de cet attribut va vous permettre d'identifier la chaîne de caractère créé, et ainsi l'ajouter dans votre page HTML à l'aide du framework.

Définition de la langue de la page

Définition de la langue du visiteur

Définir la langue du visiteur, c'est définir la langue dans laquelle le visiteur souhaite que votre site s'affiche. Par exemple, si un espagnol visite votre site, il aimerait bien qu'il s'affiche dans sa langue natale, l'espagnol. Donc la langue de ce visiteur est espagnol.

Pour déterminer la langue du visiteur, le framework va suivre les étapes suivantes :

  • Si l'utilisateur est connecté : on utilise la valeur de la propriété lang de l'utilisateur
  • S'il n'est pas connecté, on utilise la langue du navigateur
  • Si le framework n'a pas pu récupérer la langue du navigateur, on utilise la langue par défaut du framework que vous pouve zmodifier sur la page de contrôle
  • Dans tous les autres cas, on utilise la langue anglais, de valeur en.

Appel des ressources nécessaires

On connaît donc la langue dans laquelle le visiteur souhaite que le site s'affiche. Il est temps de définir quelle langue on va vraiment afficher sur le site. A chaque ajout de fichier ressource via la méthode setStrings, on suit la procédure suivante :

  • Si un fichier xml du nom donné en paramètre de setStrings existe dans un dossier du nom de la langue préférée de l'utilisateur, on ajoute cette ressource
  • Dans tous les cas, on ajoute aussi le fichier ressource du nom donné en paramètre de setStrings de la langue par défaut du site.

Je pense qu'un exemple est plus parlant que la phrase énoncée ci-dessus :

  • Le visiteur de la page est français, sa valeur de langue préférée vaut donc fr
  • La langue par défaut du site est l'anglais, sa valeur est en. Ce qui veut dire que le dossier resources/langs/en existe forcément.
  • Vous avez les fichiers resources/langs/en/menu.xml, resources/langs/fr/menu.xml et resources/langs/it/menu.xml qui contiennent les même strings (avec même id) mais dans deux langues différentes (l'anglais, le français et l'italien)
  • Vous faites un appel à la fonction setStrings :
$dsm -> setStrings('menu');?>
  • Les strings sont disponibles à l'affichage dans deux langues : le français (car c'est la langue préférée du visiteur) et l'anglais (car c'est la langue par défaut du site).
  • Si la langue préférée du visiteur avait été le mandarin, seul la langue anglaise aurait été disponible à l'affichage.

Afficher une string en fonction de la langue

Vous connaissez la langue préférée du visiteur et vous avez ajouté les ressources en conséquence, il faut maintenant afficher les strings contenues dans les xml dans votre page !

Pour cela c'est très simple, vous pouvez faire appel à la méthode string. Ou plus simplement encore, en appelant la méthode wstr. Dans un premier temps, on va se contenter d'utiliser la fonction wstr.

Vous voulez faire appel à la string ayant pour identifiant titre-principal sans prendre en compte la langue d'affichage. Si vous avez bien et bien ajouté le xml contenant cette string grâce à la méthode setStrings, et bien c'est très simple :

$dsm -> wstr('titre-principal');

La méthode wstr récupère la string et l'affichage (il appelle la commande echo).

Les catégories de string

Comme on a pu le voir plus haut, les strings s'organisent par pages et respectent l'architecture en cascade. Mais si vous souhaitez que quelques strings soient disponibles partout sur le site, il faut qu'elles soient dans une balise avec page qui a un name vide. Ce n'est pas pratique.

Certaines strings, qui sont réccurentes sur votre site, doivent pour être accessible partout sans pour autant devoir les mettre à la racine (au dossier dev).

C'est pour ça que les catégories de string existent. Ces strings, que l'on doit mettre non plus dans une balise page, mais dans une balise category.

Le parfait exemple d'une catégorie, c'est l'exemple du nom des groupes. Il existe un fichier groups.xml qui définit le nom des groupes pour chaque langue souhaitée.

Dans ce fichier groups.xml, on trouve non plus une balise page, mais une balise category. C'est catégorie a un attribut id pour pouvoir l'identifier d'un autre groupe.

Récupérer une string d'une catégorie

Pour récupérer une string dans la bonne langue, on peut utiliser la méthode string en renseignant le 3e paramètre de la méthode. La méthode wstr n'est pas utilisable pour les strings issues de catégories : car cette méthode ne fait qu'écrire le résultat de l'appel de la méthode string avec null en 3e paramètre.

Si l'on continue avec l'exemple de la catégorie groups, pour récupérer le groupe administrator, on appelle la méthode string :

echo $dsm -> string("administrator", null, "groups");

Utilisation du BBCode

Appliquer des styles à certaines parties de votre texte, comme mettre un mot en gras, un autre en italique, mettre un lien au milieu de votre texte, ne peut être fait en HTML dans vos phrases : en effet, vous écrivez vos strings dans une structure XML, y injecter des balises HTML briserait la structure de votre fichier XML et il serait illisible.

Pour palier ce problème, vous pouvez utiliser du BBCode. Il est intégré au framework et est très simple d'utilisation.

Le BBCode, comment ça s'écrit ?

Nous allons prendre un exemple simple : mettre en gras une partie de votre texte. Alors qu'habituellement dans une page HTML classique vous entourez de balises strong le mot que vous souhaitez mettre en gras, en BBCode, vous allez l'entourez de la balise b :

Ce mot est en [b]gras[/b]

Il existe beaucoup de balises prédéfinies, en voici la liste :

  • [b]Votre texte[/b] : la balise b est ensuite remplacé par la balise strong HTML
  • [i]Votre texte[/i] : la balise i est ensuite remplacé par la balise em HTML
  • [u]Votre texte[/u] : la balise u est ensuite remplacé par la balise u HTML
  • [url]http://myurl.com[/url] : la balise url est ensuite remplacé par la balise a HTML
  • [url=http://myurl.com]Votre texte de lien[/url] : la balise url est ensuite remplacé par la balise a HTML
  • [img]http://myurl.com/image.jpg[/img] : la balise img est ensuite remplacé par la balise img HTML
  • [img=Valeur de alt]http://myurl.com/image.jpg[/img] : la balise url est ensuite remplacé par la balise img HTML
  • [color=red]Votre texte[/color] : la balise color est ensuite remplacé par la balise span HTML avec l'attribut style qui définit la couleur
  • [color=#ff0000]Votre texte[/color] : la balise color est ensuite remplacé par la balise span HTML avec l'attribut style qui définit la couleur

Appliquer le BBCode

Maintenant que vous avez écrit du BBCode dans vos strings, vous remarquerez que lorsque vous les affichez avec string et wstr ça ne fonctionne pas.

C'est tout simplement que lorsque vous avez du BBCode dans votre string, il faut utiliser la méthode bbstring. Vous y mettez l'id de votre string, celle-ci est traitée pour convertir le BBCode en HTML et le résultat est retournée par la méthode.

echo $dsm -> bbstring('mon-texte');

Ca ne fonctionne pas

Oui, je ne vous ai pas tout dit, il faut tout d'abord initialiser la librairie jBBCode qui permet le traitement du BBCode. Cette dernière n'est pas initialisé par défaut par le DSM car cette initialisation prend en moyenne 30ms.

Pour initialiser la librairie jBBCode, il faut appeler la méthode initBBCode :

$dsm -> initBBCode();