Open Time

Avant d’aller plus loin — oui, je sais, on a pas fait grand chose pour l’instant — on va parler un peu d’organisation et plus particulièrement ce que j’utilise comme sous-répertoires pour le plugin et ce que je mets dedans.

On a vu dernièrement que j’utilise le sous-répertoire lib pour le code tiers, dans notre cas la bibliothèque accessConfig d’Access42. D’autres répertoires viendront s’ajouter au fur et à mesure du développement :

• js : c’est ici que je mets tout les codes javascripts qui seront utilisés à un moment ou à un autre.
• css : comme son nom l’indique, les feuilles de style, si besoin, viendront là, éventuellement avec un sous-répertoire fonts, voire img (pour les images utilisées par les feuilles de style) ; mais je ne crois pas avoir déjà développé un plugin qui utilise ces sous-répertoires.
• inc : ici je placerai les classes PHP utilisées ; en particulier tout ce qui concerne les behaviors (comportements) publiques et d’administration — on y reviendra le moment venu. J’y place aussi la gestion des données enregistrées en base de données quand c’est le cas, et encore le code qui gère les balises template.
• locales : contiendra les traductions ; on va voir juste après ce qu’il contient et comment le mettre à jour.
• img : parfois utile quand on a des images supplémentaires.

Tous ces noms sont indicatifs, mais les utiliser permet de conserver un semblant de cohérence d’un plugin à l’autre.

Bien évidemment vous êtes tout à fait libre d’utiliser cette organisation, ou bien de tout mettre au niveau principal du plugin — ce que je fais parfois pour des plugins ultra simples. À vous de voir ce qui vous paraît le plus facile à utiliser.

Revenons à la gestion des traductions.

Un outil est mis à disposition pour générer ou mettre à jour les traductions d’un plugin (ou d’un thème). Cet outil, qui s’utilise en ligne de commande, se trouve dans le dossier build-tools de votre installation Dotclear.

Ensuite, pour préparer les premières traductions en français — je rappelle que par défaut les libellés doivent être en anglais dans le code —, je lance la commande suivante, en considérant que je me trouve à la racine du dossier Dotclear :

./build-tools/po_update.sh fr ../plugins/a11yConfig

La première fois que je vais lancer cette commande, l’outil va créer automatiquement l’arborescence suivante dans le répertoire principal du plugin :

• répertoire locales : dossier des traductions
  • sous-répertoire _pot : dossier modèle de traduction (utilisé ensuite pour les mises à jour)
  • sous-répertoire fr : dossier des traductions françaises

Pour notre plugin, lorsque j’ai lancé cette commande, l’outil a émis quelques messages d’erreur, sans aucune gravité, simplement parce qu’aucun libellé pouvant être traduit n’a été reconnu comme tel dans les fichiers PHP et HTML de notre plugin.

Les libellés qui seront reconnus sont ceux, dans le code PHP, écrits sous la forme __('label') (voire sous la forme __('label-singular', 'label-plural', n) pour la gestion des pluriels^[1]), tandis que dans les fichiers HTML, ce sont les balises template {{tpl:lang …}}.

Comme je souhaite offrir une description en français de mon plugin, j’ai modifié le fichier _define.php comme suit (voir les lignes 17 et 18) :

<?php
/**
 * @brief a11yConfig, a plugin for Dotclear 2
 *
 * @package Dotclear
 * @subpackage Plugins
 *
 * @author Franck Paul, Biou and contributors
 *
 * @copyright Franck Paul carnet.franck.paul@gmail.com
 * @copyright GPL-2.0 https://www.gnu.org/licenses/gpl-2.0.html
 */

if (!defined('DC_RC_PATH')) {return;}

$this->registerModule(
    __("a11yConfig"),                                           // Name
    __("Implements Access42 accessibility configuration tool"), // Description
    "Franck Paul, Biou and contributors",                       // Author
    '1.0',                                                      // Version
    [
        'requires'    => [['core', '2.15']],
        'permissions' => 'admin',                                     // Permissions
        'type'        => 'plugin',                                    // Type
        'support'     => 'https://github.com/franck-paul/a11yConfig', // Support URL
        'settings'    => ['pref' => '#user-options.a11yConfig']      // Settings
    ]
);

Puis j’ai relancé l’outil de gestion des traductions :

./build-tools/po_update.sh fr ../plugins/a11yConfig

Cette fois-ci, plus d’erreurs vu qu’il a trouvé au moins un libellé à traduire à se mettre sous la dent et quelques nouveaux fichiers sont apparus dans l’arborescence :

• locales/_pot/main.pot : on peut ignorer ce fichier, il est simplement utilisé à des fins internes
• locales/fr/main.po : qui contient les traductions française.

Le 2e fichier est créé comme tel :

# SOME DESCRIPTIVE TITLE.
# This file is put in the public domain.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: Dotclear 2 a11yConfig module\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2019-11-12 10:30+0100\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

msgid "a11yConfig"
msgstr ""

msgid "Implements Access42 accessibility configuration tool"
msgstr ""

Que je modifie (ligne 23) ensuite pour insérer la traduction française de la description du plugin :

…
msgid "Implements Access42 accessibility configuration tool"
msgstr "Implémente l'outil de configuration de l'accessibilité d'Access42"

Vous noterez que j’ai laissé inchangé la traduction du nom du plugin, pas utile en français, c’est assez compréhensible comme ça. Dans ce cas, Dotclear utilisera la version anglaise du libellé (ce qui est vrai pour tous les libellés non traduits dans une langue ou une autre).

Nota : si vous souhaitez ajouter une autre langue, changez simplement le fr par le code de la langue correspondante (2e paramètre) dans la ligne de commande de génération des traductions. Par exemple, pour l’espagnol :

./build-tools/po_update.sh es ../plugins/a11yConfig

Notez également que vous pouvez lancer autant de fois que vous voulez cet outil, il n’écrasera pas ce que vous avez déjà traduit.

Un petit tour du côté de la gestion des plugins, en imaginant que la langue réglée chez vous soit en français, et voilà, la description est dorénavant affichée en français (vous pouvez basculer votre interface en anglais et revenir vérifier que vous avez maintenant la description en anglais) :

Nous voilà maintenant prêt à rentrer dans le vif du sujet, mais ça sera pour la prochaine fois. Pour l’instant, il s’agit d’enregistrer toutes les modifications et ajouts effectuées aujourd’hui dans notre dépôt.