
        *****************************************************
        *           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 pour tout – PO for anything) facilite la maintenance de la
traduction de la documentation en utilisant les outils classiques de
gettext. La principale caractéristique de po4a est qu'il dissocie la
traduction du contenu et la structure du document.

Ce document sert d'introduction au projet po4a en mettant l'accent sur
personnes qui envisagent éventuellement d'utiliser cet outil et qui sont
simplement curieuses et souhaitent comprendre pourquoi les choses sont comme
elles sont.

=head1 Pourquoi po4a ?

La philosophie des logiciels libres est de rendre la technologie réellement
disponible à tout le monde. Cependant, la licence n’est pas la seule
préoccupation car un logiciel libre non traduit est inutilisable par des
publics non anglophones. En conséquence, nous avons encore du travail pour
rendre les logiciels globalement disponibles.

Cette situation est bien comprise par la plupart des projets et tout le
monde est désormais convaincu de la nécessité de tout traduire. Pourtant,
les traductions représentent un effort énorme de nombreuses personnes,
paralysées par de petites difficultés techniques.

Heureusement, les logiciels libres sont réellement très bien traduits grâce
à la suite d’outils gettext. Ces outils sont utilisés pour extraire les
chaines traduisibles d’un programme et pour présenter ces dans un format
standardisé (appelés fichiers PO, ou catalogue de traduction). Tout un
écosystème d’outils a émergé pour aider les équipes de traduction à traduire
ces fichiers PO. Le résultat est alors utilisé par gettext à l'exécution du
logiciel pour afficher les messages traduits dans l’interface d’utilisation.

En ce qui concerne la documentation, cependant, la situation est quelque peu
décevante. Au début, la traduction de la documentation peut sembler plus
facile que la traduction d'un programme, car il semblerait que vous deviez
simplement copier le fichier source de la documentation et commencer à
traduire le contenu. Cependant, lorsque la documentation originale est
modifiée, le suivi des modifications se transforme rapidement en cauchemar
pour les équipes de traduction. Si elle est effectuée manuellement, cette
tâche est désagréable et sujette aux erreurs.

Les traductions obsolètes sont souvent pires qu’une absence de
traduction. Une documentation qui décrit un comportement désormais obsolète
du programme sera trompeuse. De plus, la prise de contact avec les
responsables du logiciels est impossible à cause de la barrière de la
langue. De plus, les responsables ne peuvent pas forcément résoudre les
problèmes sans une connaissance de toutes les langues dans lesquelles la
documentation est traduite. Ces difficultés, souvent causées par un mauvais
outillage, peuvent miner la motivation des équipes de traduction, aggravant
encore les problèmes.

B<Le but du projet po4a est de faciliter le travail de traduction de la
documentation>. En particulier, il facilite la I<maintenance> des
traductions de documentation.

L'idée est de réutiliser et d'adapter l'approche gettext à ce domaine. Comme
pour gettext, les textes sont extraits de leur emplacement d'origine et
présentés aux équipes de traduction sous forme de catalogues de traduction
PO. Les équipes de traduction peuvent utiliser les outils classiques de
gettext pour suivre le travail à faire, collaborer et s'organiser. po4a
injecte ensuite les traductions directement dans la structure de la
documentation pour produire des fichiers traduits qui peuvent être traités
et distribués comme les fichiers anglais. Tout paragraphe qui n'est pas
traduit est laissé en anglais dans le document résultant, garantissant que
des traductions obsolètes ne voient jamais le jour.

Ceci automatise la plupart des gros travaux de maintenance de la
traduction. La découverte des paragraphes nécessitant une mise à jour
devient très facile et le processus est complètement automatisé lorsque les
éléments sont réorganisés sans autre modification. Une vérification
spécifique peut également être utilisée pour réduire le risque d'erreurs de
formatage qui entraineraient un document altéré.

Veuillez également consulter la 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.

Voir L<Locale::Po4a::AsciiDoc> pour en savoir plus.

=item pod (analyseur stable)

C’est le format pour la documentation en ligne de Perl (« S<P>erl S<O>nline
S<D>ocumentation> »). Le langage et ses documentations sont documentés en
utilisant ce format en plus de la majorité des scripts Perl existants. Il
permet de garder la documentation plus fidèle au code en les intégrant tous
deux au même fichier. Il rend la vie du programmeur plus simple, mais
malheureusement pas celle des équipes de traduction jusqu'à ce que vous
utilisiez po4a.

Voir L<Locale::Po4a::Pod> pour en savoir plus.

=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 DTD DebianDoc et DocBook sont prises en charge,
mais l’ajout d’une nouvelle DTD est très facile. Il est même possible
d’utiliser po4a avec une DTD SGML inconnue sans modifier le code en
fournissant les informations nécessaires sur la ligne de commande. Consultez
L<Locale::Po4a::Sgml(3pm)> pour en savoir plus.

=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, 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
L<Locale::Po4a::Text(3pm)|Text> pour en savoir plus.

=item xml and XHMTL (analyseur probablement stable)

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

À ce jour, la DTD DocBook et XHTML sont pris en charge par po4a. Consultez
L<Locale::Po4a::Docbook(3pm)> pour en savoir plus.

=item 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 L<Locale::Po4a::BibTex> pour en savoir plus.

=item DocBook (analyseur probablement stable)

Un langage de balisage basé sur XML qui utilise des balises sémantiques pour
décrire des documents.

Voir L<Locale::Po4a:Docbook> pour en savoir plus.

=item 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 L<Locale::Po4a:Guide> pour en savoir plus.

=item 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 L<Locale::Po4a::Wml> pour en savoir plus.

=item Yaml (analyseur probablement stable)

Un surensemble strict de JSON. YAML est souvent utilisé comme systèmes ou
projets de configuration.  YAML est au cœur d’Ansible de Red Hat.

Voir L<Locale::Po4a::Yaml> pour en savoir plus.

=item 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 L<Locale::Po4a::RubyDoc> pour en savoir plus.

=item 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 L<Locale::Po4a:Halibut> pour en savoir plus.

=item Ini (analyseur très expérimental)

Format de fichier de configuration popularisé par MS-DOS.

Voir L<Locale::Po4a::Ini> pour en savoir plus.

=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ébuts. N’hésitez pas à nous envoyer des rapports de bogue ou
des demandes de nouvelle fonctionnalité.

=item gemtext (analyseur très expérimental)

The native plain text format of the Gemini protocol.  The extension C<.gmi>
is commonly used.  Support for this module in po4a is still in its infancy.
If you find anything, please file a bug or feature request.

=item org (very highly experimental parser)

The document format used by the Org mode.  Support for this module in po4a
is still in its infancy.  If you find anything, please file a bug or feature
request.

=item vimhelp (very highly experimental parser)

The format used for Vim help files (and some third-party plugin
documentation).  Support for this format in po4a is still in its infancy.
If you find anything, please file a bug report or feature request.

=item simplepod (very highly experimental parser)

Similar to the previously mentioned I<pod>, this one adopts the new
L<Pod::Simple> as its parser.  Since it is newly created, some bugs are
expected.  If you notice any strange behavior, please let us know.
Eventually, this module will replace I<pod>.

=item Autres formats supportés

Po4a can also handle some more rare or specialized formats, such as the
documentation of compilation options for the 2.4+ Linux kernels
(L<Locale::Po4a::KernelHelp>) or the diagrams produced by the dia tool
(L<Locale::Po4a::Dia>). Adding a new format is often very easy and the main
task is to come up with a parser for your target format. See
L<Locale::Po4a::TransTractor(3pm)> for more information about this.

=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 simples à prendre en
charge dans po4a. Cela inclut des formats étant utilisés pour plus que de la
documentation, tels que les descriptions de paquets (deb et rpm), aux
questions posées par les scripts d’installation, en passant par les fichiers
changelog, et de tous les formats spécifiques tels que les scénarios de jeux
ou les fichiers de ressource pour wine.

=back

=head1 Utiliser po4a

La manière la plus simple d'utiliser cet outil dans votre projet est
d'écrire un fichier de configuration pour le programme B<po4a>, et de
n'interagir qu'avec ce programme. Référez-vous à sa documentation, dans
L<po4a(1)>. Le reste de cette section fournit plus de détails pour une
utilisation avancée et une compréhension approfondie de po4a.

=head2 Schéma détaillé du flux de travail de po4a

Assurez-vous d'avoir lu L<po4a(1)> avant d'aborder cette section trop
détaillée afin d'obtenir une vue d'ensemble simplifiée du flux de travail de
po4a. Revenez ici pour obtenir l'image complète et effrayante, avec presque
tous les détails.

In the following schema, F<master.doc> is an example name for the
documentation to be translated; F<XX.doc> is the same document translated in
the language XX while F<doc.XX.po> is the translation catalog for that
document in the XX language. Documentation authors will mostly be concerned
with F<master.doc> (which can be a manpage, an XML document, an AsciiDoc
file, etc); the translators will be mostly concerned with the PO file, while
the end users will only see the F<XX.doc> file.

Les transitions entre crochets telles que C<[po4a met à jour le po]>
représentent l'exécution d'un outil po4a, tandis que les transitions entre
accolades telles que C<{mise à jour de chapi.doc}> représentent une
modification manuelle des fichiers du projet.

                                   master.doc
                                       |
                                       V
     +<-----<----+<-----<-----<--------+------->-------->-------+
     :           |                     |                        :
{translation}    |          {update of master.doc}              :
     :           |                     |                        :
   XX.doc        |                     V                        V
 (optional)      |                 master.doc ->-------->------>+
     :           |                   (new)                      |
     V           V                     |                        |
  [po4a-gettextize]   doc.XX.po -->+   |                        |
          |            (old)       |   |                        |
          |              ^         V   V                        |
          |              |   [po4a updates po]                  |
          V              |           |                          V
   translation.pot       ^           V                          |
          |              |        doc.XX.po                     |
          |              |         (fuzzy)                      |
    {translation}        |           |                          |
          |              ^           V                          V
          |              |     {manual editing}                 |
          |              |           |                          |
          V              |           V                          V
      doc.XX.po --->---->+<---<-- doc.XX.po    addendum     master.doc
      (initial)                 (up-to-date)  (optional)   (up-to-date)
          :                          |            |             |
          :                          V            |             |
          +----->----->----->------> +            |             |
                                     |            |             |
                                     V            V             V
                                     +------>-----+------<------+
                                                  |
                                                  V
                                     [po4a updates translations]
                                                  |
                                                  V
                                                XX.doc
                                             (up-to-date)

Là encore, ce schéma est particulièrement compliqué. Consultez L<po4a(1)>
pour un aperçu simplifié.

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 en savoir plus),
mais elle n'est nécessaire qu'une seule fois pour convertir vos traductions
existantes. Si vous n'avez aucune traduction à convertir, vous pouvez
oublier cela et vous concentrer sur la partie droite du schéma.

En haut à droite est décrit ce qui relève de l’auteur du document d’origine,
la mise à jour de la documentation. Au milieu à droite sont décrites les
mises à jour automatisées des fichiers à traduire : les nouvelles chaines
sont extraites et comparées avec la traduction existante. La traduction
existante est utilisée pour les parties n’ayant pas changé, alors que celles
qui ont été en partie modifiées sont également associées à leur ancienne
traduction, mais avec un marquage « fuzzy » indiquant que la traduction doit
être mise à jour. Un contenu nouveau ou fortement modifié est laissé non
traduit.

Ensuite, le bloc I<modifications manuelles> décrit l'action des équipes de
traduction qui modifient les fichiers PO pour fournir des traductions à
chaque chaine et paragraphe d'origine. Cela peut être fait en utilisant un
éditeur spécifique tel que 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. Référez-vous à la documentation de gettext pour
en savoir plus.

La partie inférieure de la figure montre comment B<po4a> crée un document
source traduit à partir du document original F<chapi.doc> et du catalogue de
traduction F<doc.XX.po> mis à jour par les équipes de traduction. La
structure du document est réutilisée, tandis que le contenu original est
remplacé par son équivalent traduit. En option, un addendum peut être
utilisé pour ajouter du texte supplémentaire à la traduction. Ceci est
souvent utilisé pour ajouter le nom des membres des équipes de traduction au
document final. Voir ci-dessous pour en savoir plus.

L'appel à B<po4a> met à jour automatiquement aussi bien les fichiers à
traduire que les fichiers traduits.

=head2 Commencer un nouveau projet de traduction

Si vous partez de zéro, il vous suffit d'écrire un fichier de configuration
pour po4a pour commencer. Des modèles appropriés sont créés pour les
fichiers manquants, ce qui permet à vos contributeurs de traduire votre
projet dans leur langue. Consultez L<po4a(1)> pour un tutoriel de démarrage
rapide et pour tous les détails.

Si vous disposez d'une traduction existante, c'est-à-dire d'un fichier de
documentation qui a été traduit manuellement, vous pouvez intégrer son
contenu dans votre flux de travail po4a en utilisant
B<po4a-gettextize>. Cette tâche est un peu lourde (comme décrit dans la page
de man de l'outil), mais une fois que votre projet est mis en adaptation au
flux de travail po4a, tout sera mis à jour automatiquement.

=head2 Mettre à jour les traductions et les documents

Une fois configuré, il suffit d'invoquer B<po4a> pour mettre à jour à la
fois les fichiers PO de traduction et les documents traduits. Vous pouvez
passer l'argument C<--no-translations> à B<po4a> pour ne pas mettre à jour
les traductions (et donc juste mettre à jour les fichiers PO) ou l'argument
C<--no-update> pour ne pas mettre à jour les fichiers PO (et donc juste
mettre à jour les traductions). Cela correspond à peu près aux scripts
individuels B<po4a-updatepo> et B<po4a-translate> qui sont maintenant
obsolètes (voir «Pourquoi les scripts individuels sont-ils obsolètes» dans
la FAQ ci-dessous).

=head2 Utiliser les addendas pour ajouter du texte supplémentaire aux traductions

Ajouter un nouveau texte à la traduction est probablement la seule chose qui
soit plus facile à long terme lorsque vous traduisez des fichiers
manuellement :). Cela se produit lorsque vous souhaitez ajouter une section
supplémentaire au document traduit, ne correspondant à aucun contenu du
document d'origine. Le cas d'usage classique consiste à mentionner l'équipe
de traduction et à indiquer comment signaler les problèmes spécifiques à la
traduction.

Avec po4a, vous devez spécifier les fichiers 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'entête doit commencer par la chaine B<PO4A-HEADER:>, suivie d'une
liste de champs I<clé>B<=>I<valeur> séparés par des points-virgules.

Par exemple, l'entête suivant déclare un addendum qui doit être placé à la
toute fin de la traduction.

 PO4A-HEADER: mode=eof

Les choses sont plus complexes lorsque vous souhaitez ajouter votre contenu
supplémentaire au milieu du document. L'entête suivant déclare un addendum
qui doit être placé après la section XML contenant la chaine C<À propos de
ce document> en traduction.

 PO4A-HEADER: position=About this document; 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'entête suivant, qui est
équivalent :

 PO4A-HEADER: position=About this document; mode=after; beginboundary=<section>

Ici, po4a recherche la première ligne correspondant à C<< <section> >> après
la ligne correspondant à C<À propos de ce 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'entête impose de placer l'addendum après la
section contenant C<À propos de ce 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   | Boundary kind |     Used boundary      | Insertion point compared to the boundary
 ========|===============|========================|=========================================
 'before'| 'endboundary' | last before 'position' | Right after the selected boundary
 'before'|'beginboundary'| last before 'position' | Right before the selected boundary
 'after' | 'endboundary' | first after 'position' | Right after the selected boundary
 'after' |'beginboundary'| first after 'position' | Right before the selected boundary
 'eof'   |   (none)      |  n/a                   | End of file

=head3 Trucs et astuces sur les addendas

=over

=item

Gardez à l’esprit que ce sont des expressions rationnelles. Par exemple, si
vous voulez correspondre à la fin d’une section nroff terminant par la ligne
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=About this document; mode=after; beginboundary=<section>
 PO4A-HEADER: position=About this 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 C<-vv> à B<po4a> pour comprendre comment les addendas sont
ajoutés à la traduction. Il peut également être utile d'exécuter B<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 suivante :

  .SH "AUTHORS"

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=AUTHORS;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 Big Dude, 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=About this document;beginboundary=FakePo4aBoundary

=back

=head3 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 nom des membres des équipes de traduction.

 |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> C</^=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 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.

=head2 TransTractors et l'architecture du projet

Au cœur du projet po4a se trouve la classe
L<Locale::Po4a::TransTractor(3pm)|TransTractor> qui est l’ancêtre commun à
tous les analyseurs de po4a. Ce nom étrange provient du fait qu'elle est à
la fois chargée de la traduction et de l’extraction des chaînes du document.

Plus formellement, il prend un document à traduire et un fichier PO
contenant les traductions en entrée et produit en sortie deux autres
fichiers : un autre fichier PO (résultant de l’extraction des chaînes à
traduire du document d’entrée), et un document traduit (avec la même
structure que le document d’entrée, mais dont toutes les chaînes à traduire
ont été remplacées par leur traduction donnée par le PO fournit en
entrée). Voici une représentation graphique de tout ceci :

   Input document --\                             /---> Output document
                     \      TransTractor::       /       (translated)
                      +-->--   parse()  --------+
                     /                           \
   Input PO --------/                             \---> Output PO
                                                       (extracted)

Cette forme d’os est le cœur de l’architecture de po4a. Si vous fournissez
l'entrée mais ignorez la sortie PO, vous obtenez B<po4a-translate>. Si vous
ignorez la sortie document à la place, vous obtenez B<po4a-updatepo>. <po4a>
utilise un premier TransTractor pour obtenir un fichier de sortie POT mis à
jour (en ignorant les documents en sortie), appelle B<msgmerge -U> pour
mettre à jour les fichiers PO de traduction sur le disque et crée un second
TransTractor à l'aide de ces fichiers PO mis à jour pour mettre à jour les
documents de sortie. En d'autres termes, B<po4a> vous offre une solution
unique pour mettre à jour ce qui doit l'être, à l'aide d'un seul fichier de
configuration.

B<po4a-gettextize> utilise également deux TransTractors, mais d'une autre
manière : il construit un TransTractor par langue, puis construit un nouveau
fichier PO en utilisant les msgids du document originel en tant que msgids,
et les msgids du document traduit en tant que msgstrs. Il faut faire très
attention à ce que les chaînes qui sont ainsi mises en correspondance
correspondent réellement, comme indiqué dans L<po4a-gettextize(1)>.

=head2 Analyseurs spécifiques aux formats

Tous les analyseurs de format sont implémentés au-dessus de
TransTractor. Certains sont très simples, comme les analyseurs Text,
Markdown et AsciiDoc. Ils chargent les lignes une par une en utilisant
C<TransTractor::shiftline()> et accumulent le contenu des paragraphes ou
autre. Une fois qu'une chaîne est complètement analysée, l'analyseur utilise
C<TransTractor::translate()> pour (1) ajouter cette chaîne au fichier PO de
sortie et (2) obtenir la traduction du fichier PO d'entrée. L'analyseur
pousse ensuite le résultat vers le fichier de sortie à l'aide de
C<TransTractor::pushline()>.

D'autres analyseurs sont plus complexes, car ils s'appuient sur un analyseur
externe pour analyser le document d'entrée. Les analyseurs Xml, HTML, SGML
et Pod sont construits sur les analyseurs SAX. Ils déclarent des rappels à
des événements tels que "J'ai trouvé un nouveau titre dont le contenu est
ceci" pour mettre à jour le document de sortie et les fichiers POT de sortie
en fonction du contenu d'entrée en utilisant C<TransTractor::translate()> et
C<TransTractor::pushline()>. L'analyseur Yaml est similaire, mais
différent : il sérialise une structure de données produite par l'analyseur
YAML::Tiny. C'est pourquoi le module Yaml de po4a ne parvient pas à déclarer
les lignes de référence : l'emplacement de chaque chaîne dans le fichier
d'entrée n'est pas conservé par l'analyseur, de sorte que nous ne pouvons
fournir que "$filename:1" comme emplacement de la chaîne. Les analyseurs
orientés SAX utilisent des globaux et d'autres astuces pour enregistrer le
nom de fichier et les numéros de ligne des références.

Un problème spécifique est lié à l'encodage des fichiers et aux marqueurs
BOM. Les analyseurs simples peuvent ignorer ce point qui est géré par
C<TransTractor::read()> (utilisé en interne pour obtenir les lignes d'un
document d'entrée), mais les modules qui s'appuient sur un analyseur externe
doivent s'assurer que tous les fichiers sont lus avec une couche de décodage
PerlIO appropriée. Le plus simple est d'ouvrir le fichier vous-même, et de
fournir un identificateur de fichier ou directement la chaine complète à
votre analyseur externe. Consultez C<Pod::read()> et C<Pod::parse()> pour un
exemple. Le contenu lu par le TransTractor est ignoré, mais un nouvel
identificateur de fichier est transmis à l'analyseur externe. La partie
importante est le mode C<<"<:encoding($charset)">> qui est transmis à la
fonction perl B<open()>.

=head2 Objets Po

La classe L<Locale::Po4a::Po(3pm)|Po> a la tâche de charger et d'utiliser
les fichiers PO et POT. En principe, vous pouvez lire un fichier, ajouter
des entrées, obtenir des traductions avec la méthode B<gettext()>, puis
écrire le PO dans un fichier. Les fonctions plus avancées telles que la
fusion d'un fichier PO avec un fichier POT ou la validation d'un fichier
sont respectivement déléguées à B<msgmerge> et B<msgfmt>.

=head2 Contribuer à po4a

Même si vous n'avez jamais contribué à un projet libre, bienvenue ! Nous
sommes prêts à vous aider et à vous encadrer. po4a est aujourd'hui mieux
maintenu par sa communauté. Comme nous manquons d'aide, nous essayons de
rendre le projet accueillant en améliorant la documentation et les tests
automatiques afin de vous rendre la contribution au projet plus
facile. Consultez le fichier CONTRIBUTING.md pour en savoir plus.

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

=item

L<Jamulus|https://jamulus.io/> (markdown, yaml, HTML) : une application FOSS
pour le brouillage en ligne en temps réel. La documentation du site web est
maintenue en plusieurs langues à l'aide de po4a.

=item

Autres éléments à trier : L<https://gitlab.com/fdroid/fdroid-website/>
L<https://github.com/fsfe/reuse-docs/pull/61>

=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 Pourquoi les scripts individuels sont-ils obsolètes ?

Indeed, B<po4a-updatepo> and B<po4a-translate> are deprecated in favor of
B<po4a>. The reason is that while B<po4a> can be used as a drop-in
replacement to these scripts, there is quite a lot of code duplication
here. Individual scripts last around 150 lines of codes while the B<po4a>
program lasts 1200 lines, so they do a lot in addition of the common
internals. The code duplication results in bugs occurring in both versions
and needing two fixes. One example of such duplication are the bugs #1022216
in Debian and the issue #442 in GitHub that had the exact same fix, but one
in B<po4a> and the other B<po4a-updatepo>.

À long terme, j'aimerais abandonner les scripts individuels et ne maintenir
qu'une seule version de ce code. Ce qui est sûr, c'est que les scripts
individuels ne seront plus améliorés, et que seul B<po4a> bénéficiera de
nouvelles fonctionnalités. Ceci étant dit, la dépréciation n'est pas
immédiate. Je prévois de conserver les scripts individuels aussi longtemps
que possible, et au moins jusqu'en 2030. Cependant, si votre projet utilise
encore B<po4a-updatepo> et B<po4a-translate> à cette date, vous pourriez
avoir un problème.

Nous pourrions également annuler la dépréciation de ces scripts à un moment
donné, si une réécriture élimine la duplication du code. Si vous avez des
idées (ou mieux : un correctif), votre aide est la bienvenue.

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

Il y en a quelques-uns. Voici une liste potentiellement incomplète, et
d’autres outils arrivent à l’horizon.

=over

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

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

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

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

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

=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 équipes de traduction. 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 tout marche en interne
pour pouvoir l’utiliser). Ce qui permet de ne pas réinventer la roue, et du
fait de leur utilisation importante, nous pouvons supposer qu’ils ont peu ou
pas de bogue.

=item

Pour l’utilisation finale, 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 membres des équipes de traduction
d’apprendre une nouvelle syntaxe et leur éditeur de fichier PO préféré (qui
peut être le mode PO d’Emacs, Lokalize ou Gtranslator) sera parfait.

=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 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 addendas 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 arrivions à faire un module pour
MS Word (TM) (ou au moins pour le format RTF), po4a pourrait même être
utilisés dans le milieu de la traduction professionnelle.

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

The parsers of each formats, in particular to see the options accepted by
each of them: L<Locale::Po4a::AsciiDoc(3pm)> L<Locale::Po4a::Dia(3pm)>,
L<Locale::Po4a::Gemtext(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::Org(3pm)>, L<Locale::Po4a::Pod(3pm)>,
L<Locale::Po4a::SimplePod(3pm)>, L<Locale::Po4a::Sgml(3pm)>,
L<Locale::Po4a::TeX(3pm)>, L<Locale::Po4a::VimHelp>,
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)>. Consultez également
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)

