Gestion des traductions

La gestion des langues est le point délicat de UP.

Les besoins et contraintes sont:

1. respecter la règle n°1 de UP: tous les fichiers concernant une action sont dans le dossier de l'action.
   L'ajout du dossier installe l'action, sa suppression la supprime.
2. permettre la saisie des mots clés (actions et options) dans plusieurs langues. Exemple: largeur pour width, table-par-ligne pour table_by_rows
3. afficher les textes internes aux scripts actions. Exemple, le message: action non trouvée
4. afficher la documentation dans la langue de l'utilisateur
5. afficher la valeur des options dans la bonne langue. Exemple: readmore=lire la suite

Les solutions retenues sont:

1. création optionnelle d'un sous-dossier "up" dans le dossier de l'action
2. à l'aide d'un fichier dico.json en racine, consolidé par les fichiers dico.json du dossier "up" des actions
3. on utilise un mécanisme similaire à JText : $this->trad('texte à traduire')
4. sans doc spécifique à la langue dans le sous-dossier up, les infos sont lues dans le script action
5. une méthode est mise à disposition des rédacteurs. readmore=lang[en=readmore; fr=lire la suite]

1 - Les fichiers impliqués

Pour respecter la règle n°1, il est impossible d'utiliser le mécanisme de Joomla qui implique une installation ou une découverte.

La méthode retenue est l'ajout optionnel d'un dossier "up" dans le dossier de l'action. Ce dossier contient :

• dico.ini les équivalences pour le nom de l'action et les noms d'options.
• xx-XX.ini (exemple: en-GB.ini) la traduction pour la documentation, l'explication des options et les textes à traduire pour le script

2 - Le nom des actions et des options

Le but: permettre à un rédacteur de saisir les mots-clés dans sa langue

Le mécanisme retenu est un fichier dico.json en racine du plugin.
Il est indispensable que ce fichier soit global pour UP, car il serit impossible de lire un dossier dont le nom n'est pas encore connu
Ce fichier contient une liste: "expression de substitution" : "expression utilisée par UP"

Lors de la lecture des options par le script principal de UP, cette liste est consultée. Si le nom d'une option y figure, c'est le nom utilisé qui sera transmis au script action.

Exemple: {up table_par_ligne | hauteur=250px} sera compris et utilisé par le script action comme {up table_by_rows | height=250px}

Le fichier principal dico.json est construit à partir d'un fichier de base (/plugins/content/up/dico.ini) et des fichiers dico.ini dans les sous-dossiers "up" des actions. Il suffit de créer un article avec le shortcode {up upactionslist | make-dico} pour que ce fichier soit recréé.

Les équivalences sont indiquées dans la documentation automatique des actions

3 - Les textes internes aux scripts des actions

Il s'agit par exemple des messages d'erreurs. Cela peut être pris en charge par les méthodes JText de Joomla avec l'inconvénient d'avoir à gérer des fichiers externes au dossier de l'action.

La méthode envisagée est d'avoir dans le dossier language, des fichiers xx-XX.ini avec les termes principaux (définis et utilisés par la classe parente des actions) et dans le sous-dossier up de l'action, des fichiers xx-XX.ini pour les termes définis par l'action.

La syntaxe serait $this->trad_keyword('mot-clé') pour une recherche dans les fichiers xx-XX.ini (Up et action courante). Si non trouvé, on retourne le mot-clé.

ou $this->trad_argument('fr=lire la suite; en=readmore') pour récupérer le texte dans la langue de l'utilisateur. Si les langues indiquées ne correspondent pas à l'utilisateur, on retourne le "en" ou à défaut le premier.

4 - La documentation des actions

Lors d'une demande d'infos par l'option ? dans un shortcode, ou le shortcode {up upActionsList}.

Il est impératif que l'utilisateur dispose d'une documentation. Si elle n'existe pas, les informations sont récupérées dans le script action.

Les besoins

nom de l'action (le nom du dossier) et les substitutions possibles. Exemple: table_by_rows (table-par-lignes)

le nom de l'action est le nom du dossier et les substitutions sont récupérés dans le fichier dico.json

une description courte dans la langue utilisateur

On utilise dans l'ordre: 

1. la clé "doc_description" du fichier xx-XX.ini
2. la première ligne de l'entête du script

une description détaillée dans la langue utilisateur

On utilise dans l'ordre: 

1. la clé "doc_main" du fichier xx-XX.ini
2. l'entête du script (de la 2ème ligne aux tags (@author, ...)

les tags @author, @version, @licence, @credit

Ils sont repris et jamais traduits dans le script action

la liste des options avec les substitutions possibles et l'explication dans la langue de l'utilisateur

La liste des options est toujours récupérée dans le script pour s'assurer qu'elle est complète.
Chaque ligne est construite à partir des éléments suivants: 

1. le nom de l'option pour le script. ex: width
2. les substitutions possibles lues dans dico.json. ex: largeur, l, larg
3. l'explication disponible dans le fichier xx-XX.ini de l'action ou à défaut celle dans le script

5 - Les valeurs des options

Il s'agit du texte saisi par le rédacteur. Exemple: {up readmore=lire la suite}

C'est moins utile, car le shortcode peut être adapté lors de la traduction de l'article.
Toutefois comme le mécanisme existe pour les textes internes aux scripts (point 3), il est étendu aux shortcodes.

Le rédacteur de l'article peut définir les images selon la langue, ce qui serait plus délicat pour un traducteur ou totalement impossible pour une traduction automatique comme multitrans.

v1.7

L'action lang profite de la possibilité d'avoir des shortcodes comme argument d'autres shortcodes. Cela évite d'avoir à apprendre une autre méthode !

{up readmore={up lang | en=readmore | fr=lire la suite}} contenu {/up readmore}

Attention, cette méthode est utilisable uniquement lors de la saisie d'un shortcode dans un article ou module. Pour les prefsets, utilisez l'ancienne méthode.

avant la version 1.7

Cette possibilité est toujours disponible pour toutes les options. L'option width=lang[fr=150px;en=200px] est valide.

Solution retenue

Saisir readmore=lang[en=readmore; fr=lire la suite] ou readmore=lang[en=image-en.jpg; fr=image-fr.jpg]

Avantage:

• la traduction est gérée totalement par le rédacteur au moment de la saisie du shortcode. Il n'est pas nécessaire de modifier d'autres fichiers
• seul le contenu dans la langue visiteur est transmis au script action
• si la langue visiteur est inconnue, on utilise la version anglaise (en) et à défaut la première alternative proposée.

Inconvénients:

• syntaxe à mémoriser et à respecter par le rédacteur
• impossibilité d'utiliser le point-virgule dans les textes

Note: la version avec mot-clé et fichiers language a peu d'intérêt dans le shortcode car elle obligerait les rédacteurs à les connaître et les modifier.