po4a

Autres langues

Langue: fr

Version: 2008-11-05 (ubuntu - 07/07/09)

Autres sections - même nom

Section: 7 (Divers)

NOM

po4a - Cadre de travail pour la traduction de documentations et autres documents

Introduction

L'objectif du projet po4a [po for anything --- po pour tout] est de simplifier la traduction (et de faA~Xon plus intA~Xressante, la maintenance des traductions) en utilisant les outils gettext dans des domaines pour lesquels ils n'A~Xtaient pas destinA~Xs, comme la documentation.

Table des matiA~Xres

Ce document est organisA~X de la maniA~Xre suivante :
1 Pourquoi utiliser po4a ? A~X quoi cela sert-il ?
Cette section d'introduction explique les motivations du projet et sa philosophie. Vous devriez le lire si vous cherchez A~  A~Xvaluer po4a pour vos traductions.
2 Comment utiliser les fonctionnalitA~Xs de po4a ?
Cette section est une sorte de manuel de rA~XfA~Xrence qui cherche A~  rA~Xpondre aux questions des utilisateurs et qui vous donnera une meilleure comprA~Xhension de son fonctionnement. Il vous donnera les bases de l'utilisation de po4a et sert d'introduction A~  la documentation des outils spA~Xcifiques.
Comment commencer une nouvelle traduction ?
Comment convertir la traduction en un fichier de documentation ?
Comment mettre A~  jour une traduction faite avec po4a ?
Comment convertir une traduction prA~X-existante A~  ce systA~Xme ?
Comment ajouter des choses n'A~Xtant pas des traductions (comme le nom du traducteur) ?
Comment automatiser tout ceci ?
3 Comment A~Xa marche ?
Cette section vous donne un bref aperA~Xu des rouages internes de po4a afin que vous vous sentiez plus A~  mA~Xme de nous aider A~  le maintenir et l'amA~Xliorer. Elle peut A~Xgalement vous permettre de comprendre pourquoi cela ne fait pas ce que vous souhaitez et corriger vos problA~Xmes par vous-mA~Xme.
4 FAQ
Cette section regroupe les questions le plus souvent posA~Xes. En fait, la plupart d'entre elles sont des questions de design du projet. Si vous pensez que po4a n'est pas la bonne rA~Xponse au problA~Xme de traduction de documentation, lisez cette section avant de nous donner votre avis sur la liste de diffusion <po4a-devel@lists.alioth.debian.org>. Votre avis nous intA~Xresse.
5 Notes spA~Xcifiques A~  certains modules
Cette section prA~Xsente les spA~XcificitA~Xs de chaque module du point de vue du traducteur et de l'auteur original. Lisez le pour prendre connaissance du format des traductions pour ce module et les rA~Xgles A~  suivre dans le document original pour rendre le travail des traducteurs plus simple.

Cette section ne fait pas vraiment partie de ce document, mais elle est placA~Xe dans chaque documentation des modules. Ceci permet de s'assurer que les informations sont A~  jour en conservant la documentation et le code ensemble.

6 Bogues connus et fonctionnalitA~Xs manquantes
Un certain nombre dA~XjA~  :(

Pourquoi utiliser po4a ? Dans quel domaine est-il bon ?

J'aime le concept des logiciels A~  sources ouverts, qui permettent de donner A~  tous un accA~Xs au logiciel et A~  son code source. Mais, A~Xtant moi-mA~Xme franA~Xais, je suis conscient que la licence n'est pas le seul frein A~  l'ouverture d'un logiciel : les logiciels non traduits, mA~Xme s'ils sont libres, sont sans aucune utilitA~X pour ceux qui ne comprennent pas l'anglais, et il y a encore beaucoup de travail pour les rendre accessibles A~  vraiment tout le monde.

La perception du problA~Xme par les acteurs du dA~Xveloppement libre s'est fortement accA~XlA~XrA~Xe rA~Xcemment. Nous, les traducteurs, avons gagnA~X une premiA~Xre bataille et avons convaincu tout le monde de l'importance des traductions. Mais c'est malheureusement la partie la plus facile. Il faut maintenant rA~Xaliser tout le travail et traduire tous les documents.

Les logiciels aux sources ouverts bA~XnA~Xficient d'un niveau de traduction relativement bon, grA~Xce A~  la formidable suite d'outils gettext. Ces outils permettent d'extraire les chaA~Xnes A~  traduire du programme, de les prA~Xsenter sous une forme standard pour les traducteurs, puis d'utiliser le rA~Xsultat de leur travail lors de l'exA~Xcution pour afficher les messages traduits aux utilisateurs.

Mais cette situation est assez diffA~Xrente en ce qui concerne les documentations. Trop souvent, la documentation traduite n'est pas assez visible (pas distribuA~Xe avec le programme), seulement partielle ou pas A~  jour. Cette derniA~Xre situation est de loin la moins bonne. Les traductions pas A~  jour peuvent se rA~XvA~Xler plus embA~Xtantes pour les utilisateurs que l'absence de traduction parce que d'anciens comportements d'un programme peuvent y A~Xtre dA~Xcrits, mais ne plus A~Xtre en vigueur.

La problA~Xmatique

La traduction des documentations n'est pas une tA~Xche difficile en elle-mA~Xme. Les textes sont bien plus longs que les messages des programmes ce qui rend leur traduction plus longue, mais il n'y a aucune difficultA~X technique A~  faire ceci. La difficultA~X vient en fait de la maintenance de la traduction. La dA~Xtection des parties ayant A~XtA~X modifiA~Xes et nA~Xcessitant une mise A~  jour est une tA~Xche trA~Xs difficile, ce qui explique que tant de traductions ne correspondent plus A~  la version originale.

La rA~Xponse de po4a

La maintenance de la traduction est donc la raison premiA~Xre de po4a. La faA~Xon de faire de gettext a A~XtA~X rA~XutilisA~Xe dans ce but. Comme avec gettext, des chaA~Xnes de texte sont extraites de leur emplacement d'origine de faA~Xon A~  A~Xtre prA~XsentA~Xes de faA~Xon standardisA~Xe aux traducteurs. Les outils pour gettext sont ensuite utilisA~Xs pour aider le traducteur A~  faire son travail lorsqu'une nouvelle version du document est disponible. Mais, A~  la diffA~Xrence de l'utilisation classique de gettext, les traductions sont rA~XinjectA~Xe dans la structure du document d'origine de faA~Xon A~  pouvoir les utiliser ou les distribuer comme les documents de la version anglaise.

GrA~Xce A~  ceci, la dA~Xtection des parties du document qui nA~Xcessitent une mise A~  jour est trA~Xs facile. Un autre avantage est que l'outil va faire une bonne partie du travail lorsque seule la structure du document A~  A~XtA~X modifiA~Xe et que des chapitres ont A~XtA~X dA~XplacA~Xs, rassemblA~Xs ou redA~XcoupA~Xs. En extrayant le texte A~  traduire de la structure du document, il permet A~Xgalement de masquer la complexitA~X de la mise en page et rA~Xduit les chances d'avoir un document dA~Xfectueux (mA~Xme s'il reste un risque).

Veuillez A~Xgalement consulter la FAQ plus bas dans ce document pour une liste plus complA~Xte des avantages et inconvA~Xnients de cette approche.

Formats supportA~Xs

Actuellement, cette approche a A~XtA~X implA~XmentA~Xe avec succA~Xs pour un certain nombre de formats de mise en page de texte.

nroff

Le bon vieux format des pages de manuel, utilisA~X par beaucoup de programmes. Le support de po4a pour ce format est trA~Xs utile parce que ce format est assez compliquA~X, surtout pour les dA~Xbutants. Le module Locale::Po4a::Man(3pm) supporte A~Xgalement le format mdoc, utilisA~X par les pages de manuel BSD (elles sont A~Xgalement assez frA~Xquentes sous Linux).

pod

C'est le format pour la documentation en ligne de Perl (AX Perl Online Documentation AX). Le langage et ses documentations sont documentA~Xs de cette faA~Xon, ainsi que la plupart des scripts Perl existants. Il permet de garder la documentation plus fidA~Xle au code en les intA~Xgrant tous deux au mA~Xme fichier. Il rend la vie du programmeur plus simple, mais malheureusement pas celle du traducteur.

sgml

MA~Xme s'il est de plus en plus remplacA~X par le XML, ce format est encore assez utilisA~X pour les documents dont la taille dA~Xpasse plusieurs A~Xcrans. Il permet de faire des livres complets. La mise A~  jours de documents aussi longs est un vrai cauchemar. diff se montre souvent inutile quand le document original a A~XtA~X rA~XindentA~X aprA~Xs une mise A~  jour. Heureusement, po4a vous aide dans cette tA~Xche.

Actuellement, seuls les DTD debiandoc et docbook sont supportA~Xs, mais l'ajout d'un nouveau est trA~Xs facile. Il est mA~Xme possible d'utiliser po4a avec un DTD sgml inconnu sans modifier le code en fournissant les informations nA~Xcessaires sur la ligne de commande. Veuillez consulter Locale::Po4a::Sgml(3pm) pour plus de dA~Xtails.

TeX / LaTeX

Le format LaTeX est un format majeur utilisA~X pour les documentations dans le monde du logiciel libre ou pour des publications. Le module Locale::Po4a::LaTeX(3pm) a A~XtA~X testA~X avec la documentation de Python, un livre et avec quelques prA~Xsentations.

texinfo

Toutes les documentations du projet GNU sont A~Xcrites dans ce format (c'est mA~Xme une des exigences pour devenir un projet officiel du projet GNU). Le support pour Locale::Po4a::Texinfo(3pm) dans po4a en est encore A~  ses dA~Xbut. Veuillez nous envoyer des rapports de bogue ou des demandes de nouvelle fonctionnalitA~X.

xml

Le format XML est A~  la base de beaucoup de formats pour la documentation.

A~X ce jour, la DTD docbook est supportA~Xe par po4a. Veuillez consulter Locale::Po4a::Docbook(3pm) pour plus de dA~Xtails.

autres

Po4a peut A~Xgalement gA~Xrer des formats plus rares et plus spA~Xcifiques, tels que celui de la documentation des options de compilation des noyaux 2.4.x ou les diagrammes produits par l'outil dia. L'ajout d'un nouveau format est souvent trA~Xs simple, et consiste principalement A~  fournir un interprA~Xteur pour le format voulu. Veuillez consulter Locale::Po4a::TransTractor(3pm) pour plus d'informations A~  ce sujet.

Formats non supportA~Xs

Malheureusement, po4a ne supporte pas encore certains formats utilisA~Xs pour les documentations.

Il y a une quantitA~X d'autres formats que nous aimerions supporter avec po4a, et pas seulement des formats de documentation. En fait, nous visons toutes les AX niches AX laissA~Xes par les outils gettext classiques. Cela va de la traduction de la documentation des descriptions des paquets Debian et paquetages rpm, aux les questions posA~Xes par les scripts d'installation, ex passant par les fichiers changelog, et de tous les formats spA~Xcifiques tels que les scA~Xnarios de jeux ou les fichiers de ressource pour wine.

Comment utiliser po4a ?

Cette section est une sorte de manuel de rA~XfA~Xrence qui cherche A~  rA~Xpondre aux questions des utilisateurs et qui vous donnera une meilleure comprA~Xhension de son fonctionnement. Il vous donnera les bases de l'utilisation de po4a et sert d'introduction A~  la documentation des outils spA~Xcifiques.

RA~XsumA~X graphique

Le schA~Xma suivant donne un aperA~Xu du processus mis en oeuvre pour la traduction de documents avec po4a. Ne soyez pas effrayA~X par son apparente complexitA~X, qui est due au fait que le processus complet y est prA~XsentA~X. Une fois que vous avez converti votre projet A~  po4a, seule la partie de droite du graphique est utilisA~Xe. Remarquez que l'exemple considA~Xre le format sgml, mais que tout reste identique avec les autres modules. Chaque partie de la figure sera dA~XtaillA~Xe dans les sections suivantes.
   fr.sgml  original.sgml ---->--------+------>----------->-------+
      |         |                      |                          |
      V         V       { mise A~  jour de l'original }             |
      |         |                      |                          |
      +--<---<--+                      V                          |
      |         |              original.new.sgml----->------->----+
      V         V                      |                          |
   [po4a-gettextize]      +--->---->---+                          |
      |         |         |            V                          |
      |         |         |     [po4a-updatepo]                   |
      |         V         ^            |                          V
      V    original.pot   |            V                          |
      |         |         |          fr.po                        |
      |         |         |       (approximA~X)                     |
      |  { traduction }   |            |                          |
      |         |         ^            V                          V
      |         |         |    {A~Xdition manuelle}                 |
      V         V         |            |                          |
      |         |         |            V                          V
      |         |         +--<---    fr.po       addendum   original.sgml
      +---->----+---->------->--->  (A~  jour)   (optionnel)     (A~  jour)
                                       |            |             |
                                       v            v             v
                                       +------>-----+------<------+
                                                    |
                                                    v
                                            [po4a-translate]
                                                    |
                                                    V
                                                 fr.sgml
                                                (A~  jour)
 
 

La partie gauche illustre la conversion d'une traduction n'utilisant pas po4a. En haut de la partie droite est prA~XsentA~X ce qui est du ressort de l'auteur du document d'origine (la mise A~  jour de la documentation). Au milieu de la partie de droite se trouve la partie automatisA~Xe par po4a. Les nouvelles chaA~Xnes sont extraites et comparA~Xes avec la traduction existante. Pour celles qui n'ont pas changA~X, la traduction prA~XcA~Xdente est utilisA~Xe. Celles qui ont A~XtA~X en partie modifiA~Xes sont A~Xgalement associA~Xes A~  leur ancienne traduction, mais avec un marquage spA~Xcifique indiquant que la traduction doit A~Xtre mise A~  jour. La partie du bas indique comment le document formatA~X est construit.

En fait, en tant que traducteur, la seule opA~Xration manuelle consiste en l'A~Xtape indiquA~Xe par {A~Xdition manuelle}. En effet, nous nous en excusons, po4a aide A~  la traduction, mais il ne traduit rien pour vous...

Comment commencer une nouvelle traduction ?

Cette section prA~Xsente les A~Xtapes nA~Xcessaires pour dA~Xbuter une nouvelle traduction avec po4a. Les modifications A~  appliquer pour la conversion d'un projet existant sont dA~XtaillA~Xes dans la section correspondante.

Voici les A~Xtapes permettant de commencer une traduction avec po4a :

-
Extraction du texte du document d'origine qui doit A~Xtre traduit dans un nouveau fichier pot (le format utilisA~X par gettext). Pour ceci, utilisez po4a-gettextize de cette faA~Xon :
   $ po4a-gettextize -f <format> -m <maitre.doc> -p <traduction.pot>
 
 

Naturellement, <format> est le format du document <maitre.doc> et la sortie est placA~Xe dans <traduction.pot>. Veuillez consulter po4a-gettextize(1) pour plus de dA~Xtails concernant les options existantes.

-
Traduit rA~Xellement ce qui doit A~Xtre traduit. Pour cela, vous devez renommer le fichier pot en doc.XX.po (oA~X XX est le code ISO639 de la langue vers laquelle vous A~Xtes en train de traduire, c.-A~ -d. AX fr AX pour le franA~Xais), puis A~Xditer ce fichier. C'est souvent une bonne idA~Xe de ne pas nommer le fichier XX.po pour A~Xviter de confondre ce fichier avec la traduction des messages du programme, mais vous faites comme vous voulez. N'oubliez pas de mettre A~  jour les en-tA~Xtes du fichier po, ils sont importants.

La traduction peut A~Xtre rA~XalisA~Xe avec Emacs et son mode po ou kbabel (basA~X sur KDE) ou gtranslator (basA~X sur GNOME) ou encore n'importe quel programme que vous prA~XfA~Xrez utiliser pour l'A~Xdition de ces fichiers. Un bon vieux vi fera l'affaire, mA~Xme s'il n'y a pas de mode spA~Xcial pour ce type de tA~Xche.

Si vous voulez en apprendre plus A~  ce sujet, vous voudrez probablement consulter la documentation de gettext, disponible dans le paquet gettext-doc.

Comment convertir la traduction en un fichier de documentation ?

Une fois que la traduction est effectuA~Xe, il faut gA~XnA~Xrer la documentation traduite et la distribuer avec l'original. Pour cela, utilisez po4a-translate(1) de cette faA~Xon (XX reprA~Xsente le code de la langue) :
   $ po4a-translate -f <format> -m <maitre.doc> -p <doc.XX.po> -l <XX.doc>
 
 

Comme prA~XcA~Xdemment, <format> est le format du document <maitre.doc>. Mais cette fois-ci, le fichier po fourni en paramA~Xtre de l'option -p est un fichier d'entrA~Xe. Il s'agit de votre traduction. La sortie se trouve dans le fichier <XX.doc>.

Veuillez consulter po4a-translate(1) pour plus de dA~Xtails.

Comment mettre A~  jour une traduction faite avec po4a ?

Pour mettre A~  jour votre traduction lorsque l'original a changA~X, utilisez po4a-updatepo(1) comme ceci :
   $ po4a-updatepo -f <format> -m <nouvel_original.doc> -p <courant.XX.po>
 
 

(Veuillez consulter po4a-updatepo(1) pour plus de dA~Xtails)

Naturellement, les nouveaux paragraphes de ce document ne seront pas traduits par magie dans le fichier "po" par cette opA~Xration, et vous devrez mettre A~  jour le fichier "po" manuellement. De la mA~Xme faA~Xon, vous devrez vA~Xrifier les traductions des paragraphes qui ont A~XtA~X lA~XgA~Xrement modifiA~Xs. Pour vous assurer que vous n'en oubliez pas, ils sont marquA~Xs comme AX fuzzy AX pendant cette phase, et vous devrez retirer cette marque avant d'utiliser la traduction avec po4a-translate. Comme pour la traduction originelle, vous pouvez utiliser votre A~Xditeur de fichier po prA~XfA~XrA~X.

Une fois que votre fichier po est de nouveau A~  jour, sans aucune chaA~Xne non traduite ou marquA~Xe comme AX fuzzy AX, vous pouvez gA~XnA~Xrer un fichier de documentation traduit, comme expliquA~X dans la section prA~XcA~Xdente.

Comment convertir une traduction prA~X-existante A~  ce systA~Xme ?

Souvent, vous traduisez manuellement le document sans difficultA~X, jusqu'A~  ce qu'une rA~Xorganisation majeure du document d'origine apparaisse. Alors, aprA~Xs quelques essais infructueux en utilisant diff ou des outils similaires, vous voulez convertir la traduction A~  po4a. Mais bien sA~Xr, vous ne souhaitez pas perdre votre traduction existante dans le mA~Xme temps. Pas de panique, ce cas est aussi gA~XrA~X par les outils de po4a et est appelA~X gettextization.

Le point important pour ceci est d'avoir la mA~Xme structure de document pour l'original et la version traduite, de faA~Xon A~  ce que les outils associent leur contenu correctement.

Si vous avez de la chance (c.-A~ -d., si les structures des deux documents se correspondent parfaitement), ceci fonctionnera sans soucis, et vous n'en aurez que pour quelques secondes. Sinon, vous allez comprendre pourquoi ce processus a un nom si barbare, et vous devriez vous prA~Xparer A~  une tA~Xche ingrate. Dans tous les cas, souvenez-vous que c'est le prix A~  payer pour bA~XnA~Xficier du confort que po4a vous apportera par la suite. Le point positif est que vous n'aurez A~  faire cela qu'une seule fois.

Ceci ne sera jamais rA~XpA~XtA~X suffisamment : afin de faciliter ce processus, il est trA~Xs important de trouver la version exacte qui a A~XtA~X utilisA~Xe pour rA~Xaliser la traduction. La meilleure situation est quand vous avez notA~X la version CVS lors de la traduction.

A~Xa ne fonctionnera pas trA~Xs bien si vous utilisez le document d'origine mis A~  jour avec l'ancienne traduction. A~Xa reste possible, mais sera plus compliquA~X et doit A~Xtre A~XvitA~X autant que possible. En fait, je pense que si vous n'arrivez pas A~  trouver le document original, la meilleure solution est de trouver quelqu'un pour faire la gettextization pour vous (mais, s'il vous plaA~Xt, pas moi ;).

Je dramatise peut-A~Xtre un peu trop ici. MA~Xme lorsque tout ne se passe pas bien, c'est bien plus rapide que de tout retraduire. J'ai pu rA~Xaliser une gettextization de la traduction franA~Xaise de Perl en un jour, mA~Xme si les choses ne se sont pas bien passA~Xes. Il y avait plus de deux mA~Xgaoctets de textes, et une nouvelle traduction aurait pris des mois.

Voici d'abord la procA~Xdure, puis nous reviendrons sur les astuces qui permettent d'y parvenir avec succA~Xs lorsqu'il y a un problA~Xme. Pour faciliter la comprA~Xhension, le module sgml est utilisA~X en exemple, mais le format est, encore une fois, sans importance.

Une fois que vous avez retrouvA~X l'ancien document original, la gettextization peut A~Xtre aussi facile que ceci :

  $ po4a-gettextize -f <format> -m <original.anc> -l <traduction.anc> -p <doc.XX.po>
 
 

Si vous avez de la chance, c'est fini. Vous avez converti votre ancienne traduction pour po4a et pouvez commencer la phase de mise A~  jour qui suit. Utiliser la procA~Xdure dA~Xcrite quelques sections auparavant pour synchroniser votre fichier po avec le nouveau document original, et mettez A~  jour votre traduction en consA~Xquence.

Veuillez noter que mA~Xme si tout semble s'A~Xtre bien passA~X, il reste une possibilitA~X que des erreurs se soient introduites au cours du processus. En fait, po4a est incapable de vA~Xrifier que les chaA~Xnes correspondent A~  l'original, et il marque toutes les chaA~Xnes comme AX fuzzy AX au cours de cette procA~Xdure. Vous devriez vA~Xrifier chacune d'elle soigneusement avant de retirer ces marques.

Souvent, la structure du document ne correspond pas exactement, ce qui empA~Xche po4a-gettextize de faire son travail correctement. Pour contourner cela, vous pouvez A~Xditer les fichiers afin de faire correspondre leur structure.

La section ``Gettextization : Comment A~Xa marche ?'' ci-dessous pourra vous aider. La comprA~Xhension du fonctionnement interne vous aidera A~  rA~Xaliser cette tA~Xche. Par chance, po4a-gettextize est relativement bavard sur ce qui s'est mal passA~X. Dans un premier temps, il indique oA~X, dans les documents, se trouve la diffA~Xrence des structures. Vous obtiendrez les chaA~Xnes qui ne correspondent pas, leur position dans le texte, et leur type De plus, le fichier po gA~XnA~XrA~X ainsi sera A~Xcrit dans gettextization.failed.po.

-
Retirez toutes les parties propres A~  la traduction, telles que les sections dans lesquelles vous avez indiquA~X le nom du traducteur et les remerciements envers toutes les personnes qui ont contribuA~X A~  la traduction. Les addenda qui sont dA~Xcrits dans la section suivante vous permettront de les rajouter par la suite.
-
N'hA~Xsitez pas A~  A~Xditer les deux fichiers. Le plus important est d'obtenir le fichier po. Vous pourrez le mettre A~  jour par la suite. Cela dit, il est tout de mA~Xme prA~XfA~Xrable d'A~Xditer la traduction quand c'est possible, puisque A~Xa simplifiera les A~Xtapes suivantes.
-
Si besoin, supprimez des parties de l'original s'il se trouve qu'elles n'ont pas A~XtA~X traduites. Elles reviendront par la suite lorsque vous synchroniserez le po avec le document.
-
Si vous avez un peu modifiA~X la structure (pour combiner deux paragraphes ou pour en dA~Xcouper un autre), enlevez ces modifications. S'il y a des problA~Xmes avec l'original, vous devriez en informer son auteur. Faire la correction dans votre traduction n'en fait bA~XnA~Xficier qu'une partie de la communautA~X. Et de plus, ce n'est pas possible lorsque po4a est utilisA~X.
-
Parfois, le contenu des paragraphes correspond, mais pas leur type. Corriger cela dA~Xpend du format. Pour les formats pod et nroff, cela provient souvent du fait qu'un des deux contient une ligne commenA~Xant par des espaces et pas l'autre. Pour ces formats, cela signifie que ce paragraphe ne doit pas A~Xtre reformatA~X, il a donc un type diffA~Xrent. Retirez simplement les espaces et vous serez tranquille. Il se peut aussi qu'il s'agisse d'une petite erreur dans le nom d'une balise.

De la mA~Xme faA~Xon, deux paragraphes peuvent avoir A~XtA~X combinA~Xs, dans le format pod, si la ligne qui les sA~Xpare contient des espaces, ou s'il n'y a pas de ligne vide avant la ligne =item et le contenu de cet A~XlA~Xment.

-
Il arrive A~Xgalement qu'il se produise une dA~Xsynchronisation entre les fichiers, et la traduction se retrouve alors attachA~Xe au mauvais paragraphe. C'est le signe que le problA~Xme se situe avant dans le fichier. Consultez gettextization.failed.po pour voir quand la dA~Xsynchronisation s'est produite, et corrigez-la.
-
D'autres fois, vous aurez l'impression que po4a a oubliA~X des parties du texte original ou de la traduction. gettextization.failed.po indique que les deux correspondent correctement, mais la gettextization A~Xchoue parce que po4a essaie de faire correspondre un paragraphe avec le paragraphe suivant (ou prA~XcA~Xdant) de celui qui devrait lui A~Xtre associA~X, comme si celui-ci avait disparu. Vous pesterez sA~Xrement contre po4a comme je l'ai fait quand A~Xa m'est arrivA~X.

Cette situation malheureuse se manifeste quand un mA~Xme paragraphe est rA~XpA~XtA~X dans le document. Dans ce cas, aucune nouvelle entrA~Xe n'est crA~XA~Xe dans le fichier po, mais une nouvelle rA~XfA~Xrence est ajoutA~Xe A~  l'entrA~Xe existante.

Donc, lorsque le mA~Xme paragraphe apparaA~Xt deux fois dans l'original mais n'est pas traduit exactement de la mA~Xme faA~Xon chaque fois, vous aurez l'impression qu'un paragraphe de l'original a disparu. Supprimez juste la seconde traduction. Si vous prA~XfA~Xrez plutA~Xt supprimer la premiA~Xre traduction parce que la nouvelle traduction est meilleure, enlevez la seconde de sa place et replacez-la A~  la place de la premiA~Xre.

De la mA~Xme faA~Xon, si deux paragraphes lA~XgA~Xrement diffA~Xrents ont A~XtA~X traduits de faA~Xon identique, vous aurez l'impression qu'un paragraphe de la traduction a disparu. Une solution consiste A~  ajouter une certaine chaA~Xne dans le paragraphe du document original (AX I'm different AX par exemple). Ne vous inquiA~Xtez pas, ces modifications disparaA~Xtront pendant la synchronisation, et quand le texte ajoutA~X est suffisamment court, gettext associera votre traduction au texte existant de toute faA~Xon (en le marquant comme AX fuzzy AX, ce qui n'a pas d'importance puisque toutes les chaA~Xnes sont marquA~Xes comme AX fuzzy AX aprA~Xs la gettextization).

Avec un peu de chance, ces astuces vous permettront de rA~Xaliser la gettextization et d'obtenir le prA~Xcieux po. Vous serez alors prA~Xt pour synchroniser votre fichier et commencer la traduction. Veuillez noter que pour les gros fichiers, la synchronisation peut prendre beaucoup de temps.

Par exemple, la premiA~Xre exA~Xcution de po4a-updatepo pour la traduction de la documentation Perl (un fichier po de 5,5 Mo) a pris presque deux jours sur un G5 A~  1GHz. Eh oui, 48 heures. Mais les mises A~  jour suivantes n'ont pris que quelques secondes sur un vieux portable. Ceci parce que la premiA~Xre fois, la plupart des msgid du po ne correspondent A~  aucun dans le fichier pot. Ce qui oblige gettext A~  rechercher la chaA~Xne la plus proche avec un algorithme de recherche coA~Xteux.

Comment ajouter des choses n'A~Xtant pas des traductions (comme le nom du traducteur) ?

Du fait de l'approche de type gettext, faire ceci est plus compliquA~X avec po4a que A~Xa ne l'A~Xtait en A~Xditant simplement le nouveau fichier et en lisant l'original A~  cA~XtA~X. Mais ceci reste possible en utilisant les AX addenda AX.

Pour aider A~  leur comprA~Xhension, on peut considA~Xrer les addenda comme des sortes de rustines A~  appliquer sur le document traduit A~  la fin du processus. Ils sont assez diffA~Xrents des rustines usuelles (il n'y a qu'une seule ligne de contexte, qui peut contenir une expression rationnelle Perl, et ne peuvent que rajouter du texte, sans en enlever), mais la fonctionnalitA~X qu'ils apportent est la mA~Xme.

Leur but est de permettre au traducteur d'ajouter au document du texte qui ne soit pas une traduction, mais quelque chose de spA~Xcifique A~  la version traduite. De cette faA~Xon, ils peuvent ajouter une section indiquant qui a participA~X A~  cette traduction ou expliquer comment rapporter des bogues de traduction.

Un addendum est fourni dans un fichier sA~XparA~X. La premiA~Xre ligne constitue un en-tA~Xte indiquant oA~X le texte qu'il contient doit A~Xtre placA~X dans le document. Le reste du fichier est ajoutA~X tel quel A~  cette position dans le document rA~Xsultant.

Les en-tA~Xtes ont une syntaxe relativement rigide : ils doivent commencer par la chaA~Xne AX PO4A-HEADER: AX, suivie par une liste de champs de la forme AX clef=valeur AX sA~XparA~Xs par des points-virgules. Les espaces ONT leur importance. Notez qu'il n'est pas possible d'utiliser de point-virgule dans la valeur, mA~Xme en la plaA~Xant entre des guillemets.

Encore une fois, A~Xa paraA~Xt peut-A~Xtre effrayant, mais les exemples ci-dessous devraient vous aider A~  A~Xcrire les en-tA~Xtes dont vous avez besoin. Supposons que nous voulons ajouter une section AX A~X propos de cette traduction AX aprA~Xs la section AX A~X propos de ce document AX.

Voici les diffA~Xrentes clefs d'en-tA~Xte existantes :

position (obligatoire)
une expression rationnelle. L'addendum sera placA~X prA~Xs de la ligne correspondant A~  cette expression rationnelle. Notez qu'il s'agit ici du document traduit, et non pas du document original. Si plus d'une ligne correspond A~  cette expression (ou si aucune ne correspond), l'ajout A~Xchouera. Il est prA~XfA~Xrable de donner un message d'erreur que d'ajouter l'addendum au mauvais endroit.

La ligne est appelA~Xe point de position par la suite. L'endroit oA~X est ajoutA~X l'addendum est appelA~X point d'insertion. Ces deux points sont proches, mais pas identiques. Par exemple, si vous voulez insA~Xrer une nouvelle section, il est plus simple de placer le point de position au niveau du titre de la section prA~XcA~Xdente, et d'expliquer A~  po4a oA~X se termine la section (souvenez-vous que le point de position doit A~Xtre donnA~X par une expression rationnelle ne correspondant qu'A~  une seule ligne.

La localisation du point d'insertion par rapport au point de position est contrA~XlA~Xe par les champs "mode", "beginboundary" et "endboundary", comme expliquA~X par la suite.

Dans notre cas, nous aurons :

      position=<title>A~X propos de ce document</title>
 
 
mode (obligatoire)
Le mode est soit AX before AX (avant) soit AX after AX (aprA~Xs). Il permet de prA~Xciser la position de l'addendum par rapport au point d'ancrage.

Comme nous voulons placer la nouvelle section sous celle qui correspond, nous utilisons :

      mode=after
 
 
beginboundary (utilisA~X uniquement avec mode=after, et obligatoire dans ce cas)
endboundary (idem)
expression rationnelle correspondant A~  la fin de la section aprA~Xs laquelle l'addendum doit A~Xtre placA~X.

Lorsque le mode vaut AX after AX (aprA~Xs), le point d'insertion se trouvera aprA~Xs le point de position, mais pas juste aprA~Xs ! Il est placA~X A~  la fin de la section qui dA~Xbute par le point de position, c'est-A~ -dire aprA~Xs la ligne correspondant A~  l'expression rationnelle donnA~Xe par le champ "beginboundary" ou avant la ligne correspondant A~  l'expression rationnelle donnA~Xe par le champ "endboundary".

Dans notre cas, nous pouvons choisir d'indiquer la fin de la section qui doit correspondre en ajoutant :

    endboundary=</section>
 
 

ou en indiquant le dA~Xbut de la section suivante en indiquant :

    beginboundary=<section>
 
 

Dans les deux cas, notre addendum sera placA~X aprA~Xs AX </section> AX et avant AX <section> AX. La premiA~Xre solution est meilleure puisqu'elle fonctionnera toujours, mA~Xme si le document est rA~XorganisA~X.

Les deux existent parce que les formats des documentations sont diffA~Xrents. Dans certains d'entre eux, il est possible d'indiquer la fin d'une section comme AX "</section>" AX que nous avons utilisA~X), et dans d'autres les fins de section ne sont pas spA~XcifiA~Xes explicitement (c'est le cas du format nroff). Dans le premier cas, la AX frontiA~Xre AX (boundary) est la fin de section, et le point d'insertion vient aprA~Xs. Dans le second cas, la frontiA~Xre correspond au dA~Xbut de la section suivante, et le point d'insertion vient juste avant.

Tout ceci peut sembler confus, mais l'exemple suivant devrait vous A~Xclairer.

Pour rA~Xsumer l'exemple utilisA~X, pour ajouter une section appelA~Xe AX A~X propos de cette traduction AX aprA~Xs la section AX A~X propos de ce document AX dans un document sgml, vous pouvez utiliser une de ces lignes d'en-tA~Xte.
  PO4A-HEADER: mode=after; position=A~X propos de ce document; endboundary=</section>
  PO4A-HEADER: mode=after; position=A~X propos de ce document; beginboundary=<section>
 
 
Si vous voulez ajouter quelque chose aprA~Xs la section nroff suivante :
   .SH "AUTEURS"
 
 

vous devez utiliser un champ "position" correspondant A~  cette ligne, et un champ "beginboundary" correspondant au dA~Xbut de la section suivante (c'est-A~ -dire "^\.SH"). L'addendum sera placA~X aprA~Xs le point de position et immA~Xdiatement avant la premiA~Xre ligne correspondant au champ "beginboundary". C'est-A~ -dire :

  PO4A-HEADER:mode=after;position=AUTEURS;beginboundary=\.SH
 
 
Si vous voulez ajouter quelque chose A~  une section (par exemple aprA~Xs AX Copyright Tralala AX) au lieu d'ajouter une section entiA~Xre, vous pouvez fournir une "position" correspondant A~  cette ligne, et un champ "beginboundary" correspondant A~  n'importe quelle ligne.
  PO4A-HEADER:mode=after;position=Copyright Tralala, 2004;beginboundary=^
 
 
Si vous voulez ajouter quelque chose A~  la fin du document, donnez une position correspondant A~  n'importe quelle ligne du document (mais A~  une seule ligne, puisque po4a n'acceptera pas que la position ne corresponde pas A~  une ligne unique), et donnez un champ "endboundary" ne correspondant A~ aucune ligne. N'utilisez pas de chaA~Xne simple, comme AX FIN AX, mais prA~XfA~Xrez-en une qui a une chance moindre de se trouver dans votre document.
  PO4A-HEADER:mode=after;position=<title>Au sujet de...</title>;beginboundary=FausseLimitePo4a
 
 

Dans tous les cas, rappelez-vous qu'il s'agit d'une expression rationnelle. Par exemple, si vous voulez pointer la fin d'une section nroff qui se termine par la ligne :

   .fi
 
 

N'utilisez pas ".fi" comme valeur pour endboundary, parce que cette expression rationnelle correspond A~Xgalement A~  AX ce[ fi]chier AX, ce qui n'est A~Xvidemment pas ce que vous voulez. La valeur du champ endboundary dans ce cas est "^\.fi$".

Si l'addendum n'est pas positionnA~X lA~  oA~X vous l'escomptiez, essayez en fournissant l'option -vv aux outils, ce qui vous donnera des indications sur ce qui est fait pour le placement de l'addendum.

Voici un exemple plus dA~XtaillA~X.

Document original (au format pod) :

  |=head1 NAME
  |
  |dummy - a dummy program
  |
  |=head1 AUTHOR
  |
  |me
 
 

Voici maintenant un addendum qui s'assure qu'une section est ajoutA~Xe A~  la fin du fichier pour indiquer le traducteur.

  |PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head
  |
  |=head1 TRADUCTEUR
  |
  |moi
 
 

De faA~Xon A~  placer l'addendum avant l'AUTEUR (section nommA~Xe AUTHOR dans le document original), utilisez l'en-tA~Xte suivant :

  PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1
 
 

Ceci fonctionne parce que la premiA~Xre ligne correspondant A~  l'expression rationnelle donnA~Xe dans le champ beginboundary (/^=head1/) aprA~Xs la section AX NOM AX (correspondant A~  la section AX NAME AX dans le document original), est celle indiquant les auteurs. De cette faA~Xon, l'addendum est placA~X entre les deux sections.

Comment automatiser tout ceci ?

L'utilisation de po4a s'est montrA~Xe propice aux erreurs pour les utilisateurs parce que deux programmes doivent A~Xtre appelA~Xs dans le bon ordre (po4a-updatepo puis po4a-translate), chacun d'eux prenant au moins 3 paramA~Xtres. De plus, il A~Xtait difficile avec ce systA~Xme d'utiliser un seul fichier po pour tous les documents quand plusieurs formats A~Xtaient utilisA~Xs.

Le programme po4a(1) a A~XtA~X conA~Xu pour rA~Xpondre A~  ces difficultA~Xs. Une fois que votre projet a A~XtA~X converti A~  po4a, vous A~Xcrivez un petit fichier de configuration indiquant oA~X se trouvent vos fichiers de traduction (les fichiers po et pot), oA~X se trouvent les documents originaux, leurs formats, et oA~X doivent A~Xtre placA~Xes leur traduction.

Ensuite, l'appel de po4a(1) avec ce fichier vA~Xrifie que les fichiers po sont synchronisA~Xs avec le document original, et que les documents traduits sont gA~XnA~XrA~Xs correctement. Bien sA~Xr, il vous faudra appeler ce programme deux fois : une fois avant l'A~Xdition des fichiers po pour les mettre A~  jour et une autre fois aprA~Xs pour mettre A~  jour les documents traduits. Mais vous n'aurez qu'A~  vous rappeler cette commande.

Comment A~Xa marche ?

Cette section vous donne un bref aperA~Xu des rouages internes de po4a afin que vous vous sentiez plus A~  mA~Xme de nous aider A~  le maintenir et l'amA~Xliorer. Elle peut A~Xgalement vous permettre de comprendre pourquoi cela ne fait pas ce que vous souhaitez et corriger vos problA~Xmes par vous-mA~Xme.

Quel est le plan gA~XnA~Xral ici ?

L'architecture po4a est orientA~Xe objet (en Perl, n'est-ce pas formidable ?). L'ancA~Xtre commun de tous les classes d'analyseur est appelA~X Transtractor. Ce nom A~Xtrange provient du fait qu'il est A~  la fois chargA~X de la traduction et de l'extraction des chaA~Xnes du document.

Plus formellement, il prend un document A~  traduire et un fichier po contenant les traductions en entrA~Xe et produit en sortie deux autres fichiers : un autre fichier po (rA~Xsultant de l'extraction des chaA~Xnes A~  traduire du document d'entrA~Xe), et un document traduit (avec la mA~Xme structure que le document d'entrA~Xe, mais dont toutes les chaA~Xnes A~  traduire ont A~XtA~X remplacA~Xes par leur traduction donnA~Xe par le po fournit en entrA~Xe). Voici une reprA~Xsentation graphique de tout ceci :

   document entrA~Xe --\                             /---> document sortie
                      \      TransTractor::       /       (traduit)
                       +-->--   parse()  --------+
                      /                           \
   po entrA~Xe --------/                             \---> po sortie
                                                          (extrait)
 
 

Cette forme d'os est le coeur de l'architecture de po4a. Sans le fichier po en entrA~Xe et le document en sortie, cela donne po4a-gettextize. Si vous fournissez les deux entrA~Xes et ignorez le po de sortie, vous aurez po4a-translate.

TransTractor::parse() est une fonction virtuelle implA~XmentA~Xe dans chaque module. Voici un petit exemple pour montrer comment elle marche. Cet exemple analyse une liste de paragraphes qui dA~Xbutent tous par <p>.

   1 sub parse {
   2   PARAGRAPH: while (1) {
   3     $my ($paragraph,$pararef,$line,$lref)=("","","","");
   4     $my $first=1;
   5     while (($line,$lref)=$document->shiftline() && defined($line)) {
   6       if ($line =~ m/<p>/ && !$first--; ) {
   7         $document->unshiftline($line,$lref);
   8
   9         $paragraph =~ s/^<p>//s;
  10         $document->pushline("<p>".$document->translate($paragraph,$pararef));
  11
  12         next PARAGRAPH;
  13       } else {
  14         $paragraph .= $line;
  15         $pararef = $lref unless(length($pararef));
  16       }
  17     }
  18     return; # Did not got a defined line? End of input file.
  19   }
  20 }
 
 

A~X la ligne 6, <p> est rencontrA~X pour la seconde fois. Cela indique le passage un paragraphe suivant. Nous replaA~Xons donc la ligne, qui vient juste d'A~Xtre obtenue, dans le document d'origine (ligne 7) et envoyons le paragraphe ainsi construit dans les sorties. AprA~Xs avoir retirA~X le <p> de tA~Xte en ligne 9, nous envoyons la concatA~Xnation de cette balise avec la traduction du reste du paragraphe.

Cette fonction translate() est trA~Xs pratique. Elle envoie son paramA~Xtre dans le fichier po de sortie (l'extraction) et renvoie sa traduction telle qu'elle a A~XtA~X trouvA~Xe dans le fichier po d'entrA~Xe (la traduction). Comme elle est utilisA~Xe dans le paramA~Xtre de pushline(), cette traduction se retrouve dans le document de sortie.

N'est-ce pas gA~Xnial ? Il est possible de construire un module complet pour po4a en moins de 20 lignes, si le format est suffisamment simple...

Vous trouverez plus de dA~Xtails A~  ce sujet dans Locale::Po4a::TransTractor(3pm).

Gettextization : Comment A~Xa marche ?

L'idA~Xe ici est de prendre A~  la fois le document d'origine et sa traduction, et de supposer que la NiA~Xme chaA~Xne extraite du document traduit correspond A~  la traduction de la NiA~Xme chaA~Xne du document original. Pour que cela fonctionne, il faut donc que les deux documents aient exactement la mA~Xme structure. Par exemple, si les fichiers ont la structure suivante, il y a trA~Xs peu de chance pour que la quatriA~Xme chaA~Xne de la traduction (qui est de type AX chapter AX) soit la traduction de la quatriA~Xme chaA~Xne du document original (de type AX paragraph AX).
     Original         Traduction
 
   chapitre            chapitre
     paragraphe          paragraphe
     paragraphe          paragraphe
     paragraphe        chapitre
   chapitre              paragraphe
     paragraphe          paragraphe
 
 

Pour cela, les analyseurs po4a sont utilisA~Xs A~  la fois sur l'original et sur la traduction pour extraire des fichiers po, et un troisiA~Xme fichier po est construit A~  partir d'eux en utilisant les chaA~Xnes du second comme traductions des chaA~Xnes du premier. Pour s'assurer que les chaA~Xnes ainsi associA~Xes sont bien les traductions, les analyseurs de po4a doivent ajouter des informations sur le type syntaxique des chaA~Xnes extraites du document (les analyseurs existants le font, les vA~Xtres devraient A~Xgalement). Ensuite, ces informations sont utilisA~Xes pour s'assurer que les deux documents ont la mA~Xme syntaxe. Dans l'exemple prA~XcA~Xdent, cela permet de dA~Xtecter que la quatriA~Xme chaA~Xne est dans un cas un paragraphe et dans l'autre un titre de chapitre, et le problA~Xme est affichA~X.

En thA~Xorie, il devrait A~Xtre possible de dA~Xtecter le problA~Xme, puis de resynchroniser les fichiers par la suite (comme le fait diff). Mais il est alors difficile de savoir quoi faire des chaA~Xnes prA~XcA~Xdant la dA~Xsynchronisation, et le rA~Xsultat pourrait parfois ne pas A~Xtre bon. C'est pourquoi l'implA~Xmentation actuelle ne resynchronise rien et A~Xchoue avec un message d'erreur complet quand quelque chose se passe mal, indiquant qu'une modification manuelle des fichiers est nA~Xcessaire pour corriger le problA~Xme.

MA~Xme avec ces prA~Xcautions, des erreurs peuvent survenir. C'est la raison pour laquelle toutes les traductions trouvA~Xes de cette faA~Xon sont marquA~Xes AX fuzzy AX, pour s'assurer que le traducteur les relira et vA~Xrifiera.

Fonctionnement d'un Addendum

Bien, il n'y a rien de bien compliquA~X ici. La traduction n'est pas directement A~Xcrite sur le disque, mais est conservA~Xe en mA~Xmoire jusqu'A~  ce que tous les addenda soient ajoutA~Xs. Les algorithmes utilisA~Xs sont assez simples. Une ligne correspondant A~  l'expression rationnelle de la position est recherchA~Xe, et l'addendum est ajoutA~X juste avant si mode=before. Sinon, la premiA~Xre ligne trouvA~Xe A~  partir de cette position correspondant A~  l'expression rationnelle donnA~Xe par le champ boundary est recherchA~Xe et l'addendum est insA~XrA~X juste aprA~Xs cette ligne s'il s'agit d'un "endboundary" ou juste avant s'il s'agit d'un "beginboundary".

FAQ

Cette section regroupe les questions le plus souvent posA~Xes. En fait, la plupart d'entre elles sont des questions de design du projet. Si vous pensez que po4a n'est pas la bonne rA~Xponse au problA~Xme de traduction de documentation, lisez cette section avant de nous donner votre avis sur la liste de diffusion <po4a-devel@lists.alioth.debian.org>. Votre avis nous intA~Xresse.

Pourquoi traduire chaque paragraphe sA~XparA~Xment ?

En effet, avec po4a, tous les paragraphes sont traduits sA~XparA~Xment (en fait, c'est au choix de chaque module, mais tous les modules existants font ainsi, et les vA~Xtres devraient A~Xgalement). Il y a deux avantages principaux A~  cette approche :
Quand les parties techniques du document sont masquA~Xes, le traducteur ne peut pas faire de bA~Xtises avec. Moins nous prA~Xsentons de marqueurs au traducteur, moins il pourra faire d'erreurs.
DA~Xcouper le document aide A~  isoler les changements apparaissant dans le document original. Lorsque l'original est modifiA~X, la mise A~  jour des parties modifiA~Xes est plus facile.

MA~Xme avec ces avantages, certains n'aiment pas l'idA~Xe de traduire chaque paragraphe sA~XparA~Xment. Voici quelques rA~Xponses A~  leurs inquiA~Xtudes :

Cette approche a A~XtA~X couronnA~Xe de succA~Xs dans le cadre du projet KDE et a permis de produire la plus grosse documentation traduite et mise A~  jour A~  notre connaissance.
Les traducteurs peuvent toujours utiliser le contexte pour traduire, puisque les chaA~Xnes du fichier po se trouvent dans le mA~Xme ordre que dans le document original. La traduction sA~Xquentielle est donc relativement comparable qu'elle soit faite avec ou sans po4a. Et dans tous les cas, la meilleure faA~Xon reste de convertir le document dans un format imprimable puisque les indications de formatage ne sont pas vraiment lisibles.
C'est l'approche utilisA~Xe par les traducteurs professionnels. MA~Xme si je l'admets, leurs buts peuvent A~Xtre diffA~Xrents des traducteurs de logiciels A~  source ouvert. La maintenance A~Xtant par exemple souvent moins critique puisque le contenu change rarement.

Pourquoi ne pas dA~Xcouper au niveau des phrases (ou A~  un niveau plus petit) ?

Les outils des traducteurs professionnels dA~Xcoupent parfois les documents au niveau des phrases, de faA~Xon A~  maximiser la rA~Xutilisation de traductions prA~XcA~Xdentes et A~  accA~XlA~Xrer leur travail. Le problA~Xme est qu'une mA~Xme phrase peut avoir plusieurs traductions en fonction du contexte.

Les paragraphes sont par dA~Xfinition plus longs que les phrases. Cela permet la plupart du temps d'assurer que deux paragraphes dans deux documents diffA~Xrents auront le mA~Xme sens (et la mA~Xme traduction), indA~Xpendamment du contexte.

Un dA~Xcoupage A~  un niveau encore plus petit qu'une phrase pourrait A~Xtre trA~Xs gA~Xnant. Ce serait un peu long d'expliquer pourquoi ici, mais les lecteurs intA~XressA~Xs pourront par exemple consulter la page de manuel Locale::Maketext::TPJ13(3pm) (qui est fournie avec la documentation de Perl). Pour faire court, chaque langue a ses propres rA~Xgles syntaxiques, et il n'y a aucun moyen de construire des phrases A~  partir de morceaux de phrases pour toutes les langues existantes (ou pour les 5 A~  10 langues les plus parlA~Xes, et mA~Xme moins).

Pourquoi ne pas mettre la version originelle en commentaire avec la traduction ?

A~X premiA~Xre vue, gettext ne semble pas adaptA~X A~  tous les types de traduction. Par exemple, il ne semblait pas adaptA~X A~  debconf, l'interface que tous les paquets Debian utilisent pour l'interaction avec l'utilisateur pendant l'installation. Dans ce cas, les textes A~  traduire A~Xtaient assez courts (une dizaine de lignes pour chaque fichier), et il A~Xtait difficile de placer la traduction dans un fichier sA~XparA~X parce qu'il doit A~Xtre disponible avant l'installation du paquet.

C'est pourquoi les concepteurs de debconf ont dA~XcidA~X d'implA~Xmenter une autre solution, plaA~Xant les traductions dans le mA~Xme fichier que l'original. C'est une solution plutA~Xt sA~Xduisante. Certains voudront A~Xgalement faire ainsi pour les fichiers xml, par exemple. Voici A~  quoi cela ressemblerait :

  <section>
   <title lang="en">My title</title>
   <title lang="fr">Mon titre</title>
 
   <para>
    <text lang="en">My text.</text>
    <text lang="fr">Mon texte.</text>
   </para>
  </section>
 
 

Mais cette solution a A~XtA~X si problA~Xmatique que l'approche basA~Xe sur po est dA~Xsormais utilisA~Xe. Seul l'original peut A~Xtre A~XditA~X dans le fichier, et les traductions sont placA~Xes dans des fichiers po gA~XnA~XrA~Xs A~  partir du modA~Xle maA~Xtre (et replacA~Xs au cours de la compilation). L'ancien systA~Xme a A~XtA~X abandonnA~X A~  cause de plusieurs problA~Xmes :

problA~Xmes de maintenance

Si plusieurs traducteurs fournissent une rustine (patch) au mA~Xme moment, il est difficile de les appliquer ensemble.

Comment dA~Xtecter les modifications dans l'original qui doivent A~Xtre appliquA~Xes A~  une traduction ? Pour pouvoir utiliser diff, il faut noter la version du document original traduit. C'est-A~ -dire qu'il faut un fichier po dans le fichier ;)

problA~Xmes d'encodage

Cette solution n'est envisageable que quand seules des langues europA~Xennes sont impliquA~Xes, mais la traduction pour le corA~Xen, le russe ou l'arabe peuvent compliquer la situation. UTF peut A~Xtre une solution, mais il y a A~Xgalement des problA~Xmes avec.

De plus, ces problA~Xmes sont difficiles A~  dA~Xtecter (c.-A~ -d. que seules les personnes capables de lire le corA~Xen pourront s'apercevoir que l'encodage pour le corA~Xen est dA~Xfectueux [ce qui aurait A~XtA~X causA~X par un traducteur russe]).

gettext rA~Xsout tous ces problA~Xmes.

Mais gettext n'a pas A~XtA~X conA~Xu pour faire A~Xa !

C'est vrai, mais A~  ce jour, personne n'a apportA~X de meilleure solution. La seule solution alternative est la traduction manuelle, avec tous les problA~Xmes de maintenance qu'elle comporte.

Quant est-il des autres outils de traduction de documentation utilisant gettext ?

Il n'y en A~  notre connaissance que deux :
poxml
C'est l'outil dA~XveloppA~X au sein du projet KDE pour gA~Xrer les XML DocBook. C'est A~  notre connaissance le premier programme qui a extrait des chaA~Xnes A~  traduire d'une documentation pour les mettre dans un fichier po, et les rA~Xinjecter ensuite dans le document aprA~Xs la traduction.

Il ne peut gA~Xrer que le format XML, avec un DTD particulier. Je n'aime pas beaucoup la faA~Xon dont les listes sont gA~XrA~Xes : elles sont rassemblA~Xes en un seul gros msgid. Lorsque la liste est de taille importante, les A~XlA~Xments sont assez durs A~  gA~Xrer.

po-debiandoc
Ce programme A~Xcrit par Denis Barbier est un prA~Xcurseur du module sgml de po4a, qui le remplace plus ou moins. Comme son nom l'indique, il ne gA~Xre que le DTD debiandoc, qui est en voie d'extinction.

Le principal avantage de po4a par rapport A~  eux est la facilitA~X d'ajouter du contenu additionnel (ce qui est encore plus difficile avec ces outils) et la possibilitA~X de faire une gettextization.

A~Xduquer les dA~Xveloppeurs au problA~Xme des traductions

Lors de la traduction de documentations ou de programmes, trois types de difficultA~Xs sont rencontrA~Xs ; des problA~Xmes linguistiques (tout le monde ne parle pas deux langues), des problA~Xmes techniques (la raison d'A~Xtre de po4a) et des problA~Xmes de type relationnel et humain. Tous les dA~Xveloppeurs ne voient pas la nA~XcessitA~X de rA~Xaliser des traductions. MA~Xme avec la meilleure volontA~X, ils peuvent aussi ignorer comment faciliter le travail des traducteurs. C'est pour cela que po4a fournit une bonne quantitA~X de documentation que vous pouvez leur indiquer.

Un autre point important est que chaque fichier traduit contient un petit commentaire indiquant ce qu'est le fichier et comment l'utiliser. Ceci devrait aider les pauvres dA~Xveloppeurs inondA~Xs de tonnes de fichiers contenant les traductions pour des langues qu'ils ne parlent quasiment pas, et qui devrait les aider A~  gA~Xrer ces fichiers correctement.

Dans le projet po4a, les fichiers traduits ne sont plus des fichiers source. Comme les fichiers sgml sont d'habitude des fichiers source, ceci peut A~Xtre dA~Xroutant. C'est pourquoi tous les fichiers contiennent un en-tA~Xte similaire A~  celui-ci :

  |       *****************************************************
  |       *           GENERATED FILE, DO NOT EDIT             * 
  |       * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
  |       *****************************************************
  |
  | This file was generated by po4a-translate(1). Do not store it (in cvs,
  | for example), but store the po file used as source file by po4a-translate. 
  |
  | In fact, consider this as a binary, and the po file as a regular source file:
  | If the po gets lost, keeping this translation up-to-date will be harder ;)
 
 

De la mA~Xme faA~Xon, les fichiers po usuels n'ont qu'A~  A~Xtre copiA~Xs dans le rA~Xpertoire po/. Mais ce n'est pas le cas de ceux manipulA~Xs par po4a. Le principal risque A~Xtant que le dA~Xveloppeur A~Xcrase la traduction existante de son programme avec la traduction de sa documentation. (Les deux ne peuvent pas A~Xtre stockA~Xes dans le mA~Xme fichier po parce que le programme doit installer sa traduction en tant que fichier mo et que la documentation n'a besoin de la traduction qu'au moment de la compilation). C'est pourquoi les fichiers po crA~XA~Xs par le module po-debiandoc contient l'en-tA~Xte suivant :

  #
  #  ADVISES TO DEVELOPERS:
  #    - you do not need to manually edit POT or PO files.
  #    - this file contains the translation of your debconf templates.
  #      Do not replace the translation of your program with this !!
  #        (or your translators will get very upset)
  #
  #  ADVISES TO TRANSLATORS:
  #    If you are not familiar with the PO format, gettext documentation 
  #     is worth reading, especially sections dedicated to this format.
  #    For example, run:
  #         info -n '(gettext)PO Files'
  #         info -n '(gettext)Header Entry'
  #
  #    Some information specific to po-debconf are available at
  #            /usr/share/doc/po-debconf/README-trans
  #         or http://www.debian.org/intl/l10n/po-debconf/README-trans
  #
 
 

RA~XSUMA~X des avantages de l'approche basA~Xe sur gettext

Les traductions ne sont pas stockA~Xes indA~Xpendamment de l'original, ce qui rend possible la dA~Xtection des parties A~  mettre A~  jour.
Les traductions sont stockA~Xes dans des fichiers diffA~Xrents pour chaque langue, ce qui A~Xvite les interfA~Xrences entre traducteurs. Que ce soit pour la soumission de rustines ou pour le choix d'un encodage.
En interne, tout est basA~X sur "gettext" (mais "po4a" offre une interface simple qui ne nA~Xcessite pas de comprendre comment A~Xa marche en interne pour pouvoir l'utiliser). Ce qui permet de ne pas rA~Xinventer la roue, et du fait de leur utilisation importante, nous pouvons supposer qu'ils ont peu ou pas de bogue.
Pour l'utilisateur final, rien ne change (A~  part que les documentations seront probablement mieux maintenues :). La documentation distribuA~Xe reste la mA~Xme.
Il n'est pas nA~Xcessaire pour les traducteurs d'apprendre une nouvelle syntaxe et leur A~Xditeur de fichier po prA~XfA~XrA~X (qui peut A~Xtre le mode po d'emacs, kbabel ou gtranslator) sera parfait.
Gettext permet d'obtenir facilement des statistiques sur ce qui a A~XtA~X fait, ce qui doit A~Xtre revu et mis A~  jour, et sur ce qu'il reste A~  faire. Vous trouverez des exemples A~  ces adresses :
  - http://kbabel.kde.org/img/previewKonq.png
  - http://www.debian.org/intl/l10n/
 
 

Mais tout n'est pas rose, et cette approche a aussi quelques dA~Xsavantages que nous devons gA~Xrer.

Les addenda sont ... surprenants au premier abord.
Il n'est pas possible d'adapter le texte traduit A~  votre goA~Xt, comme de dA~Xcomposer ou recomposer des paragraphes. Mais d'un autre cA~XtA~X, s'il s'agit d'un problA~Xme dans le document original, celui-ci doit A~Xtre signalA~X de toute faA~Xon.
MA~Xme s'il a une interface simple, il reste un nouvel outil qu'il faudra apprendre A~  maA~Xtriser.

Un de mes rA~Xves serait d'intA~Xgrer po4a A~  gtranslator ou kbabel. Lorsqu'un fichier serait ouvert, ses chaA~Xnes seraient extraites automatiquement. Lors de l'enregistrement, le fichier sgml traduit serait A~Xcrit sur le disque. Si nous arrivons A~  faire un module pour MS Word (TM) (ou au moins pour le format RTF), des traducteurs professionnels pourraient mA~Xme l'utiliser.

Bogues connus et demandes d'A~Xvolutions

Le plus gros problA~Xme (A~  part les modules manquants) est la gestion de l'encodage. Ajouter un pragma perl UTF8, puis recoder les chaA~Xnes en sortie est le chemin envisagA~X, mais ce n'est pas encore fait.

Nous aimerions A~Xgalement factoriser certaines parties de code (concernant l'injection de fichier) du module sgml dans le TransTractor de faA~Xon A~  ce que tous les modules puissent en profiter. Mais ceci n'est pas visible pour les utilisateurs.

AUTEURS

  Denis Barbier <barbier,linuxfr.org>
  Martin Quinson (mquinson#debian.org)
 
 

TRADUCTION

  Martin Quinson (mquinson#debian.org)