====== Localisation d'un plugin ====== Cette page est destiné à la localisation d'un plugin, c'est à dire à la création d'un dossier locales puis d'un sous dossier par langue et enfin du fichier ''main.po'' qui contiendra la traduction dans une langue d'un plugin. ===== Guide d'utilisation des fichiers de localisation ===== ==== Mécanique générale ==== Chaque plugin contient du texte qui ne doit pas être inscrit en dur dans le code mais doit pouvoir être adapté pour toutes les langues. Pour ce faire, les fichiers avec l'extension "po" sont ajoutés. Ce sont ces fichiers qui, une fois interprétés par le moteur de dotclear2, vont remplacer, en façade de votre blog, les codes tels que par le mot ou la phrase associée dans la langue du blog. Pour ceci, il faut que le plugin dispose d'une traduction dans la langue souhaitée. Vous trouverez ci-dessous le détail des différents fichiers. ==== Organisation des fichiers ==== === Le dossier locales === Nommé **locales**, ce dossier accueille les dossiers contenant les langues vers lesquelles le plugin est traduit. Par exemple il peut contenir : * un dossier **fr** qui contiendra les fichiers pour la traduction en français * un dossier **en** qui lui sera pour la version anglaise (facultatif) * etc. ==== Le fichier main.po ==== Exemple de localisation : # French translation of DotClear # Copyright (C) 2006. # Olivier Meunier , 2006. # msgid "" msgstr "Content-Type: text/plain; charset=UTF-8\n" ... #: plugins/maintenance/index.php:74 #, php-format msgid "Indexing entry %d to %d." msgstr "Index des billets %d à %d" ... Les 3 premières lignes contiennent les commentaires du traducteur. * La langue de traduction, * La licence associée au fichier, * Le nom, le mail de l'auteur ainsi que la date de traduction du fichier. Décomposons ce code pour définir les fonctions de chaque ligne utilisée : msgid "" msgstr "Content-Type: text/plain; charset=UTF-8\n" Ces deux lignes permettent de définir le format du fichier ainsi que la méthode de codage des caractères. Ici, il est de type texte et utilise l'encodage UTF-8. (pour plus d'information sur les encodages : [[http://www.w3.org/International/O-HTTP-charset.fr.php|Site du W3C]]) #: plugins/maintenance/index.php:74 Cette ligne indique le fichier dans lequel est appelé la traduction et à quelle ligne elle est appelée. Si il y a plusieurs appels d'une même traduction, il suffit d'indiquer toutes les lignes comme dans l'exemple suivant : #: plugins/maintenance/index.php:87 plugins/maintenance/index.php:111 Si les appels sont nombreux, vous pouvez également utiliser une syntaxe qui tient sur plusieurs lignes, comme dans cet autre exemple : #: inc//core/class.dc.blog.php:1497 inc//core/class.dc.blog.php:1503 #: inc//core/class.dc.blog.php:1565 msgid "No such comment ID" msgstr "Identifiant du commentaire inconnu" Optionnellement, on peut indiquer que la traduction contient des variables PHP : #, php-format Dans notre cas, le %d est une variable PHP de type numérique. msgid "Indexing entry %d to %d." Notez que d'autres types de variables existent. Par exemple, pour passer une variable de type texte, il faut utiliser **%s** à la place de **%d**. Pour en savoir plus sur les types de variables et comment les utiliser, lisez [[http://fr.php.net/manual/en/function.sprintf.php|la documentation PHP sur la fonction sprintf]]. Le mot-clé **msgid** associe un identifiant unique à la traduction. Il est donc important de ne jamais donner deux traductions différentes au même identifiant. msgstr "Index des billets %d à %d" Enfin le mot-clé **msgstr** contient la traduction tant attendue. Si on regarde dans le fichier index.php comme indiqué, à la ligne 74... heu 77 ;-) echo '

'.sprintf(__('Indexing entry %d to %d.'),$start,$start+$limit).'

'; Voici donc l'appel de la traduction. À la place de "%d to %d", elle contiendra le contenu des variables **$start** et **$start+$limit**. Comme le montre cet exemple, le commentaire concernant la ligne associée à la traduction n'est plus correct, il semblerait que 3 lignes ont été ajoutées depuis au début du fichier index.php du plugin. Il est donc pertinent de mettre à jours son fichier de traduction quand on apporte des modifications aux fichiers qui contiennent des textes à traduire. À noter également : * Le mot-clé **msgid** ne peut se terminer par un espace, exemple "Ma chaine" sera trouvée et remplacée par sa traduction mais pas "Ma chaine " * Un script shell permettant de créer un squelette existe voir [[http://dev.dotclear.net/2.0/browser/QA/po_update.sh|po_update.sh]] * Un petit billet de Zeiram membre du forum existe aussi sur l'utilisation de gettext ([[http://mudry.org/blog/post/2006/12/31/342-traduction-d-un-plugin-dotclear2|voir ici]]) * L'existence d'un plugin de traduction [[http://lab.dotclear.org/wiki/plugin/translater|Translater]] ==== Le fichier public.po ==== Il s'écrit de la même manière que le fichier main.po et traduira les chaines qui apparaissent du côté public du blog. Ne pas oublier de rajouter **l10n::set(dirname(__FILE__).'/locales/'.$_lang.'/public');** dans le fichier **_public.php** du thème/plugin. * [[http://tips.dotaddict.org/fiche/Ajouter-des-traductions-dans-les-th%C3%A8mes|Ajouter des traductions dans les thèmes (Tips DotAddict)]] ===== Les exceptions de certains plugins ===== Certains plugins préfèrent utiliser les anciennes méthodes utilisées par Dotclear 1 ou encore faire un mélange des deux méthodes. Ces méthodes sont à proscrire donc nous ne ferons qu'effleurer le sujet. ==== Méthode Dotclear 1 ==== Peut être dans le but d'une adaptation rapide vers Dotclear2 tel que le plugin newsletter, === Le fichier main.lang.php === Même principe que pour Dotclear 2 sauf que tout est réuni en une ligne et qu'on ne sait pas quels sont les fichiers qui l'appellent. $GLOBALS['__l10n']['Newsletter'] = 'Lettre d\'informations'; Les fichiers ''*.lang.php'' sont traités plus rapidement que les fichiers ''*.po''. Il est possible de créer les traductions dans un fichier ''.po'' puis de générer un fichier ''.lang.php'' correspondant. ==== Méthode Dotclear 1 & 2 ==== Ils utilisent à la fois le fichier "main.po" et le fichier "main.lang.php" qui sont redondants tel que les plugins ThemeSwitcher, gallery, CSScompress, minialbum. Il faut savoir que c'est le fichier "main.lang.php" qui a la priorité sur le fichier "main.po". Si l'un des deux n'est pas présent Dotclear2 prend l'autre sinon il prend main.lang.php. ==== Sans traduction ==== Ou encore d'autres ne les utilisent pas. Cette méthode est à proscrire bien entendu.