Provided by: po4a_0.73-2ubuntu1_all 
NOM
po4a - Cadre de travail pour la traduction de documentations et autres documents
Introduction
po4a (PO pour tout – PO for anything) facilite la maintenance de la traduction de la
documentation en utilisant les outils classiques de gettext. La principale caractéristique
de po4a est qu'il dissocie la traduction du contenu et la structure du document.
Ce document sert d'introduction au projet po4a en mettant l'accent sur personnes qui
envisagent éventuellement d'utiliser cet outil et qui sont simplement curieuses et
souhaitent comprendre pourquoi les choses sont comme elles sont.
Pourquoi po4a ?
La philosophie des logiciels libres est de rendre la technologie réellement disponible à
tout le monde. Cependant, la licence n’est pas la seule préoccupation car un logiciel
libre non traduit est inutilisable par des publics non anglophones. En conséquence, nous
avons encore du travail pour rendre les logiciels globalement disponibles.
Cette situation est bien comprise par la plupart des projets et tout le monde est
désormais convaincu de la nécessité de tout traduire. Pourtant, les traductions
représentent un effort énorme de nombreuses personnes, paralysées par de petites
difficultés techniques.
Heureusement, les logiciels libres sont réellement très bien traduits grâce à la suite
d’outils gettext. Ces outils sont utilisés pour extraire les chaines traduisibles d’un
programme et pour présenter ces dans un format standardisé (appelés fichiers PO, ou
catalogue de traduction). Tout un écosystème d’outils a émergé pour aider les équipes de
traduction à traduire ces fichiers PO. Le résultat est alors utilisé par gettext à
l'exécution du logiciel pour afficher les messages traduits dans l’interface
d’utilisation.
En ce qui concerne la documentation, cependant, la situation est quelque peu décevante. Au
début, la traduction de la documentation peut sembler plus facile que la traduction d'un
programme, car il semblerait que vous deviez simplement copier le fichier source de la
documentation et commencer à traduire le contenu. Cependant, lorsque la documentation
originale est modifiée, le suivi des modifications se transforme rapidement en cauchemar
pour les équipes de traduction. Si elle est effectuée manuellement, cette tâche est
désagréable et sujette aux erreurs.
Les traductions obsolètes sont souvent pires qu’une absence de traduction. Une
documentation qui décrit un comportement désormais obsolète du programme sera trompeuse.
De plus, la prise de contact avec les responsables du logiciels est impossible à cause de
la barrière de la langue. De plus, les responsables ne peuvent pas forcément résoudre les
problèmes sans une connaissance de toutes les langues dans lesquelles la documentation est
traduite. Ces difficultés, souvent causées par un mauvais outillage, peuvent miner la
motivation des équipes de traduction, aggravant encore les problèmes.
Le but du projet po4a est de faciliter le travail de traduction de la documentation. En
particulier, il facilite la maintenance des traductions de documentation.
L'idée est de réutiliser et d'adapter l'approche gettext à ce domaine. Comme pour gettext,
les textes sont extraits de leur emplacement d'origine et présentés aux équipes de
traduction sous forme de catalogues de traduction PO. Les équipes de traduction peuvent
utiliser les outils classiques de gettext pour suivre le travail à faire, collaborer et
s'organiser. po4a injecte ensuite les traductions directement dans la structure de la
documentation pour produire des fichiers traduits qui peuvent être traités et distribués
comme les fichiers anglais. Tout paragraphe qui n'est pas traduit est laissé en anglais
dans le document résultant, garantissant que des traductions obsolètes ne voient jamais le
jour.
Ceci automatise la plupart des gros travaux de maintenance de la traduction. La découverte
des paragraphes nécessitant une mise à jour devient très facile et le processus est
complètement automatisé lorsque les éléments sont réorganisés sans autre modification. Une
vérification spécifique peut également être utilisée pour réduire le risque d'erreurs de
formatage qui entraineraient un document altéré.
Veuillez également consulter la FAQ plus bas dans ce document pour une liste plus complète
des avantages et inconvénients de cette approche.
Formats pris en charge
Actuellement, cette approche a été implémentée avec succès pour un certain nombre de
formats de mise en page de texte :
man (analyseur stable)
Le bon vieux format des pages de manuel, utilisé par beaucoup de programmes. Le
support de po4a pour ce format est très utile parce que ce format est assez compliqué,
surtout pour les débutants.
Le module Locale::Po4a::Man(3pm) prend également en charge le format mdoc, utilisé par
les pages de manuel BSD (ils sont également assez courants sous Linux).
AsciiDoc (analyseur stable)
Ce format est un format de balisage léger destiné à faciliter la création de
documentation. Il est par exemple utilisé pour documenter le système git. Ces pages de
manuel sont traduites à l'aide de po4a.
Voir Locale::Po4a::AsciiDoc pour en savoir plus.
pod (analyseur stable)
C’est le format pour la documentation en ligne de Perl (« Perl Online Documentation>
»). Le langage et ses documentations sont documentés en utilisant ce format en plus de
la majorité des scripts Perl existants. Il permet de garder la documentation plus
fidèle au code en les intégrant tous deux au même fichier. Il rend la vie du
programmeur plus simple, mais malheureusement pas celle des équipes de traduction
jusqu'à ce que vous utilisiez po4a.
Voir Locale::Po4a::Pod pour en savoir plus.
sgml (analyseur stable)
Même s’il est de plus en plus remplacé par le XML, ce format est encore assez utilisé
pour les documents dont la taille dépasse plusieurs écrans. Il permet même de faire
des livres complets. Des documents aussi longs peuvent être vraiment complexes à
traduire. diff se montre souvent inutile quand le document original a été réindenté
après une mise à jour. Heureusement, po4a vous aide dans cette tâche.
Actuellement, seules les DTD DebianDoc et DocBook sont prises en charge, mais l’ajout
d’une nouvelle DTD est très facile. Il est même possible d’utiliser po4a avec une
DTD SGML inconnue sans modifier le code en fournissant les informations nécessaires
sur la ligne de commande. Consultez Locale::Po4a::Sgml(3pm) pour en savoir plus.
TeX / LaTeX (analyseur stable)
Le format LaTeX est un format majeur utilisé pour les documentations dans le monde du
logiciel libre ou pour des publications.
Le module Locale::Po4a::LaTeX(3pm) a été testé avec la documentation de Python, un
livre et avec quelques présentations.
text (analyseur stable)
Le format Text est le format de base pour de nombreux formats qui incluent de longs
blocs de texte, y compris Markdown, fortunes, sections préliminaires YAML,
debian/changelog et debian/control.
Ceci prend en charge le format commun utilisé dans les générateurs de sites statiques,
les README et d'autres systèmes de documentation. Voir Locale::Po4a::Text(3pm) pour en
savoir plus.
xml and XHMTL (analyseur probablement stable)
Le format XML est à la base de beaucoup de formats pour la documentation.
À ce jour, la DTD DocBook et XHTML sont pris en charge par po4a. Consultez
Locale::Po4a::Docbook(3pm) pour en savoir plus.
BibTex (analyseur probablement stable)
Le format BibTex est utilisé conjointement avec LaTeX pour la mise en forme des listes
de références (bibliographies).
Voir Locale::Po4a::BibTex pour en savoir plus.
DocBook (analyseur probablement stable)
Un langage de balisage basé sur XML qui utilise des balises sémantiques pour décrire
des documents.
Voir Locale::Po4a:Docbook pour en savoir plus.
Guide XML (analyseur probablement stable)
Un format de documentation XML. Ce module a été développé spécifiquement pour aider à
prendre en charge et à maintenir les traductions de la documentation de Gentoo Linux
jusqu'à au moins mars 2016 (basé sur la Wayback Machine). Gentoo est depuis passé au
format DevBook XML.
Voir Locale::Po4a:Guide pour en savoir plus.
Wml (analyseur probablement stable)
Le Web Markup Language, ne pas confondre le WML avec le WAP utilisé sur les téléphones
portables. Ce module s'appuie sur le module Xhtml, qui lui-même s'appuie sur le module
XmL.
Voir Locale::Po4a::Wml pour en savoir plus.
Yaml (analyseur probablement stable)
Un surensemble strict de JSON. YAML est souvent utilisé comme systèmes ou projets de
configuration. YAML est au cœur d’Ansible de Red Hat.
Voir Locale::Po4a::Yaml pour en savoir plus.
RubyDoc (analyseur probablement stable)
Le format Ruby Document (RD), à l'origine le format de documentation par défaut pour
Ruby et les projets Ruby avant d'être la conversion à RDoc en 2002. Bien
qu'apparemment la version japonaise du Manuel de Référence Ruby utilise toujours le
RD.
Voir Locale::Po4a::RubyDoc pour en savoir plus.
Halibut (analyseur très expérimental)
Un système de production de documentation, avec des éléments similaires à TeX,
debiandoc-sgml, TeXinfo, et autres, développé par Simon Tatham, le développeur de
PuTTY.
Voir Locale::Po4a:Halibut pour en savoir plus.
Ini (analyseur très expérimental)
Format de fichier de configuration popularisé par MS-DOS.
Voir Locale::Po4a::Ini pour en savoir plus.
texinfo (analyseur très expérimental)
Toutes les documentations du projet GNU sont écrites dans ce format (c’est même une
des exigences pour devenir un projet officiel du projet GNU). La prise en charge pour
Locale::Po4a::Texinfo(3pm) dans po4a en est encore à ses débuts. N’hésitez pas à nous
envoyer des rapports de bogue ou des demandes de nouvelle fonctionnalité.
gemtext (analyseur très expérimental)
Le format texte natif du protocole Gemini. L’extension « .gmi » est généralement
utilisée. La prise en charge de ce module dans po4a en est encore à ses débuts. Si
vous trouvez des problèmes, n’hésitez pas à faire un rapport de bogue ou à demander
des améliorations.
Autres formats supportés
Po4a peut également gérer des formats plus rares et plus spécifiques, tels que celui
de la documentation des options de compilation des noyaux Linux 2.4+
(Locale::Po4a::KernelHelp) ou les diagrammes produits par l’outil dia
(Locale::Po4a:Dia). L’ajout d’un nouveau format est souvent très simple, et consiste
principalement à fournir un interpréteur pour le format voulu. Consulter
Locale::Po4a::TransTractor(3pm) pour en savoir plus.
Formats non supportés
Malheureusement, po4a soufre d’un manque de prise en charge de divers formats de
documentation. Beaucoup d’entre eux seraient simples à prendre en charge dans po4a.
Cela inclut des formats étant utilisés pour plus que de la documentation, tels que les
descriptions de paquets (deb et rpm), aux questions posées par les scripts
d’installation, en passant par les fichiers changelog, et de tous les formats
spécifiques tels que les scénarios de jeux ou les fichiers de ressource pour wine.
Utiliser po4a
La manière la plus simple d'utiliser cet outil dans votre projet est d'écrire un fichier
de configuration pour le programme po4a, et de n'interagir qu'avec ce programme.
Référez-vous à sa documentation, dans po4a(1). Le reste de cette section fournit plus de
détails pour une utilisation avancée et une compréhension approfondie de po4a.
Schéma détaillé du flux de travail de po4a
Assurez-vous d'avoir lu po4a(1) avant d'aborder cette section trop détaillée afin
d'obtenir une vue d'ensemble simplifiée du flux de travail de po4a. Revenez ici pour
obtenir l'image complète et effrayante, avec presque tous les détails.
Le schéma suivant, chapi.doc est un exemple de nom pour la documentation à traduire ;
XX.doc est le même document traduit dans la langue XX tandis que doc.XX.po est le
catalogue de traduction de ce document dans la langue XX. Les responsables de la
documentation auront principalement la charge de chapi.doc (qui peut être une page de
manuel, un document XML, un fichier AsciiDoc, etc.) ; les équipes de traduction seront
principalement concernées par le fichier PO, tandis que seul le fichier XX.doc sera
publié.
Les transitions entre crochets telles que "[po4a met à jour le po]" représentent
l'exécution d'un outil po4a, tandis que les transitions entre accolades telles que "{mise
à jour de chapi.doc}" représentent une modification manuelle des fichiers du projet.
chapi.doc
|
V
+<----------+<--------------------+----------------------->+
: | | :
{traduction} | { mise à jour de chapi.doc } :
: | | :
XX.doc | V V
(optionnel) | chapi.doc ------------------>+
: | (nouveau) |
V V | |
[po4a-gettextize] doc.XX.po --->+ | |
| (vieux) | | |
| ^ V V |
| | [po4a met à jour le po] |
V | | |
traduction.pot | V |
| | doc.XX.po |
| | (correspondances) |
| | | |
{traduction} | | |
| | V |
| | {modifications manuelles} |
| | | |
V | V V
doc.XX.po --------->+<------- doc.XX.po addendum chapi.doc
(initial) (à jour) (optionnel) (à jour)
: | | |
: V | |
+-------------------------> + | |
| | |
V V V
+----------->+<------------+
|
V
[po4a met à jour les traductions]
|
V
XX.doc
(à jour)
Là encore, ce schéma est particulièrement compliqué. Consultez po4a(1) pour un aperçu
simplifié.
La partie à gauche montre comment po4a-gettextize(1) peut être utilisé pour convertir un
projet de traduction existant en infrastructure po4a. Ce script prend un document original
et son équivalent traduit, et essaie de créer le fichier PO correspondant. Une telle
conversion manuelle est assez lourde (voir la documentation po4a-gettextize(1) pour en
savoir plus), mais elle n'est nécessaire qu'une seule fois pour convertir vos traductions
existantes. Si vous n'avez aucune traduction à convertir, vous pouvez oublier cela et vous
concentrer sur la partie droite du schéma.
En haut à droite est décrit ce qui relève de l’auteur du document d’origine, la mise à
jour de la documentation. Au milieu à droite sont décrites les mises à jour automatisées
des fichiers à traduire : les nouvelles chaines sont extraites et comparées avec la
traduction existante. La traduction existante est utilisée pour les parties n’ayant pas
changé, alors que celles qui ont été en partie modifiées sont également associées à leur
ancienne traduction, mais avec un marquage « fuzzy » indiquant que la traduction doit être
mise à jour. Un contenu nouveau ou fortement modifié est laissé non traduit.
Ensuite, le bloc modifications manuelles décrit l'action des équipes de traduction qui
modifient les fichiers PO pour fournir des traductions à chaque chaine et paragraphe
d'origine. Cela peut être fait en utilisant un éditeur spécifique tel que GNOME
Translation Editor, Lokalize de KDE ou poedit, ou en utilisant une plateforme de
localisation en ligne telle que weblate ou pootle. Le résultat de la traduction est un
ensemble de fichiers PO, un par langue. Référez-vous à la documentation de gettext pour en
savoir plus.
La partie inférieure de la figure montre comment po4a crée un document source traduit à
partir du document original chapi.doc et du catalogue de traduction doc.XX.po mis à jour
par les équipes de traduction. La structure du document est réutilisée, tandis que le
contenu original est remplacé par son équivalent traduit. En option, un addendum peut être
utilisé pour ajouter du texte supplémentaire à la traduction. Ceci est souvent utilisé
pour ajouter le nom des membres des équipes de traduction au document final. Voir ci-
dessous pour en savoir plus.
L'appel à po4a met à jour automatiquement aussi bien les fichiers à traduire que les
fichiers traduits.
Commencer un nouveau projet de traduction
Si vous partez de zéro, il vous suffit d'écrire un fichier de configuration pour po4a pour
commencer. Des modèles appropriés sont créés pour les fichiers manquants, ce qui permet à
vos contributeurs de traduire votre projet dans leur langue. Consultez po4a(1) pour un
tutoriel de démarrage rapide et pour tous les détails.
Si vous disposez d'une traduction existante, c'est-à-dire d'un fichier de documentation
qui a été traduit manuellement, vous pouvez intégrer son contenu dans votre flux de
travail po4a en utilisant po4a-gettextize. Cette tâche est un peu lourde (comme décrit
dans la page de man de l'outil), mais une fois que votre projet est mis en adaptation au
flux de travail po4a, tout sera mis à jour automatiquement.
Mettre à jour les traductions et les documents
Une fois configuré, il suffit d'invoquer po4a pour mettre à jour à la fois les fichiers PO
de traduction et les documents traduits. Vous pouvez passer l'argument "--no-translations"
à po4a pour ne pas mettre à jour les traductions (et donc juste mettre à jour les fichiers
PO) ou l'argument "--no-update" pour ne pas mettre à jour les fichiers PO (et donc juste
mettre à jour les traductions). Cela correspond à peu près aux scripts individuels
po4a-updatepo et po4a-translate qui sont maintenant obsolètes (voir «Pourquoi les scripts
individuels sont-ils obsolètes» dans la FAQ ci-dessous).
Utiliser les addendas pour ajouter du texte supplémentaire aux traductions
Ajouter un nouveau texte à la traduction est probablement la seule chose qui soit plus
facile à long terme lorsque vous traduisez des fichiers manuellement :). Cela se produit
lorsque vous souhaitez ajouter une section supplémentaire au document traduit, ne
correspondant à aucun contenu du document d'origine. Le cas d'usage classique consiste à
mentionner l'équipe de traduction et à indiquer comment signaler les problèmes spécifiques
à la traduction.
Avec po4a, vous devez spécifier les fichiers addendum, qui peuvent être conceptuellement
considérés comme des correctifs appliqués au document localisé après traitement. Chaque
addendum doit être fourni dans un fichier séparé, dont le format est cependant très
différent des correctifs classiques. La première ligne est une ligne d'en-tête,
définissant le point d'insertion de l'addendum (avec une syntaxe malheureusement obscure -
voir ci-dessous) tandis que le reste du fichier est ajouté textuellement à la position
déterminée.
La ligne d'entête doit commencer par la chaine PO4A-HEADER:, suivie d'une liste de champs
clé=valeur séparés par des points-virgules.
Par exemple, l'entête suivant déclare un addendum qui doit être placé à la toute fin de la
traduction.
PO4A-HEADER: mode=eof
Les choses sont plus complexes lorsque vous souhaitez ajouter votre contenu supplémentaire
au milieu du document. L'entête suivant déclare un addendum qui doit être placé après la
section XML contenant la chaine "À propos de ce document" en traduction.
PO4A-HEADER: position=À propos de ce document; mode=after; endboundary=</section>
En pratique, en essayant d'appliquer un addendum, po4a recherche la première ligne
correspondant à l'argument "position" (cela peut être une expression régulière regexp).
N'oubliez pas que po4a considère ici le document traduit. Cette documentation est en
anglais, mais votre ligne devrait probablement se lire comme suit si vous souhaitez que
votre addendum s'applique à la traduction française du document.
PO4A-HEADER: position=À propos de ce document; mode=after; endboundary=</section>
Une fois que la "position" est trouvée dans le document cible, po4a recherche la ligne
suivante après la "position" qui correspond au "endboundary" fourni. L'addendum est ajouté
juste après cette ligne (car nous avons fourni un endboundary, c'est-à-dire une limite
terminant la section courante).
Le même effet pourrait être obtenu avec l'entête suivant, qui est équivalent :
PO4A-HEADER: position=À propos de ce document; mode=after; beginboundary=<section>
Ici, po4a recherche la première ligne correspondant à "<section>" après la ligne
correspondant à "À propos de ce document" dans la traduction, et ajoute l'addendum avant
cette ligne puisque nous avons fourni un beginboundary, c'est-à-dire une limite marquant
le début de la section suivante. Donc, cette ligne d'entête impose de placer l'addendum
après la section contenant "À propos de ce document", et d'informer po4a qu'une section
commence par une ligne contenant la balise "<section>". C'est équivalent à l'exemple
précédent, car ce que vous voulez vraiment, c'est ajouter cet addendum soit après
"</section>" soit avant "<section.".
Vous pouvez également définir le mode insertion sur la valeur "before", avec une
sémantique similaire : combiner "mode=before" avec un "endboundary" mettra l'addendum
juste après la limite correspondante, qui est la dernière limite potentielle avant la
"position". La combinaison de "mode=before" avec un "beginboundary" placera l'addendum
juste avant la limite correspondante, c'est-à-dire la dernière limite potentielle avant la
"position".
Mode | Type de limite | Limite utilisée | Point d'insertion par rapport à la limite
========|===============|========================|=========================================
'before'| 'endboundary' | dernière avant la 'position' | Juste après la limite
'before'|'beginboundary'| dernière avant la 'position' | Juste avant la limite
'after' | 'endboundary' | première après la 'position' | Juste après la limite
'after' |'beginboundary'| première après la 'position' | Juste avant la limite
'eof' | (rien) | sans objet | Fin de fichier
Trucs et astuces sur les addendas
• Gardez à l’esprit que ce sont des expressions rationnelles. Par exemple, si vous
voulez correspondre à la fin d’une section nroff terminant par la ligne ".fi",
n’utilisez pas ".fi" comme valeur pour endboundary, parce que cala correspondra
également à "ce[ fi]chier", ce qui n’est évidemment pas ce que vous voulez. La valeur
du champ endboundary dans ce cas est "^\.fi$".
• Les espaces SONT importants dans le contenu de la "position" et des limites. Donc les
deux lignes suivantes sont différentes. La seconde ne sera trouvé que s'il y a
suffisamment d'espaces de fin dans le document traduit.
PO4A-HEADER: position=À propos de ce document; mode=after; beginboundary=</section>
PO4A-HEADER: position=À propos de ce document; mode=after; beginboundary=<section>
• Bien que cette recherche contextuelle puisse être considérée comme opérant à peu près
sur toutes les lignes du document traduit, elle opère en fait sur la chaîne de
caractères des données internes à po4a. Cette chaîne de caractères des données
internes peut être aussi bien un texte s'étendant sur un paragraphe et contenant
plusieurs lignes, ou bien peut être un marqueur XML isolé. Le point d'insertion exact
de l'addendum doit donc être placé avant ou après cette chaîne de caractères des
données internes et ne peut pas être à l'intérieur de celle-ci.
• Passez l'argument "-vv" à po4a pour comprendre comment les addendas sont ajoutés à la
traduction. Il peut également être utile d'exécuter po4a en mode débogage pour voir la
chaîne de données interne réelle lorsque votre addendum ne s'applique pas.
Exemples d'addenda
• Si vous voulez ajouter quelque chose après la section nroff suivante :
.SH "AUTEURS"
Vous devez sélectionner une approche en deux étapes en définissant mode=after.
D'abord, vous devez restreindre la recherche à la ligne après AUTHORS avec l'argument
de position. Ensuite, vous devez faire correspondre le début de la section suivante
(c'est-à-dire, ^\.SH) avec l'argument de beginboundary. C'est-à-dire :
PO4A-HEADER:mode=after;position=AUTEURS;beginboundary=\.SH
• Si vous voulez ajouter quelque chose juste après une ligne donnée (par exemple après «
Copyright Bidule »), utilisez une position correspondant à cette ligne, un mode=after
et renseignez un champ beginboundary correspondant à n’importe quelle ligne.
PO4A-HEADER:mode=after;position=Copyright Tralala, 2004;beginboundary=^
• Si vous voulez ajouter quelque chose à la fin du document, donnez une position
correspondant à n’importe quelle ligne du document (mais à une seule ligne, puisque
po4a n’acceptera pas que la position ne corresponde pas à une ligne unique), et donnez
un champ endboundary ne correspondant à aucune ligne. N’utilisez pas de chaîne simple,
comme "EOF", mais préférez-en une qui a une chance moindre de se trouver dans votre
document.
PO4A-HEADER:mode=after;position=À propos de ce document;beginboundary=FausseLimitePo4a
Exemple plus détaillé
Document original (au format POD :
|=head1 NOM
|
|bêta - un programme un peu bêta
|
|=head1 AUTEUR
|
|moi
Voici maintenant un addendum qui s’assure qu’une section est ajoutée à la fin du fichier
pour indiquer le nom des membres des équipes de traduction.
|PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head
|
|=head1 TRADUCTEUR
|
|encore moi
|
Pour placer l’addendum avant l’AUTEUR (section nommée AUTHOR dans le document original),
utilisez l’en-tête suivant :
PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1
Ceci fonctionne parce que la première ligne correspondant à l’expression rationnelle
donnée dans le champ beginboundary "/^=head1/" après la section « NOM » (correspondant à
la section « NAME » dans le document original), est celle indiquant les auteurs. De cette
façon, l’addendum est placé entre les deux sections. Notez que si une autre section est
ajoutée entre NOM et AUTEUR, po4a ajoutera l’addendum par erreur avant la nouvelle
section.
Pour éviter cela, vous pouvez utiliser mode=before :
PO4A-HEADER:mode=before;position=^=head1 AUTEUR
Comment ça marche ?
Cette section vous donne un bref aperçu des rouages internes de po4a afin que vous vous
sentiez plus à même de nous aider à le maintenir et l’améliorer. Elle peut également vous
permettre de comprendre pourquoi cela ne fait pas ce que vous souhaitez et corriger vos
problèmes par vous-même.
TransTractors et l'architecture du projet
Au cœur du projet po4a se trouve la classe Locale::Po4a::TransTractor(3pm) qui est
l’ancêtre commun à tous les analyseurs de po4a. Ce nom étrange provient du fait qu'elle
est à la fois chargée de la traduction et de l’extraction des chaînes du document.
Plus formellement, il prend un document à traduire et un fichier PO contenant les
traductions en entrée et produit en sortie deux autres fichiers : un autre fichier PO
(résultant de l’extraction des chaînes à traduire du document d’entrée), et un document
traduit (avec la même structure que le document d’entrée, mais dont toutes les chaînes à
traduire ont été remplacées par leur traduction donnée par le PO fournit en entrée). Voici
une représentation graphique de tout ceci :
document en entrée --\ /---> document en sortie
\ TransTractor:: / (traduit)
+-->-- parse() --------+
/ \
PO en entrée --------/ \---> PO en sortie
(extrait)
Cette forme d’os est le cœur de l’architecture de po4a. Si vous fournissez l'entrée mais
ignorez la sortie PO, vous obtenez po4a-translate. Si vous ignorez la sortie document à la
place, vous obtenez po4a-updatepo. <po4a> utilise un premier TransTractor pour obtenir un
fichier de sortie POT mis à jour (en ignorant les documents en sortie), appelle msgmerge
-U pour mettre à jour les fichiers PO de traduction sur le disque et crée un second
TransTractor à l'aide de ces fichiers PO mis à jour pour mettre à jour les documents de
sortie. En d'autres termes, po4a vous offre une solution unique pour mettre à jour ce qui
doit l'être, à l'aide d'un seul fichier de configuration.
po4a-gettextize utilise également deux TransTractors, mais d'une autre manière : il
construit un TransTractor par langue, puis construit un nouveau fichier PO en utilisant
les msgids du document originel en tant que msgids, et les msgids du document traduit en
tant que msgstrs. Il faut faire très attention à ce que les chaînes qui sont ainsi mises
en correspondance correspondent réellement, comme indiqué dans po4a-gettextize(1).
Analyseurs spécifiques aux formats
Tous les analyseurs de format sont implémentés au-dessus de TransTractor. Certains sont
très simples, comme les analyseurs Text, Markdown et AsciiDoc. Ils chargent les lignes une
par une en utilisant TransTractor::shiftline() et accumulent le contenu des paragraphes ou
autre. Une fois qu'une chaîne est complètement analysée, l'analyseur utilise
TransTractor::translate() pour (1) ajouter cette chaîne au fichier PO de sortie et (2)
obtenir la traduction du fichier PO d'entrée. L'analyseur pousse ensuite le résultat vers
le fichier de sortie à l'aide de TransTractor::pushline().
D'autres analyseurs sont plus complexes, car ils s'appuient sur un analyseur externe pour
analyser le document d'entrée. Les analyseurs Xml, HTML, SGML et Pod sont construits sur
les analyseurs SAX. Ils déclarent des rappels à des événements tels que "J'ai trouvé un
nouveau titre dont le contenu est ceci" pour mettre à jour le document de sortie et les
fichiers POT de sortie en fonction du contenu d'entrée en utilisant
TransTractor::translate() et TransTractor::pushline(). L'analyseur Yaml est similaire,
mais différent : il sérialise une structure de données produite par l'analyseur
YAML::Tiny. C'est pourquoi le module Yaml de po4a ne parvient pas à déclarer les lignes de
référence : l'emplacement de chaque chaîne dans le fichier d'entrée n'est pas conservé par
l'analyseur, de sorte que nous ne pouvons fournir que "$filename:1" comme emplacement de
la chaîne. Les analyseurs orientés SAX utilisent des globaux et d'autres astuces pour
enregistrer le nom de fichier et les numéros de ligne des références.
Un problème spécifique est lié à l'encodage des fichiers et aux marqueurs BOM. Les
analyseurs simples peuvent ignorer ce point qui est géré par TransTractor::read() (utilisé
en interne pour obtenir les lignes d'un document d'entrée), mais les modules qui
s'appuient sur un analyseur externe doivent s'assurer que tous les fichiers sont lus avec
une couche de décodage PerlIO appropriée. Le plus simple est d'ouvrir le fichier
vous-même, et de fournir un identificateur de fichier ou directement la chaine complète à
votre analyseur externe. Consultez Pod::read() et Pod::parse() pour un exemple. Le contenu
lu par le TransTractor est ignoré, mais un nouvel identificateur de fichier est transmis à
l'analyseur externe. La partie importante est le mode "<"<:encoding($charset)""> qui est
transmis à la fonction perl open().
Objets Po
La classe Locale::Po4a::Po(3pm) a la tâche de charger et d'utiliser les fichiers PO et
POT. En principe, vous pouvez lire un fichier, ajouter des entrées, obtenir des
traductions avec la méthode gettext(), puis écrire le PO dans un fichier. Les fonctions
plus avancées telles que la fusion d'un fichier PO avec un fichier POT ou la validation
d'un fichier sont respectivement déléguées à msgmerge et msgfmt.
Contribuer à po4a
Même si vous n'avez jamais contribué à un projet libre, bienvenue ! Nous sommes prêts à
vous aider et à vous encadrer. po4a est aujourd'hui mieux maintenu par sa communauté.
Comme nous manquons d'aide, nous essayons de rendre le projet accueillant en améliorant la
documentation et les tests automatiques afin de vous rendre la contribution au projet plus
facile. Consultez le fichier CONTRIBUTING.md pour en savoir plus.
Projets open-source utilisant po4a
Voici une liste très partielle des projets qui utilisent po4a en production pour leur
documentation. Si vous souhaitez ajouter votre projet à la liste, envoyez-nous simplement
un e-mail (ou une demande de fusion (Merge Request)).
• adduser (man) : outil de gestion des utilisateurs et des groupes.
• apt (man, docbook) : Gestionnaire de paquets Debian.
• aptitude (docbook, svg) : gestionnaire de paquets en mode commande pour Debian
• site internet F-Droid <https://gitlab.com/fdroid/fdroid-website> (markdown) :
catalogue de logiciels libres pour la plateforme Android.
• git <https://github.com/jnavila/git-manpages-l10n> (asciidoc) : système de contrôle de
version distribué pour suivre les modifications du code source.
• manuel Linux <https://salsa.debian.org/manpages-l10n-team/manpages-l10n> (man)
Ce projet fournit une infrastructure pour traduire de nombreuses pages de manuel dans
différents langages, prête à être intégrée dans plusieurs distributions majeures (Arch
Linux, Debian et dérivés, Fedora).
• Stellarium <https://github.com/Stellarium/stellarium> (HTML) : un planétarium open
source gratuit pour votre ordinateur. po4a est utilisé pour traduire les descriptions
des objets célestes.
• Jamulus <https://jamulus.io/> (markdown, yaml, HTML) : une application FOSS pour le
brouillage en ligne en temps réel. La documentation du site web est maintenue en
plusieurs langues à l'aide de po4a.
• Autres éléments à trier : <https://gitlab.com/fdroid/fdroid-website/>
<https://github.com/fsfe/reuse-docs/pull/61>
FAQ
Comment prononcer po4a ?
Personnellement, je le prononce comme pouah <https://en.wiktionary.org/wiki/pouah>, qui
est une interjection française équivalente à l'anglais yuck :) J'ai peut-être un étrange
sens de l'humour :)
Pourquoi les scripts individuels sont-ils obsolètes ?
En effet, po4a-updatepo et po4a-translate sont dépréciés au profit de po4a. La raison en
est que, bien que po4a puisse être utilisé comme un remplacement direct de ces scripts, on
y trouve beaucoup de duplication de code. Les scripts individuels font environ 150 lignes
de code alors que le programme po4a en fait 1200, ils font donc beaucoup de choses en plus
des éléments internes communs. La duplication du code entraîne l'apparition de bogues dans
les deux versions et nécessite des corrections doubles. On peut voir une telle duplication
dans les bogues #1022216 de Debian et le problème #442 sur GitHub qui avaient exactement
la même correction, avec une dans po4a et l'autre dans po4a-updatepo.
À long terme, j'aimerais abandonner les scripts individuels et ne maintenir qu'une seule
version de ce code. Ce qui est sûr, c'est que les scripts individuels ne seront plus
améliorés, et que seul po4a bénéficiera de nouvelles fonctionnalités. Ceci étant dit, la
dépréciation n'est pas immédiate. Je prévois de conserver les scripts individuels aussi
longtemps que possible, et au moins jusqu'en 2030. Cependant, si votre projet utilise
encore po4a-updatepo et po4a-translate à cette date, vous pourriez avoir un problème.
Nous pourrions également annuler la dépréciation de ces scripts à un moment donné, si une
réécriture élimine la duplication du code. Si vous avez des idées (ou mieux : un
correctif), votre aide est la bienvenue.
Qu’en est-il des autres outils de traduction de documentation utilisant gettext ?
Il y en a quelques-uns. Voici une liste potentiellement incomplète, et d’autres outils
arrivent à l’horizon.
poxml
C’est l’outil développé au sein du projet KDE pour gérer les XML DocBook. C’est à
notre connaissance le premier programme qui a extrait des chaînes à traduire d’une
documentation pour les mettre dans un fichier PO, et les réinjecter ensuite dans le
document après la traduction.
Il ne peut gérer que le format XML, avec une DTD particulière. Je n’aime pas beaucoup
la façon dont les listes sont gérées, elles sont rassemblées en un seul gros msgid.
Lorsque la liste est de taille importante, les éléments sont assez durs à gérer.
po-debiandoc
Ce programme écrit par Denis Barbier est un précurseur du module SGML de po4a, qui le
remplace plus ou moins. Comme son nom l’indique, il ne gère que la DTD DebianDoc, qui
est en voie d’extinction.
xml2po.py
Utilisé par l'équipe de documentation de GIMP depuis 2004, il fonctionne assez bien
même si, comme son nom l'indique, il ne fonctionne qu'avec des fichiers XML et
nécessite des makefiles spécialement configurés.
Sphinx
Le projet de documentation Sphinx utilise également gettext de manière intensive pour
gérer ses traductions. Malheureusement, il ne fonctionne que pour quelques formats de
texte, rest et markdown, bien qu'il soit peut-être le seul outil à faire cela en
gérant l'ensemble du processus de traduction.
Le principal avantage de po4a par rapport à eux est la facilité d’ajouter du contenu
additionnel (ce qui est encore plus difficile avec ces outils) et la possibilité de faire
une gettextisation.
RÉSUMÉ des avantages de l’approche basée sur gettext
• Les traductions ne sont pas stockées indépendamment de l’original, ce qui rend possible
la détection des parties à mettre à jour.
• Les traductions sont stockées dans des fichiers différents pour chaque langue, ce qui
évite les interférences entre équipes de traduction. Que ce soit pour la soumission de
rustines ou pour le choix d’un encodage.
• En interne, tout est basé sur gettext (mais po4a offre une interface simple qui ne
nécessite pas de comprendre comment tout marche en interne pour pouvoir l’utiliser). Ce
qui permet de ne pas réinventer la roue, et du fait de leur utilisation importante, nous
pouvons supposer qu’ils ont peu ou pas de bogue.
• Pour l’utilisation finale, rien ne change (à part que les documentations seront
probablement mieux maintenues :). La documentation distribuée reste la même.
• Il n’est pas nécessaire pour les membres des équipes de traduction d’apprendre une
nouvelle syntaxe et leur éditeur de fichier PO préféré (qui peut être le mode PO
d’Emacs, Lokalize ou Gtranslator) sera parfait.
• gettext permet d’obtenir facilement des statistiques sur ce qui a été fait, ce qui doit
être revu et mis à jour, et sur ce qu’il reste à faire. Vous trouverez des exemples à
ces adresses :
- https://docs.kde.org/stable5/en/kdesdk/lokalize/project-view.html
- http://www.debian.org/intl/l10n/
Mais tout n’est pas rose, et cette approche a aussi quelques désavantages que nous devons
gérer.
• Les addendas sont surprenants au premier abord.
• Il n’est pas possible d’adapter le texte traduit à votre goût, comme de décomposer ou
recomposer des paragraphes. Mais d’un autre côté, s’il s’agit d’un problème dans le
document original, celui-ci doit être signalé de toute façon.
• Même s’il a une interface simple, il reste un nouvel outil qu’il faudra apprendre à
maîtriser.
Un de mes rêves serait d’intégrer po4a à Gtranslator ou Lokalize. Lorsqu’un fichier de
documentation serait ouvert, ses chaînes seraient extraites automatiquement. Lors de
l’enregistrement, le fichier traduit + un fichier po seraient écrits sur le disque. Si
nous arrivions à faire un module pour MS Word (TM) (ou au moins pour le format RTF),
po4a pourrait même être utilisés dans le milieu de la traduction professionnelle.
VOIR AUSSI
• La documentation de l'outil tout-en-un que vous devriez utiliser : po4a(1).
• La documentation des scripts po4a individuels : po4a-gettextize(1), po4a-updatepo(1),
po4a-translate(1), po4a-normalize(1).
• Les scripts d'assistance supplémentaires : msguntypot(1), po4a-display-man(1),
po4a-display-pod(1).
• Les parsers de chaque format, en particulier pour consulter les options acceptées par
chacun d'entre eux : Locale::Po4a::AsciiDoc(3pm) Locale::Po4a::Dia(3pm),
Locale::Po4a::Guide(3pm), Locale::Po4a::Ini(3pm), Locale::Po4a::KernelHelp(3pm),
Locale::Po4a::Man(3pm), Locale::Po4a::RubyDoc(3pm), Locale::Po4a::Texinfo(3pm),
Locale::Po4a::Text(3pm), Locale::Po4a::Xhtml(3pm), Locale::Po4a::Yaml(3pm),
Locale::Po4a::BibTeX(3pm), Locale::Po4a::Docbook(3pm), Locale::Po4a::Halibut(3pm),
Locale::Po4a::LaTeX(3pm), Locale::Po4a::Pod(3pm), Locale::Po4a::Sgml(3pm),
Locale::Po4a::TeX(3pm), Locale::Po4a::Wml(3pm), Locale::Po4a::Xml(3pm).
• La mise en œuvre de l'infrastructure de base : Locale::Po4a::TransTractor(3pm)
(particulièrement important pour comprendre l'organisation du code),
Locale::Po4a::Chooser(3pm), Locale::Po4a::Po(3pm), Locale::Po4a::Common(3pm).
Consultez également le fichier CONTRIBUTING.md dans l'arborescence des sources.
AUTEURS
Denis Barbier <barbier,linuxfr.org>
Martin Quinson (mquinson#debian.org)
TRADUCTION
Martin Quinson (mquinson#debian.org)