Provided by: po4a_0.66-1_all 
NOM
po4a - Cadre de travail pour la traduction de documentations et autres documents
Introduction
po4a (PO for anything = PO pour tout) 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 les utilisateurs potentiels qui
envisagent d'utiliser cet outil et sur les curieux qui souhaitent comprendre pourquoi les choses sont
comme elles sont.
Pourquoi po4a ?
Le concept des logiciels à sources ouverts est de rendre la technologie réellement disponible pour tout
le monde. Mais, la licence n’est pas la seule préoccupation, un logiciel ouvert est inutile pour des
utilisateurs non anglophones. En conséquence, nous avons encore du travail pour rendre le logiciel
disponible pour tous.
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 ouverts sont réllement très bien traduits en utilisant la suite d’outils
gettext. Ces outils sont utilisés pour extraire les chaînes à traduire d’un programme et pour présenter
les chaînes à traduire dans un format standardisé (appelés fichiers PO ou catalogue de traduction). Tout
un écosystème d’outils a émergé pour aider les traducteurs à traduire réellement ces fichiers PO. Le
résultat est alors utilisé par gettext à l'exécution pour afficher les messages traduits aux
utilisateurs.
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 traducteurs. Si elle est effectuée
manuellement, cette tâche est désagréable et sujette aux erreurs.
Les traductions obsolètes sont souvent pires que pas de traduction du tout. Les utilisateurs finaux
peuvent être trompés par la documentation décrivant un ancien comportement du programme. De plus, ils ne
peuvent pas interagir directement avec les mainteneurs car ils ne parlent pas anglais. De plus, le
mainteneur ne peut pas résoudre le problème car il ne connaît pas toutes les langues dans lesquelles sa
documentation est traduite. Ces difficultés, souvent causées par un mauvais outillage, peuvent miner la
motivation des traducteurs bénévoles, aggravant encore le problème.
Le but du projet po4a est de faciliter le travail des traducteurs de documentation. En particulier, il
rend les traductions de documentation maintenables.
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 traducteurs sous forme de catalogues de
traduction PO. Les traducteurs peuvent exploiter les outils classiques de gettext pour suivre le travail
à faire, collaborer et s'organiser en équipes. po4a injecte ensuite les traductions directement dans la
structure de la documentation pour produire des fichiers source 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 les utilisateurs finaux ne voient jamais une traduction obsolète
dans la documentation.
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 entraîneraient 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.
See Locale::Po4a::AsciiDoc for details.
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 du traducteur
jusqu'à ce que vous utilisiez po4a.
See Locale::Po4a::Pod for details.
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. Veuillez consulter
Locale::Po4a::Sgml(3pm) pour plus de détails.
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)
The Text format is the base format for many formats that include long blocks of text, including
Markdown, fortunes, YAML front matter section, debian/changelog, and 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 plus de détails.
xml and XHMTL (analyseur probablement stable)
Le format XML est à la base de beaucoup de formats pour la documentation.
À ce jour, la DTD DocBook (veuillez consulter Locale::Po4a::Docbook(3pm) pour plus de détails) et
XHTML sont pris en charge par po4a.
BibTex (analyseur probablement stable)
The BibTex format is used alongside LaTex for formatting lists of references (bibliographies).
See Locale::Po4a::BibTex for details.
DocBook (analyseur probablement stable)
A XML-based markup language that uses semantic tags to describe documents.
See Locale::Po4a:Docbook for greater details.
Guide XML (analyseur probablement stable)
A XML documentation format. This module was developed specifically to help with supporting and
maintaining translations of Gentoo Linux documentation up until at least March 2016 (Based on the
Wayback Machine). Gentoo have since moved to the DevBook XML format.
See Locale::Po4a:Guide for greater details.
Wml (analyseur probablement stable)
The Web Markup Language, do not mixup WML with the WAP stuff used on cell phones. This module relies
on the Xhtml module, which itself relies on the XmL module.
See Locale::Po4a::Wml for greater details.
Yaml (analyseur probablement stable)
A strict superset of JSON. YAML is often used as systems or configuration projects. YAML is at the
core of Red Hat's Ansible.
See Locale::Po4a::Yaml for greater details.
RubyDoc (analyseur probablement stable)
The Ruby Document (RD) format, originally the default documentation format for Ruby and Ruby projects
before converted to RDoc in 2002. Though apparently the Japanese version of the Ruby Reference Manual
still use RD.
See Locale::Po4a::RubyDoc for greater details.
Halibut (analyseur très expérimental)
A documentation production system, with elements similar to TeX, debiandoc-sgml, TeXinfo, and others,
developed by Simon Tatham, the developer of PuTTY.
See Locale::Po4a:Halibut for greater details.
Ini (analyseur très expérimental)
Configuration file format popularized by MS-DOS.
See Locale::Po4a::Ini for greater details.
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ébut. Veuillez nous envoyer des rapports de bogue ou des demandes de
nouvelle fonctionnalité.
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 simple à 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
Historiquement, po4a a été construit autour de quatre scripts, chacun remplissant une tâche spécifique.
po4a-gettextize(1) aide à amorcer les traductions et éventuellement à convertir les projets de traduction
existants en po4a. po4a-updatepo(1) reporte les modifications apportées à la documentation d'origine dans
les fichiers po correspondants. po4a-translate(1) construit le fichier source traduit à partir du fichier
d'origine et du fichier PO correspondant. De plus, po4a-normalize(1) est surtout utile pour déboguer les
analyseurs po4a, car il produit un document non traduit à partir de l'original. Il permet de repérer plus
facilement les problèmes introduits par le processus d'analyse.
La plupart des projets n'ont besoin que des fonctionnalités de po4a-updatepo(1) et po4a-translate(1),
mais ces scripts se sont avérés encombrants et sujets aux erreurs. Si la documentation à traduire est
répartie sur plusieurs fichiers source, il est difficile de maintenir les fichiers PO à jour et de créer
correctement les fichiers de documentation. En guise de réponse, un outil tout-en-un a été fourni :
po4a(1). Cet outil prend un fichier de configuration décrivant la structure du projet de traduction :
l'emplacement des fichiers PO, la liste des fichiers à traduire et les options à utiliser, et il
automatise entièrement le processus. Lorsque vous appelez po4a(1), il met à jour les fichiers PO et
régénère les fichiers de traduction qui en ont besoin. Si tout est déjà à jour, po4a(1) ne modifie aucun
fichier.
Le reste de cette section donne un aperçu de la façon d'utiliser l'interface des scripts de po4a. La
plupart des utilisateurs préféreront probablement utiliser l'outil tout-en-un, qui est décrit dans la
documentation de po4a(1).
Résumé graphique des scripts po4a
Le schéma suivant donne un aperçu de la façon dont chaque script po4a peut être utilisé. Ici, master.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
auteurs de la documentation seront principalement concernés par master.doc (qui peut être une page de
manuel, un document XML, un fichier asciidoc ou similaire) ; les traducteurs seront principalement
concernés par le fichier PO, tandis que les utilisateurs finaux ne verront que le fichier XX.doc.
maître.doc
|
V
+<-----<----+<-----<-----<--------+------->-------->-------+
: | | :
{traduction} | { mise à jour de maître.doc } :
: | | :
XX.doc | V V
(optionnel) | maître.doc ->-------->------>+
: | (nouveau) |
V V | |
[po4a-gettextize] doc.XX.po--->+ | |
| (ancien) | | |
| ^ V V |
| | [po4a-updatepo] |
V | | V
traduction.pot ^ V |
| | doc.XX.po |
| | (fuzzy) |
{ traduction } | | |
| ^ V V
| | {édition manuelle} |
| | | |
V | V V
doc.XX.po --->---->+<---<-- doc.XX.po addendum maître.doc
(initial) (à jour) (optionnel) (à jour)
: | | |
: V | |
+----->----->----->------> + | |
| | |
V V V
+------>-----+------<------+
|
V
[po4a-translate]
|
V
XX.doc
(à jour)
Ce schéma est compliqué, mais en pratique, seule la partie de droite (impliquant po4a-updatepo(1) et
po4a-translate(1)) est utilisée une fois le projet installé et configuré.
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 plus de détails), 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 est relève de l’auteur du document d’origine, la mise à jour de la
documentation. Au milieu à droite sont décrites les actions automatisées par po4a-updatepo(1). Les
nouvelles chaînes 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, l'étape manual editing (= édition manuelle) décrit l'action des traducteurs, qui modifient les
fichiers PO pour fournir des traductions à chaque chaîne 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. Veuillez vous référer à la documentation de
gettext pour plus de détails.
La partie inférieure de la figure montre comment po4a-translate(1) crée un document source traduit à
partir du document original master.doc et du catalogue de traduction doc.XX.po mis à jour par les
traducteurs . 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 du traducteur au document final. Voir ci-
dessous pour plus de détails.
Comme indiqué précédemment, le programme po4a(1) combine les effets des scripts séparés, mettant à jour
les fichiers PO et le document traduit en un seul appel. La logique sous-jacente reste la même.
Commencer une nouvelle traduction
Si vous utilisez po4a(1), il n'y a pas d'étape spécifique pour démarrer une traduction. Il vous suffit de
lister les langues dans le fichier de configuration et les fichiers PO manquants sont automatiquement
créés. Naturellement, le traducteur doit alors fournir des traductions pour chaque contenu utilisé dans
vos documents. po4a(1) crée également un fichier POT, qui est un fichier modèle PO. Les traducteurs
potentiels peuvent traduire votre projet dans une nouvelle langue en renommant ce fichier et en
fournissant les traductions dans leur langue.
Si vous préférez utiliser les scripts individuels séparément, vous devez utiliser po4a-gettextize(1)
comme suit pour créer le fichier POT. Ce fichier peut ensuite être copié dans XX.po pour initialiser une
nouvelle traduction.
$ po4a-gettextize --format <format> --master <maître.doc> --po <traduction.pot>
Le document maître est utilisé en entrée, tandis que le fichier POT est la sortie de ce processus.
Intégrer les modifications du document d'origine
Le script à utiliser pour cela est po4a-updatepo(1) (veuillez vous référer à sa documentation pour plus
de détails) :
$ po4a-updatepo --format <format> --master <nouveau_maître.doc> --po <ancien.XX.po>
Le document maître est utilisé en entrée, tandis que le fichier PO est mis à jour : il est utilisé à la
fois en entrée et en sortie.
Générer un document traduit
Une fois que la traduction est effectuée, il faut générer la documentation traduite et la distribuer avec
l’original. Pour cela, utilisez po4a-translate(1) de la façon suivante :
$ po4a-translate --format <format> --master <maître.doc> --po <doc.XX.po> --localized <XX.doc>
Les fichiers maître et PO sont utilisés en entrée, tandis que le fichier traduit est la sortie de ce
processus.
Utiliser les addenda 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 à donner des crédits à 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'en-tête doit commencer par la chaîne PO4A-HEADER:, suivie d'une liste de champs clé=valeur
séparés par des points-virgules.
Par exemple, l'en-tê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'en-tête suivant déclare un addendum qui doit être placé après la section XML contenant la
chaîne "About this document" en traduction.
PO4A-HEADER: position=Au sujet de…; 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'en-tête suivant, qui est équivalent :
PO4A-HEADER: position=Au sujet de…; mode=after; beginboundary=<section>
Ici, po4a recherche la première ligne correspondant à "<section"> après la ligne correspondant à "About
this 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'en-tête impose de placer l'addendum après la section contenant "About this 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 addenda
• Gardez à l’esprit que ce sont des expressions rationnelle. 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 addenda 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=Au sujet de…;beginboundary=FausseLimitePo4a
Exemple plus détaillé
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 ajoutée à la fin du fichier pour indiquer le
traducteur.
|PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head
|
|=head1 TRADUCTEUR
|
|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.
L’architecture po4a est orientée objet. La classe Locale::Po4a::TransTractor(3pm) est l’ancêtre commun à
tous les analyseurs de po4a. Ce nom étrange provient du fait qu’il est à la fois chargé 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 entrée --\ /---> document sortie
\ TransTractor:: / (traduit)
+-->-- parse() --------+
/ \
PO entrée --------/ \---> PO sortie
(extrait)
Cette forme d’os est le cœur de l’architecture de po4a. Sans le fichier PO en entrée et le document en
sortie, cela donne po4a-gettextize. Si vous fournissez les deux entrées et ignorez le PO de sortie, vous
aurez po4a-translate. Le po4a appelle deux fois TransTract et appelle msgmerge -U entre ces appels pour
fournir une solution unique à partir d’un seul fichier de configuration. Lisez
Locale::Po4a::TransTractor(3pm) pour plus d’informations.
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.
• Other item to sort out: <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 :)
Qu’en est-il des autres outils de traduction de documentation utilisant gettext ?
Il n’y en à notre connaissance que deux :
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.
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 gettextization.
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 traducteurs. 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 ça 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’utilisateur final, 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 traducteurs 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 addenda 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 arrivons à faire un module pour MS Word
(TM) (ou au moins pour le format RTF), des traducteurs professionnels pourraient même l’utiliser.
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). Veuillez également consulter 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)
Outils po4a 2022-01-02 PO4A(7)