Outils de traduction - 2e partie
Cette page est une annexe du Manuel du traducteur du projet GNU.
Introduction
Le site gnu.org contient des centaines de pages dont certaines sont traduites en 25 langues. Beaucoup d'entre elles sont fréquemment remaniées, les traductions doivent donc être mises à jour. Pour faciliter cette opération, les développeurs de gnu.org ont écrit un ensemble de scripts connu sous le nom de GNUnited Nations (GNUN), qui fait appel à plusieurs autres programmes. La maintenance des fichiers se fait à l'aide de systèmes de contrôle de version : CVS pour le site lui-même (dépôt www) et Git pour les traductions en français (dépôt www-fr).
Le circuit de mise à jour des traductions est résumé par le schéma suivant, adapté du manuel de GNUN :
+-------------+ +---------------+
| Dépôt | | Dépôt |
| officiel | | officiel |
| www (CVS) | | www-fr (Git) |
+-------------+ +---------------+
| ^ | ^
M1 | | C2 M3 | | M5
V | V |
+-------------+ +---------------+
| Dépôts | M2 | Dépôts | M4
| locaux |---->---->----| locaux |<------.
| www (CVS) | | www-fr (Git) | |
+-------------+ +---------------+ |
^ | | |
| C1 | | |
'---<----<---Coordinateur---' '---Membres---'
M1 = cvs update C1 = make publish
M2 = make sync C2 = cvs commit
M3 = git pull
M4 = git commit
M5 = git push
Le travail se fait dans des copies locales de www et www-fr. Il comporte cinq étapes :
- synchroniser les copies locales de www et www-fr avec les dépôts officiels correspondants [voir schéma : M1 et M3] ;
- synchroniser www-fr avec www localement et déterminer quels fichiers PO ont besoin d'une mise à jour [M2] ;
- mettre à jour ces fichiers ;
- les valider ;
- les enregistrer dans le dépôt www-fr local [M4] et les envoyer dans le dépôt www-fr officiel [M5] (cette dernière étape demande d'avoir un compte sur Savannah - voir la Charte de trad-gnu).
Par la suite, les fichiers mis à jour seront envoyés dans le dépôt www de Savannah par le coordinateur du groupe [C1 et C2], et moins d'une heure plus tard GNUN régénèrera les pages traduites.
Le circuit des nouvelles traductions et des révisions est le même, à part que la synchronisation des dépôts n'est pas nécessaire puisque l'initiative appartient à l'équipe de traduction.
Sources d'information et de formation
- Le manuel de GNUN décrit le principe de la génération des pages traduites et détaille chaque fonction de GNUN. Ce que GNUN permet de faire, entre autres :
- valider les fichiers PO ;
- transformer les fichiers PO en pages HTML (avec le style par défaut), ce qui facilite grandement la relecture ;
- voir quelles traductions ont besoin d'une mise à jour.
- Git est ce qui risque le plus de dérouter les débutants, mais avec l'aide attentionnée et la supervision de notre coordinateur il suffit d'une semaine ou deux pour s'y mettre, foi de Mme Michu. L'essentiel de ce qu'il y a à savoir se trouve dans les trois premiers chapitres du Git Book. S'il y a un problème, quelques mots-clés dans un moteur de recherche ou un appel au secours sur la liste font merveille. Pas de panique, les erreurs sont la plupart du temps rattrapables.
Et devinez quoi... Git a des interfaces graphiques :
- Git GUI (multiplateforme) permet de faire une bonne partie des opérations. Il est couplé avec gitk.
- gitk visualise l'historique des branches, montre les différences entre fichiers et permet de faire des recherches dans l'arborescence.
Mise en place des outils
Installation de GNUN dans une arborescence www locale
GNUN a été conçu pour le site web de gnu.org et a besoin de l'arborescence de www.gnu.org pour fonctionner. Pour l'utiliser en local, il faut donc recréer cette arborescence. Cela se fait avec cvs.
GNUN s'installe dans le dossier utilisateur. L'installation complète occupe pas loin de 500 Mo (plus de 19 000 éléments !). Il est toutefois possible de l'élaguer (voir plus loin).
Prérequis :
- cvs
- make, autoconf, autotools
- texinfo, gettext
- po4a (pour la conversion HTML <--> PO)
- pour la validation des pages HTML : libxml2, libxml2-utils et la DTD XHTML 1.0 du W3C (paquet w3c-dtd-xhtml d'Ubuntu)
- gawk
1. Installation complète
Créer un répertoire, GNU par exemple, et se placer dans celui-ci :
$ mkdir GNU $ cd GNU
Récupérer tous les fichiers du site web de gnu.org dans un sous-repertoire www :
$ cvs -z3 -d:pserver:anonymous@cvs.savannah.gnu.org:/webcvs/www co www
Récupérer les sources de GNUN :
$ cvs -d :pserver:anonymous@cvs.sv.gnu.org:/sources/trans-coord \
checkout trans-coord/gnun/server/gnun
Préparer l'installation :
$ cd trans-coord/gnun/server/gnun $ autoreconf -i $ ./configure $ make
Il faut éditer le fichier gnun.conf pour remplacer les adresses de courriel, afin que les tests ne soient pas envoyés aux webmasters GNU ;-)
$ sed -i -e 's/bug-gnun@gnu.org/adresse@bidon.fr' gnun.conf
Maintenant, on peut installer GNUnited Nations dans ~/GNU/www/server/gnun :
$ sudo make install
Et finalement copier config.mk et GNUmakefile dans le répertoire www/server/gnun :
$ cp GNUmakefile ~/GNU/www/server/gnun/ $ cp config.mk ~/GNU/www/server/gnun/
2. Installation partielle
Pour les personnes qui utilisent un SSD (mémoire flash), l'installation précédente est un véritable gâchis. Ce n'est pas la place occupée en mémoire ni le temps de téléchargement qui est le plus gênant, c'est que chaque mise à jour fait vieillir le SSD pour rien car on modifie beaucoup de fichiers qui n'ont rien à voir avec nos traductions. Pour pallier cet inconvénient, il est possible de télécharger uniquement les fichiers nécessaires à la mise à jour de nos fichiers PO, à leur validation et à la régénération des pages traduites. Cela peut se faire au coup par coup. Les fichiers à télécharger sont :
- DOSSIER/po/ARTICLE.po, DOSSIER/po/ARTICLE.pot, DOSSIER/po/ARTICLE.translist et DOSSIER/ARTICLE.html ;
- DOSSIER/ARTICLE.fr.html (pas indispensable mais souvent utile) ;
- dans server/gnun/ : gnun.mk, languages.txt (juste pour faire plaisir à GNUN), translinks*.html et translinks*.fr.html (config.mk et GNUmakefile seront ajoutés au cours de l'installation de GNUN) ;
- les « includes » qui se trouvent dans server/ : banner.html, body-include-1.html, body-include-2.html, bottom-notes.html, footer-text.html, footer.html, head-include-1.html, head-include-2.html, header.html et top-addendum.html ;
- les traductions des includes ci-dessus : server/*.fr.html ;
- philosophy/philosophy-menu.html et .fr.html ;
- planetfeeds.fr.html (indispensable pour régénérer home.fr.html) ;
- software/allgnupkgs.html (pour régénérer software.fr.html).
Remarque 1 : server/gnun/ contient d'autres fichiers qui ne nous sont pas indispensables.
Remarque 2 : dans server/ il y a d'autres includes qui ne nous sont pas indispensables (footer-min*, footer-short*, html5*, outdated* et skip-translations*), ainsi que des pages web ordinaires (*whatsnew*, sitemap*, takeaction* et tasks*).
Remarque 3 : il devrait être possible d'alléger la liste ci-dessus. Il faudrait pour cela simplifier server/gnun/GNUmakefile. Qui veut s'y coller ?
Pour que GNUN ne rouspète pas trop, il faut lui faire croire que les seules traductions existantes sont les nôtres. C'est tout simple, il suffit de faire disparaître tous les codes de langue, sauf « fr », aux lignes 21 et 26 de server/gnun/gnun.mk ; ce qui donne :
[...] TEMPLATE_LINGUAS := fr [...] FUZZY_DIFF_LINGUAS := fr [...]
Après élagage, l'arborescence www ne contient plus que ~2280 éléments (fichiers et dossiers) et occupe moins de 27 Mo. La récupération des sources de GNUN et l'installation sont les mêmes que plus haut.
Clonage du dépôt Git www-fr et création d'une branche
Créer le répertoire www-fr dans le répertoire courant :
$ cd ~/GNU $ git clone ID-SUR-SAVANNAH@git.sv.gnu.org:/srv/git/www-fr.git
Écrire dans ~/.gitconfig l'identité de celui/celle qui fait les commits. Sans l'option --global, l'information est écrite dans le fichier .git/config (l'adresse de courriel n'a pas besoin d'être valide, il faut seulement qu'elle contienne « @ ») :
$ cd www-fr $ git config --global user.name "Gribouille Tartempion" $ git config --global user.email gtartempion@serveur.mail
La commande ci-dessous va faciliter le travail à plusieurs :
$ git config branch.autosetuprebase remote
Créer une branche « gt » synchronisée avec la branche master, et l'envoyer sur le serveur :
$ cd ~/GNU/www-fr $ git branch --set-upstream gt origin/master $ git push origin gt
Synchroniser la branche gt avec origin/master. Les modifs qui sont sur gt mais pas sur master s'ajouteront en tête de branche grâce à l'option « autosetuprebase » :
$ git checkout gt $ git pull
Les cinq étapes d'une mise à jour
Synchronisation des dépôts locaux avec le dépôt www de Savannah
1. Synchroniser l'arborescence www locale avec le dépôt CVS de www :
$ cd ~/GNU/www $ cvs update -d
- Remarque 1. La connexion au dépôt CVS de Savannah est quelquefois très lente et très irrégulière ; il est arrivé que la synchronisation de www prenne une demi-heure au lieu de moins d'une minute normalement. On peut alors utiliser une solution de repli plus rapide : s'abonner à la liste de diffusion www.commits@gnu.org pour être informé en temps réel des modifications des pages web et synchroniser uniquement les fichiers correspondants :
$ cd ~/GNU/www $ cvs update SECTION/po/DOCUMENT.fr.po SECTION/po/DOCUMENT.pot SECTION/DOCUMENT.html
- Remarque 2. La synchronisation ne se fait bien (c'est-à-dire sans « conflit pendant la fusion ») que si les fichiers n'ont pas été modifiés localement. Si pour une raison quelconque ils l'ont été (à l'étape de validation par exemple), on peut supprimer les changements globalement :
$ cd ~/GNU/www $ cvs diff | patch -R -p0
Ou bien, si la connexion est mauvaise, on peut restreindre l'opération à un dossier particulier :
$ cd ~/GNU/www/DOSSIER $ cvs diff | patch -R -p0
2. Synchroniser localement www-fr avec www en utilisant GNUN :
$ cd ~/GNU/www-fr $ make sync
Inventaire des PO à mettre à jour
2 méthodes :
- À partir de l'arborescence www
$ cd ~/GNU/www/server/gnun $ make report TEAM=fr
- À partir du dépôt local www-fr
$ cd ~/GNU/www-fr $ make report
Mise à jour des PO
Il est préférable de mettre les fichiers à jour dans www-fr, et de faire ensuite la validation sur une copie dans www (voir plus loin pourquoi).
La mise à jour peut se faire dans un éditeur de PO ou un éditeur de texte ordinaire (voir Outils de traduction 1e partie).
Validation des PO / Génération des pages HTML
- On met le fichier à valider DOCUMENT.fr.po dans le dossier ~/GNU/www/SECTION/po/. C'est faisable avec
make publish, mais alors tous les PO de www-fr seront reformatés et copiés dans www, même ceux qui ne sont pas encore prêts à être validés.
- On se place dans le répertoire ~/GNU/www/server/gnun, et on demande à générer la page :
$ cd ~/GNU/www/server/gnun $ make VALIDATE=yes ../../SECTION/DOCUMENT.fr.html
Et voilà, make dit s'il y a une erreur. On peut modifier ../../SECTION/po/DOCUMENT.fr.po et régénérer la page HTML, qu'on récupère dans ~/GNU/www/SECTION/.
Remarque. Il arrive fréquemment que le fichier POT soit régénéré au cours de la validation (voir le manuel de GNUN). Cela modifie également le fichier PO (ainsi que des fichiers intermédiaires) et perturbe les synchronisations ultérieures. Il est possible de supprimer les changements comme expliqué plus haut, mais il faut évidemment que le PO mis à jour soit sauvegardé ailleurs. Il est donc recommandé de faire les mises à jour dans www-fr et de ne valider qu'une copie. De même, la page DOCUMENT.fr.html régénérée doit être sauvegardée si l'on veut s'en servir pour la relecture.
Envoi dans le dépôt www-fr
- Ajouter des modifications ou de nouveaux fichiers à la branche gt (indexation) :
$ git checkout gt $ git add fichier1 fichier2 ...
- Enregistrer (commiter) les modifications dans le dépôt local (branche gt) :
$ git commit fichier1 fichier2 ...
Les commits peuvent être regroupés logiquement, par exemple modifications d'un même type sur plusieurs fichiers.
- Envoyer (pousser) les modifications sur le serveur :
$ git push origin gt
- Faire la liste des fichiers modifiés entre deux envois dans le dépôt www. Comme les modifs de gt ne sont ajoutées à master qu'une fois envoyées dans www, il suffit de faire la liste des fichiers qui diffèrent entre les deux branches :
$ git diff --name-only gt..master
- Prévenir sur la liste trad-gnu qu'il y a des fichiers à envoyer, en en donnant la liste et en les classant : mises à jour, relectures, nouvelles traductions, etc.
