po4a - Cadre de travail pour la traduction de documentations et autres documents
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.
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.
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 plus de détails.
- 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.
Voir Locale::Po4a::Pod pour plus de détails.
- 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)
- 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
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)
- 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 plus de détails.
- 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 plus de détails.
- 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 plus de détails.
- 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 plus de détails.
- Yaml (analyseur probablement stable)
- Un sur-ensemble 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 plus de détails.
- 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 plus de détails.
- 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 plus de détails.
- Ini (analyseur très expérimental)
- Format de fichier de configuration popularisé par
MS-DOS.
Voir Locale::Po4a::Ini pour plus de détails.
- 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.
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.
Most projects only require the features of
po4a-updatepo(1) and
po4a-translate(1), but these scripts proved to be cumbersome and error
prone to use. If the documentation to translate is split over several source
files, it is difficult to keep the PO files up to date and build the
documentation files correctly. As an answer, a all-in-one tool was provided:
po4a(1). This tool takes a configuration file describing the structure
of the translation project: the location of the PO files, the list of files to
translate, and the options to use, and it fully automates the process. When
you invoke
po4a(1), it both updates the PO files and regenerate the
translation files that need to. If everything is already up to date,
po4a(1) does not change any file.
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).
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.
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.
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.
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.
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
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.
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.
- •
- Autres éléments à trier :
<https://gitlab.com/fdroid/fdroid-website/>
<https://github.com/fsfe/reuse-docs/pull/61>
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 :)
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 gettextization.
- •
- 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.
- •
- 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.
Denis Barbier <barbier,linuxfr.org>
Martin Quinson (mquinson#debian.org)
Martin Quinson (mquinson#debian.org)