
        *****************************************************
        *           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-gettextize - Convertir un fichier original (et sa traduction) en
fichier PO

=head1 SYNOPSIS

B<po4a-gettextize> B<-f> I<fmt> B<-m> I<maître.doc> [B<-l> I<XX.doc>] B<-p>
I<XX.po>

(I<XX.po> est le fichier de sortie, tous les autres sont des entrées)

=head1 DESCRIPTION

po4a (PO for anything) facilite la maintenance de la traduction de la
documentation en utilisant les outils gettext classiques. La principale
caractéristique de po4a est qu'il découple la traduction du contenu de la
structure du document.  Veuillez vous référer à la page L<po4a(7)> pour une
introduction en douceur à ce projet.

Le script B<po4a-gettextize> sert à convertir des fichiers de documentation
depuis leur format d’origine vers le format PO. Vous n’avez besoin de lui
que pour configurer votre projet de traduction avec po4, jamais par la
suite.

Si vous partez de zéro, B<po4a-gettextize> extraira les chaînes traduisibles
de la documentation et écrira un fichier POT. Si vous fournissez un fichier
traduit pré-existant avec l'indicateur B<-l>, B<po4a-gettextize> essaiera
d'utiliser les traductions qu'il contient dans le fichier PO produit. Ce
processus reste fastidieux et manuel, comme expliqué dans la section
«Convertir une traduction manuelle vers po4a» ci-dessous.

Si le document maître contient des caractères non ASCII, il convertit les
fichiers PO en UTF-8 (si ce n’est pas déjà le cas). Sinon (si le document
maître ne contient que des caractères ASCII), le fichier PO généré utilisera
l’encodage du document traduit donné en entrée, ou en UTF- si aucun document
traduit n’est fourni.

=head1 OPTIONS

=over 4

=item B<-f>, B<--format>

Type de format de la documentation que vous souhaitez traiter. Utilisez
l’option B<--help-format> pour afficher la liste des formats disponibles.

=item B<-m>, B<--master>

Fichier contenant le document maître à traduire. Vous pouvez utiliser cette
option plusieurs fois si vous voulez gettextizer plusieurs documents.

=item B<-M>, B<--master-charset>

Jeu de caractères du fichier contenant les documents à traduire.

=item B<-l>, B<--localized>

Fichier contenant le document traduit. Si vous fournissez plusieurs fichiers
maîtres, vous voudrez sûrement fournir également plusieurs documents
traduits en utilisant cette option plusieurs fois.

=item B<-L>, B<--localized-charset>

Jeu de caractères du fichier contenant le document traduit.

=item B<-p>, B<--po>

Fichier où le catalogue de messages sera écrit. S’il n’est pas spécifié, le
catalogue de messages sera écrit sur la sortie standard.

=item B<-o>, B<--option>

Passe une ou des options supplémentaires au greffon de format. Veuillez vous
référer à la documentation de chaque greffon pour la liste des options
valides et leurs significations. Par exemple, vous pourriez passer « -o
tablecells » au parseur AsciiDoc, tandis que le parseur de texte accepterait
« -o tabs=split ».

=item B<-h>, B<--help>

Affiche un message d’aide.

=item B<--help-format>

Énumère les formats de documentations connus de po4a.

=item B<-V>, B<--version>

Affiche la version du script et quitte.

=item B<-v>, B<--verbose>

Rend le programme plus bavard.

=item B<-d>, B<--debug>

Affiche quelques informations de débogage.

=item B<--msgid-bugs-address> B<adresse@email>

Fixe l’adresse à laquelle les bogues des msgid doivent être envoyés. Par
défaut, les fichiers POT créés n’ont pas de champ Report-Msgid-Bugs-To.

=item B<--copyright-holder> I<chaîne>

Fixe le détenteur du copyright dans l’en-tête du fichier POT. La valeur par
défaut est S<« Free> Software Foundation, S<Inc. ».>

=item B<--package-name> I<chaîne>

Fixe le nom du paquet pour l’en-tête du fichier POT. La valeur par défaut
est S<« PACKAGE ».>

=item B<--package-version> I<chaîne>

Fixe la version du paquet pour l’en-tête du fichier POT. La valeur par
défaut est S<« VERSION ».>

=back

=head2 Convertir une traduction manuelle vers po4a

B<po4a-gettextize> va essayer d’extraire le contenu de n’importe quel
fichier de traduction fourni, et utiliser son contenu en tant que msgstr du
fichier PO produit. Soyez attentif au fait que ce processus est très
fragile, la n-ième chaîne du fichier traduit est supposée être la traduction
de la n-ième chaîne de l’original. Cela ne va naturellement pas fonctionner
à moins que les deux fichiers partagent exactement la même structure.

À l'intérieur, chaque parseur po4a rapporte le type syntaxique de chaque
chaîne extraite. C’est de cette façon que les désynchronisation sont
détectée durant la transformation en gettext.  Par exemple, si les fichiers
ont la structure suivante, il y a très peu de chance pour que la quatrième
chaîne de la traduction (de type S<« chapître »)> soit la traduction de la
quatrième chaîne du document original (de type S<« paragraphe »).> Il est plus
probable qu’un nouveau paragraphe ait été ajouté à l’original, ou que deux
paragraphes originaux aient été fusionnés en un seul dans la traduction.

    Original         Traduction

  chapitre            chapitre
    paragraphe          paragraphe
    paragraphe          paragraphe
    paragraphe        chapitre
  chapitre              paragraphe
    paragraphe          paragraphe

B<po4a-gettextize> diagnostiquera toute désynchronisation de structure
détectée. Lorsque cela se produit, vous devez éditer manuellement les
fichiers (cela nécessite probablement que vous ayez quelques notions de la
langue cible). Vous devez ajouter des paragraphes bidons ou supprimer du
contenu dans l'un des documents (ou les deux) pour corriger les disparités
signalées, jusqu'à ce que la structure des deux documents corresponde
parfaitement. Quelques astuces sont données dans la section suivante.

Même lorsque le document est traité avec succès, des disparités non
détectées et des erreurs silencieuses sont toujours possibles. C'est
pourquoi toute traduction associée automatiquement par po4a-gettextize est
marquée I<fuzzy> pour exiger une inspection manuelle par des humains. Il
faut vérifier que chaque «msgstr» récupéré est bin la traduction du «msgid»
associé, et non la chaîne avant ou après.

Comme vous pouvez le voir, la clé ici est d'avoir exactement la même
structure dans le document traduit et dans l'original. Le mieux est de faire
la «gettextisation» sur la version exacte de F<master.doc> qui a été
utilisée pour la traduction, et de ne mettre à jour le fichier PO par
rapport au dernier fichier maître qu'une fois la «gettextisation» réussie.

Si vous avez de la chance pour avoir une correspondance parfaite dans la
structure des fichiers, construire un fichier PO correct se fait en quelques
secondes. Sinon, vous allez vite comprendre pourquoi ce processus a un nom
si barbare :) Mais n’oubliez pas que ce travail fastidieux est le prix à
payer pour l’utilisation confortable de po4a par la suite. Une fois
converti, la synchronisation entre les documents maîtres et leurs
traductions sera toujours automatique.

Même lorsque tout ne se passe pas bien, la transformation en gettext reste
plus rapide qu'une traduction complète. J’ai pu réaliser une gettextization
de la traduction française de Perl en un jour, même si la structure de
nombreux documents était désynchronisée. Il y avait plus de deux mégaoctets
de textes (2 millions de caractères) : redémarrer une nouvelle traduction
aurait nécessité plusieurs mois de travail.

=head2 Trucs et astuces pour le processus de «gettextisation»

La «gettextisation» s'arrête dès qu'une désynchronisation est détectée. En
théorie, il devrait probablement être possible de resynchroniser la
«gettextisation» plus loin dans les documents en utilisant par ex. le même
algorithme que l'utilitaire L<diff(1)>. Mais une intervention humaine serait
toujours obligatoire pour faire correspondre manuellement les éléments qui
ne pourraient pas être automatiquement mis en correspondance, expliquant
pourquoi la resynchronisation automatique n'est pas (encore?) implémentée.

Que cela arrive, tout le jeu consiste à aligner de nouveaux de ces fichues
structures de fichier par des modifications manuelles. B<po4a-gettextize>
est plutôt verbeux sur ce qui a mal tourné quand cela se produit. Il signale
les chaînes qui ne correspondent pas, leur position dans le texte, et le
type de chacune d’entre elles. De plus, le fichier PO généré ainsi sera
écrit dans F<gettextization.failed.po> pour permettre leur inspection.

Voici encore quelques astuces pour vous aider dans ce processus fastidieux :

=over 

=item 

Supprimez tout le contenu superflu des traductions, comme la section donnant
des crédits aux traducteurs. Vous pouvez les rajouter dans po4a par la
suite, en utilisant un addendum (voir L<po4a(7)>).

=item 

Si vous avez besoin de modifier les fichiers pour aligner leurs structures,
vous devriez préférer modifier la traduction si possible. En effet, si les
modifications apportées à l'original sont trop intrusives, l'ancienne et la
nouvelle version ne seront pas mises en correspondance lors de la mise à
jour du PO, et la traduction correspondante sera de toute façon
sauvegardée. Mais n'hésitez pas à éditer également le document d'origine si
nécessaire : l'important est de commencer par obtenir un premier fichier PO.

=item 

N'hésitez pas à supprimer tout contenu original qui n'existe pas dans la
version traduite. Ce contenu sera automatiquement réintroduit par la suite,
lors de la synchronisation du fichier PO avec le document.

=item 

Vous devriez probablement informer l’auteur original de toute modification
structurelle dans la traduction qui semble nécessaire. Les problèmes du
document originel doit être signalée à l’auteur. Faire la correction dans
votre traduction n’en fait bénéficier qu’une partie de la communauté. Et de
plus, c’est impossible avec po4a ;)

=item 

Parfois, le contenu des paragraphes correspond, mais pas leur type. Corriger
cela dépend du format. Pour les formats POD et man, cela provient souvent du
fait qu’un des deux contient une ligne commençant par des espaces et pas
l’autre. Pour ces formats, cela signifie que ce paragraphe ne doit pas être
reformaté, il a donc un type différent. Retirez simplement les espaces et
vous serez tranquille. Il se peut aussi qu’il s’agisse d’une petite erreur
dans le nom d’une balise en XML.

De la même façon, deux paragraphes peuvent avoir été combinés, dans le
format POD, si la ligne qui les sépare contient des espaces, ou s’il n’y a
pas de ligne vide entre la ligne B<=item> et le contenu de cet élément.

=item 

Parfois, le message de désynchronisation semble étrange car la traduction
est attachée au mauvais paragraphe source. C’est le signe d’une problème non
détecté en amont dans le processus. Cherchez le point de synchronisation
réel en inspectant F<gettextization.failed.po>, et corrigez le problème là
où est vraiment.

=item 

Dans certaines configurations malheureuses, vous aurez l’impression que po4a
a oublié des parties du texte original ou de la
traduction. F<gettextization.failed.po> indique que les fichiers
correspondent jusqu’au paragraphe N. Mais après, une tentative
(infructueuse) est réalisée pour faire correspondre le paragraphe N+1 du
fichier original non pas avec le paragraphe N+1 de la traduction comme il le
faudrait, mais avec le paragraphe N+2. Comme si le paragraphe N+1 que vous
voyez dans le document avait simplement disparu du fichier durant le
processus.

Cette situation malheureuse se manifeste quand un même paragraphe est répété
dans le document. Dans ce cas, aucune nouvelle entrée n’est créée dans le
fichier PO, mais une nouvelle référence est ajoutée à l’entrée existante.

La situation précédente se produit aussi lorsque deux paragraphes similaires
mais différents sont traduits exactement de la même manière. Cela supprimera
apparemment un paragraphe de la traduction. Pour résoudre le problème, il
suffit de modifier légèrement l'une des traductions du document. Vous pouvez
également préférer supprimer le deuxième paragraphe du document d'origine.

À l'opposé, si le même paragraphe apparaît deux fois dans l’original mais
n’est pas traduit exactement de la même façon chaque fois, vous aurez
l’impression qu’un paragraphe de l’original a disparu. Copiez simplement la
meilleure traduction à la place de l'autre dans le document traduit pour
résoudre le problème.

=item 

Pour finir, ne soyez pas trop surpris si la première synchronisation de
votre fichier PO prend du temps. En effet, la plupart des «msgid» du fichier
PO résultant de la «gettextisation» ne correspondent exactement à aucun
élément du fichier POT construit à partir des fichiers maîtres récents. Cela
force gettext à rechercher le plus proche en utilisant un algorithme coûteux
de proximité de chaînes.

Par exemple, le premier B<po4a-updatepo> de la traduction française de la
documentation Perl (fichier PO de 5,5 Mo) a pris environ 48 heures (oui,
deux jours) tandis que les suivants ne prennent qu'une dizaine de secondes.

=back

=head1 VOIR AUSSI

L<po4a-gettextize(1)>, L<po4a-normalize(1)>, L<po4a-translate(1)>,
L<po4a-updatepo(1)>, L<po4a(7)>.

=head1 AUTEURS

 Denis Barbier <barbier@linuxfr.org>
 Nicolas François <nicolas.francois@centraliens.net>
 Martin Quinson (mquinson#debian.org)


=head1 TRADUCTION

 Martin Quinson (mquinson#debian.org)

=head1 COPYRIGHT ET LICENCE

Copyright 2002-2020 by SPI, inc.

Ce programme est un logiciel S<libre ;> vous pouvez le copier et / ou le
modifier sous les termes de la GPL (voir le fichier COPYING).

