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
Clonage du dépôt Git www-fr et création d'une branche
Prérequis : git, un compte sur Savannah (projet www-fr).
Le dépôt www-fr comprend plusieurs branches :
- master, que l'on ne peut pas supprimer ni modifier ; elle contient les fichiers .fr.po et le « GNUmakefile » qui permet de synchroniser les arborescences www-fr et www dans les deux sens (make sync et make publish), et de voir l'état des traductions (make report) ; elle est en principe synchronisée avec www après envoi des mises à jour dans le dépôt CVS de www.
- une ou plusieurs branches perso qui contiennent les dernières modifications faites par les traducteurs.
- scripts, qui contient :
- batch-transvalidate, pour convertir les POs en page HTML, et vérifier que leur format est correct et que le HTML est conforme aux standards du W3C.
- mini-www-checkout et micro-www-checkout, pour créer un répertoire www réduit, ne contenant que les fichiers nécessaires à la régénération de pages traduites en français.
- pot2pad et pad2po, pour faciliter le passage du format PO au pad de traduction et inversement.
Ne pas hésiter à modifier ces scripts, à les critiquer ou à en créer de nouveaux. Ils sont là pour ça. ;-)
1. Clonage de www-fr
Créer le répertoire de travail (GNU/ par exemple) qui contiendra aussi www, et s'y placer :
mkdir -p ~/GNU && cd ~/GNU
Ensuite, on a le choix de cloner le dépôt complet ou seulement certaines branches.
- Clonage du dépôt complet
git clone ID-SUR-SAVANNAH@git.sv.gnu.org:/srv/git/www-fr.git
- Clonage séparé des branches master et scripts (voir http://www.kernel.org/pub/software/scm/git/docs/git-remote.html). Cela évite de traîner l'historique de www-fr avec les scripts, et inversement. Mais surtout, cela permet d'utiliser les scripts avec les fichiers PO sans avoir à les copier ailleurs. En effet, il est impossible d'accéder en même temps à deux branches d'un même dépôt local qui n'ont aucun fichier en commun. Les scripts peuvent être n'importe où ; en revanche, le répertoire www-fr doit avoir la même racine que www.
mkdir -p ~/GNU/www-fr && cd ~/GNU/www-fr git init git remote add -f -t master -m master origin ID-SUR-SAVANNAH@git.sv.gnu.org:/srv/git/www-fr.git git merge origin
La branche créée localement s'appelle master par défaut. Lorsqu'on clone uniquement la branche scripts, la branche master créée à cette occasion ne correspond pas à la branche master du dépôt distant. Il faut la renommer si l'on veut ensuite pousser les modifications locales. Autrement, on a une erreur assez énigmatique : « error: src refspec scripts does not match any. »
mkdir -p ~/www-fr-scripts && cd ~/www-fr-scripts git init git remote add -f -t scripts -m scripts origin ID-SUR-SAVANNAH@git.sv.gnu.org:/srv/git/www-fr.git git merge origin git branch -m master scripts
2. Création d'une branche personnelle
É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 « @ ») :
~/GNU/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
Remarque : on peut demander à Git d'ignorer certains fichiers en créant un fichier .gitignore global (dans $HOME), ou en utilisant le fichier .git/info/exclude de chacun des dépôts locaux. L'exclusion des fichiers .html est nécessaire si l'on se sert de batch-transvalidate, qui sauvegarde les pages web traduites dans www-fr. Par exemple, le fichier exclude de www-fr pourrait contenir :
*~ *.html *.txt
Installation d'une arborescence www locale
Le type d'arborescence à créer dépend de ce que l'on veut en faire.
1. Installation minimum pour utiliser batch-transvalidate
Les fichiers strictement nécessaires à batch-transvalidate sont téléchargés par micro-www-checkout. C'est la méthode recommandée avec un SSD (disque à mémoire flash). Il est en effet très mauvais pour ce type de disque de modifier fréquemment des centaines de fichiers, ce qui arrive si l'on synchronise une arborescence www complète avec le dépôt CVS.
L'inconvénient de sélectionner les fichiers à télécharger est que pour chaque nouveau fichier traduit on doit faire un « cvs checkout » sur le HTML original, le POT et le PO (après envoi dans le dépôt CVS), de manière à pouvoir les mettre à jour par la suite. Mais cela n'arrive pas tous les jours.
Prérequis : cvs, rsync.
cd ~/www-fr-scripts ./micro-www-checkout -l fr
2. Installation minimum pour utiliser GNUN
Si la conversion des POs et la validation HTML doivent être faites par GNUN, il faut télécharger quelques autres fichiers ; on peut utiliser mini-www-checkout (même méthode que ci-dessus).
3. Installation complète
Pour avoir une image complète du site web (plus de 450 Mo), il faut passer par la méthode traditionnelle :
Prérequis : cvs.
mkdir -p $HOME/GNU && cd $HOME/GNU cvs -z3 -d:pserver:anonymous@cvs.savannah.gnu.org:/webcvs/www co www
Installation de GNUN (optionnelle)
Prérequis :
- une arborescence www complète, ou bien créée par mini-www-checkout ;
- make, gawk ;
- 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 Debian w3c-dtd-xhtml).
Télécharger le paquet gnun-latest (ou gnun-0.7) par exemple dans $HOME, et l'extraire. On obtient le dossier gnun-0.7 :
wget ftp://ftp.gnu.org/gnu/gnun/gnun-latest tar xzvf gnun-latest.tar.gz
Se placer dans le dossier gnun-0.7 et préparer l'installation :
cd ~/gnun-0.7 ./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 's/bug-gnun@gnu.org/adresse@bidon.fr/' gnun.conf
Maintenant, on peut installer GNUnited Nations dans ~/GNU/www/server/gnun :
sudo make install
Enfin, il faut 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/
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
- Remarque 1. La connexion au dépôt CVS de Savannah est quelquefois très lente et très irrégulière. Avec une arborescence www réduite (voir plus haut), il peut arriver que la synchronisation prenne 10 ou 20 minutes – ne parlons pas de l'arborescence complète. 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 (ne pas oublier de se placer sur la branche adéquate) :
cd ~/GNU/www-fr git checkout gt 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 (ne pas oublier de se placer sur la branche adéquate)
cd ~/GNU/www-fr git checkout gt 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
2 méthodes possibles : batch-transvalidate et GNUN.
1. batch-transvalidate
C'est un script interactif – trop, disent certains ;-) – qui peut être utilisé avec un fichier de configuration ou des options en ligne de commande. Il permet de valider une liste de POs créée de diverses manières (entre autres par Git) et éditable. Une fois validés, les POs peuvent être commités dans le dépôt Git local. Les pages traduites sont enregistrées dans www-fr, mais on fait en sorte que Git les ignore (voir plus haut). L'arborescence www n'est pas modifiée.
Prérequis :
- po4a (qui dépend de gettext, perl, etc.),
- xmllint (paquet Debian libxml2-utils),
- DTD XHTML 1.0 du W3C (paquet Debian w3c-dtd-xhtml),
- html5.dtd de gnun (dans le même répertoire que batch-transvalidate).
Si le script est dans le répertoire www-fr-script :
cd ~/www-fr-scripts ./batch-transvalidate
2. GNUN
- 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.
