
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 NOM

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

=head1 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.

=head1 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.

B<Le but du projet po4a est de faciliter le travail des traducteurs de
documentation>. En particulier, il rend les traductions de documentation
I<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
S<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 B<FAQ> plus bas dans ce document pour une
liste plus complète des avantages et inconvénients de cette approche.

=head2 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 :

=over 

=item 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 L<Locale::Po4a::Man(3pm)|Man> prend également en charge le format
mdoc, utilisé par les pages de manuel BSD (ils sont également assez courants
sous Linux).

=item 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.

=item pod (analyseur stable)

C’est le format pour la documentation en ligne de Perl (S<« Perl> Online
S<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.

=item 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. B<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 S<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 S<DTD SGML> inconnue sans modifier le code en
fournissant les informations nécessaires sur la ligne de commande. Veuillez
consulter L<Locale::Po4a::Sgml(3pm)> pour plus de détails.

=item 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 L<Locale::Po4a::LaTeX(3pm)|LaTeX> a été testé avec la
documentation de Python, un livre et avec quelques présentations.

=item 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, 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
L<Locale::Po4a::Text(3pm)|Text> pour plus de détails.

=item xml and XHMTL (analyseur probablement stable)

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

À ce jour, la S<DTD DocBook> (veuillez consulter L<Locale::Po4a::Docbook(3pm)>
pour plus de détails) et XHTML sont pris en charge par po4a.

=item 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 L<Locale::Po4a::Texinfo(3pm)|Texinfo> dans po4a en est
encore à ses début. Veuillez nous envoyer des rapports de bogue ou des
demandes de nouvelle fonctionnalité.

=item 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+ ou les diagrammes produits par l’outil dia. L’ajout d’un nouveau format
est souvent très simple, et consiste principalement à fournir un
interpréteur pour le format voulu. Veuillez consulter
L<Locale::Po4a::TransTractor(3pm)> pour plus d’informations à ce sujet.

=item 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.

=back

=head1 Utiliser po4a

Historiquement, po4a a été construit autour de quatre scripts, chacun
remplissant une tâche spécifique. L<po4a-gettextize(1)> aide à amorcer les
traductions et éventuellement à convertir les projets de traduction
existants en po4a. L<po4a-updatepo(1)> reporte les modifications apportées à
la documentation d'origine dans les fichiers po
correspondants. L<po4a-translate(1)> construit le fichier source traduit à
partir du fichier d'origine et du fichier PO correspondant. De plus,
L<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
L<po4a-updatepo(1)> et L<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 :
L<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 L<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, L<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
L<po4a(1)>.

=head2 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, F<master.doc> est un exemple de nom pour la documentation
à S<traduire ;> F<XX.doc> est le même document traduit dans la langue XX tandis
que F<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 F<master.doc> (qui peut être une page de manuel, un document XML, un
fichier asciidoc ou S<similaire) ;> les traducteurs seront principalement
concernés par le fichier PO, tandis que les utilisateurs finaux ne verront
que le fichier F<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 L<po4a-updatepo(1)> et L<po4a-translate(1)>) est utilisée une
fois le projet installé et configuré.

La partie à gauche montre comment L<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 L<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 L<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 I<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 B<GNOME Translation Editor>, B<Lokalize> de KDE
ou B<poedit>, ou en utilisant une plateforme de localisation en ligne telle
que B<weblate> ou B<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 L<po4a-translate(1)> crée
un document source traduit à partir du document original F<master.doc> et du
catalogue de traduction F<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 L<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.

=head2 Commencer une nouvelle traduction

Si vous utilisez L<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. L<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 L<po4a-gettextize(1)> comme suit pour créer le fichier POT. Ce
fichier peut ensuite être copié dans F<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.

=head2 Intégrer les modifications du document d'origine

Le script à utiliser pour cela est L<po4a-updatepo(1)> (veuillez vous
référer à sa documentation pour plus de S<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 à
S<jour :> il est utilisé à la fois en entrée et en sortie.

=head2 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
L<po4a-translate(1)> de la façon S<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.

=head2 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 B<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 I<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 B<PO4A-HEADER:>, suivie
d'une liste de champs I<clé>B<=>I<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 C<About this
document> en traduction.

=pod

 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 C<position> (cela peut être une expression
régulière regexp). N'oubliez pas que po4a considère ici le document
B<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 C<position> est trouvée dans le document cible, po4a
recherche la ligne suivante après la C<position> qui correspond au
C<endboundary> fourni. L'addendum est ajouté juste B<après> cette ligne (car
nous avons fourni un I<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 à C<<section>> après la
ligne correspondant à C<About this document> dans la traduction, et ajoute
l'addendum B<avant> cette ligne puisque nous avons fourni un
I<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 C<About this document>, et d'informer po4a qu'une section
commence par une ligne contenant la balise C<<section>>. C'est équivalent à
l'exemple précédent car ce que vous voulez vraiment, c'est ajouter cet
addendum soit après C</section>> soit avant C<<section>>.

Vous pouvez également définir le I<mode> insertion sur la valeur C<before>,
avec une sémantique similaire : combiner C<mode=before> avec un
C<endboundary> mettra l'addendum juste B<après> la limite correspondante,
qui est la dernière limite potentielle avant la C<position>. La combinaison
de C<mode=before> avec un C<beginboundary> placera l'addendum juste B<avant>
la limite correspondante, c'est-à-dire la dernière limite potentielle avant
la C<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

=head3 Trucs et astuces sur les addenda

=over 

=item 

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
C<.fi>, n’utilisez pas C<.fi> comme valeur pour B<endboundary>, parce que
cala correspondra également à C<ce[ fi]chier>, ce qui n’est évidemment pas
ce que vous voulez. La valeur du champ B<endboundary> dans ce cas est
C<^\.fi$>.

=item 

Les espaces SONT importants dans le contenu de la C<position> et des
limites. Donc les deux lignes suivantes B<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>

=item 

Bien que cette recherche contextuelle puisse être considérée comme opérant à
peu près sur toutes les lignes du document B<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 I<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.

=item 

Passez l'argument B<-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.

=back

=head3 Exemples d'addenda

=over 

=item 

Si vous voulez ajouter quelque chose après la section nroff S<suivante :>

  .SH "AUTEURS"

Vous devez sélectionner une approche en deux étapes en définissant
B<mode=after>. D'abord, vous devez restreindre la recherche à la ligne après
B<AUTHORS> avec l'argument de B<position>. Ensuite, vous devez faire
correspondre le début de la section suivante (c'est-à-dire, B<^\.SH>) avec
l'argument de B<beginboundary>. C'est-à-dire :

 PO4A-HEADER:mode=after;position=AUTEURS;beginboundary=\.SH

=item 

Si vous voulez ajouter quelque chose juste après une ligne donnée (par
exemple après « Copyright Bidule »), utilisez une B<position> correspondant
à cette ligne, un B<mode=after> et renseignez un champ B<beginboundary>
correspondant à n’importe quelle ligne.

 PO4A-HEADER:mode=after;position=Copyright Tralala, 2004;beginboundary=^

=item 

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 B<endboundary> ne correspondant à
aucune ligne. N’utilisez pas de chaîne simple, comme B<"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

=back



=head3 Exemple plus détaillé

Document original (au format S<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 B<beginboundary> (/^=head1/) après la
section S<« NOM »> (correspondant à la section S<« 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 B<mode>=I<before> :

 PO4A-HEADER:mode=before;position=^=head1 AUTEUR

=head1 Comment ça S<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
L<Locale::Po4a::TransTractor(3pm)|TransTractor> 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
S<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 S<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 B<po4a-gettextize>. Si vous
fournissez les deux entrées et ignorez le PO de sortie, vous aurez
B<po4a-translate>. Le B<po4a> appelle deux fois TransTract et appelle
B<msgmerge -U> entre ces appels pour fournir une solution unique à partir
d’un seul fichier de configuration. Lisez L<Locale::Po4a::TransTractor(3pm)>
pour plus d’informations.

=head1 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)).

=over 

=item 

adduser (man) : outil de gestion des utilisateurs et des groupes.

=item 

apt (man, docbook) : Gestionnaire de paquets Debian.

=item 

aptitude (docbook, svg) : gestionnaire de paquets en mode commande pour
Debian

=item 

L<site internet F-Droid|https://gitlab.com/fdroid/fdroid-website> (markdown)
: catalogue de logiciels libres pour la plateforme Android.

=item 

L<git|https://github.com/jnavila/git-manpages-l10n> (asciidoc) : système de
contrôle de version distribué pour suivre les modifications du code source.

=item 

L<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).

=item 

L<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.

=back



=head1 FAQ

=head2 Comment prononcer po4a ?

Personnellement, je le prononce comme
L<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 :)

=head2 Qu’en est-il des autres outils de traduction de documentation utilisant
S<gettext ?>

Il n’y en à notre connaissance que S<deux :>

=over 

=item B<poxml>

C’est l’outil développé au sein du projet KDE pour gérer les
S<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.

=item B<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.

=back

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.

=head2 RÉSUMÉ des avantages de l’approche basée sur gettext

=over 2

=item 

Les traductions ne sont pas stockées indépendamment de l’original, ce qui
rend possible la détection des parties à mettre à jour.

=item 

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.

=item 

En interne, tout est basé sur B<gettext> (mais B<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.

=item 

Pour l’utilisateur final, rien ne change (à part que les documentations
seront probablement mieux S<maintenues :)>. La documentation distribuée
reste la même.

=item 

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.

=item 

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 S<adresses :>

 - https://docs.kde.org/stable5/en/kdesdk/lokalize/project-view.html
- http://www.debian.org/intl/l10n/

=back

Mais tout n’est pas rose, et cette approche a aussi quelques désavantages
que nous devons gérer.

=over 2

=item 

Les addenda sont… surprenants au premier abord.

=item 

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.

=item 

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
S<MS Word> (TM) (ou au moins pour le format RTF), des traducteurs
professionnels pourraient même l’utiliser.

=back

=head1 VOIR AUSSI

=over 

=item 

La documentation de l'outil tout-en-un que vous devriez utiliser :
L<po4a(1)>.

=item 

La documentation des scripts po4a S<individuels :> L<po4a-gettextize(1)>,
L<po4a-updatepo(1)>, L<po4a-translate(1)>, L<po4a-normalize(1)>.

=item 

Les scripts d'assistance supplémentaires : L<msguntypot(1)>,
L<po4a-display-man(1)>, L<po4a-display-pod(1)>.

=item 

Les parsers de chaque format, en particulier pour consulter les options
acceptées par chacun d'entre S<eux :> L<Locale::Po4a::AsciiDoc(3pm)>
L<Locale::Po4a::Dia(3pm)>, L<Locale::Po4a::Guide(3pm)>,
L<Locale::Po4a::Ini(3pm)>, L<Locale::Po4a::KernelHelp(3pm)>,
L<Locale::Po4a::Man(3pm)>, L<Locale::Po4a::RubyDoc(3pm)>,
L<Locale::Po4a::Texinfo(3pm)>, L<Locale::Po4a::Text(3pm)>,
L<Locale::Po4a::Xhtml(3pm)>, L<Locale::Po4a::Yaml(3pm)>,
L<Locale::Po4a::BibTeX(3pm)>, L<Locale::Po4a::Docbook(3pm)>,
L<Locale::Po4a::Halibut(3pm)>, L<Locale::Po4a::LaTeX(3pm)>,
L<Locale::Po4a::Pod(3pm)>, L<Locale::Po4a::Sgml(3pm)>,
L<Locale::Po4a::TeX(3pm)>, L<Locale::Po4a::Wml(3pm)>,
L<Locale::Po4a::Xml(3pm)>.

=item 

La mise en œuvre de l'infrastructure de base :
L<Locale::Po4a::TransTractor(3pm)> (particulièrement important pour
comprendre l'organisation du code), L<Locale::Po4a::Chooser(3pm)>,
L<Locale::Po4a::Po(3pm)>, L<Locale::Po4a::Common(3pm)>. Veuillez également
consulter le fichier F<CONTRIBUTING.md> dans l'arborescence des sources.

=back

=head1 AUTEURS

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


=head1 TRADUCTION

 Martin Quinson (mquinson#debian.org)

