Toujours vous annoncer avant de commencer à travailler (en créant un ticket ou en commentant un ticket existant). Ceci afin d’éviter que plusieurs personnes travaillent sur la même chose et entrent en conflit.
Le travail de documentation se fait sur la branche main.
Le code source de la documentation se trouve dans le dossier
support/documentation/content du dépot de code.
La documentation est générée via l’outils Hugo. Celui-ci doit être installé sur votre machine pour pouvoir prévisualiser la documentation.
Le thème utilisé est hugo-theme-learn. Il est recommandé d’en lire la documentation avant de commencer.
Quand une version du plugin est publiée, ou quand la documentation est mise
à jour, les mainteneur⋅euses du plugin fusionnerons la branche main dans
la branche documentation. Ce qui aura pour effet de déclencher les
pipelines github et gitlab pour mettre à jour les versions publiées.
La langue principale est l’anglais (code en).
Le dossier support/documentation/content/enne contient que les fichiers de
documentation en anglais.
La documentation est traduite en utilisant Weblate (voir la documentation sur la traduction). Pour cela, on utilise l’outils po4a, comme nous le verrons plus loin dans cette page.
Dans le fichier support/documentation/config.toml, inspirez vous de la
section [Languages.fr] pour déclarer la nouvelle langue.
Si les traductions ne sont pas complètes, ce n’est pas grave, la version anglaise sera utilisée pour les chaînes manquantes.
Pour prévisualiser vos modification, il suffit de lancer :
hugo serve -s support/documentation/
Puis d’ouvrir votre navigateur à l’adresse http://localhost:1313/peertube-plugin-livechat/. Cette page se raffraichira automatiquement à chaque modification.
Pour l’instant, vous n’avez que la version anglaise. Pour mettre à jour les
chaînes et générer les traductions, vous devez lancer le script
doc-translate.sh.
Pour cela, assurez vous d’avoir po4a (version >= 0.69) installé sur votre ordinateur.
Certaines distributions linux (comme Debian Bullseye par exemple) ont une
version trop ancienne de po4a. Veillez à installer une version
compatible. Si vous utilisez Debian Bullseye par exemple, vous pouvez
télécharger le fichier Bookworm po4a.deb depuis
https://packages.debian.org,
et l’installer manuellement.
Pour gérer les traductions, il suffit de faire :
npm run doc:translate
Vous pouvez ensuite prévisualiser le résultat en utilisant hugo serve -s support/documentation/, et en utilisant le sélecteur de langue.
Éditez seulement les fichiers anglais dans
support/documentation/content/en.
Ensuite, avant de commiter, lancez toujours npm run doc:translate, afin
que les changements dans les fichiers anglais puissent être propagés dans le
fichier support/documentation/po/livechat.en.pot.
Vous pouvez utiliser le code court livechat_label pour utiliser des
chaînes de l’application. Voir ici : Traduction de la
documentation.
Il est possible d’empêcher un fichier d’être traduit, en utilisant
livechatnotranslation : true dans la section Yaml Font Matter. Voir ici :
Traduction de la
documentation.
Veuillez utiliser l’option livechatnotranslation pour la documentation
technique. Nous ne voulons pas traduire la documentation technique, afin
d’éviter les problèmes liés à une mauvaise traduction.
Pour faciliter le travail des traducteur⋅rices, évitez de faire des paragraphes trop longs.
Pour l’instant il n’est pas possible d’utiliser des tableaux Markdown : les outils de translation ne savent pas les gérer.
Il peut y avoir des liens vers la documentation ailleurs sur le web. Essayez de ne pas changer les urls des pages de documentation. Ou au moins, mettez des liens vers les nouvelles pages dans les anciennes urls.
Il suffit d’éditer les fichiers markdown en anglais, et de spécifier que vous ne pouvez pas compiler les traductions lorsque vous faites votre Pull Request.
La publication de la documentation est automatique, dès que les
modifications sont fusionnées dans la branche documentation.