.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PO4A-GETTEXTIZE 1p"
.TH PO4A-GETTEXTIZE 1p "2020-08-19" "Outils po4a" "Outils po4a"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NOM"
.IX Header "NOM"
po4a\-gettextize \- Convertir un fichier original (et sa traduction) en
fichier \s-1PO\s0
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBpo4a\-gettextize\fR \fB\-f\fR \fIfmt\fR \fB\-m\fR \fImaître.doc\fR [\fB\-l\fR \fI\s-1XX\s0.doc\fR] \fB\-p\fR
\&\fI\s-1XX\s0.po\fR
.PP
(\fI\s-1XX\s0.po\fR est le fichier de sortie, tous les autres sont des entrées)
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
po4a (\s-1PO\s0 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 \fBpo4a\fR\|(7) pour une
introduction en douceur à ce projet.
.PP
Le script \fBpo4a\-gettextize\fR sert à convertir des fichiers de documentation
depuis leur format d’origine vers le format \s-1PO.\s0 Vous n’avez besoin de lui
que pour configurer votre projet de traduction avec po4, jamais par la
suite.
.PP
If you start from scratch, \fBpo4a\-gettextize\fR will extract the translatable
strings from the documentation and write a \s-1POT\s0 file. If you provide a
previously existing translated file with the \fB\-l\fR flag, \fBpo4a\-gettextize\fR
will try to use the translations that it contains in the produced \s-1PO\s0
file. This process remains tedious and manual, as explained in Section
\&'Converting a manual translation to po4a' below.
.PP
Si le document maître contient des caractères non \s-1ASCII,\s0 il convertit les
fichiers \s-1PO\s0 en \s-1UTF\-8\s0 (si ce n’est pas déjà le cas). Sinon (si le document
maître ne contient que des caractères \s-1ASCII\s0), le fichier \s-1PO\s0 généré utilisera
l’encodage du document traduit donné en entrée, ou en \s-1UTF\-\s0 si aucun document
traduit n’est fourni.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-f\fR, \fB\-\-format\fR" 4
.IX Item "-f, --format"
Type de format de la documentation que vous souhaitez traiter. Utilisez
l’option \fB\-\-help\-format\fR pour afficher la liste des formats disponibles.
.IP "\fB\-m\fR, \fB\-\-master\fR" 4
.IX Item "-m, --master"
Fichier contenant le document maître à traduire. Vous pouvez utiliser cette
option plusieurs fois si vous voulez gettextizer plusieurs documents.
.IP "\fB\-M\fR, \fB\-\-master\-charset\fR" 4
.IX Item "-M, --master-charset"
Jeu de caractères du fichier contenant les documents à traduire.
.IP "\fB\-l\fR, \fB\-\-localized\fR" 4
.IX Item "-l, --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.
.IP "\fB\-L\fR, \fB\-\-localized\-charset\fR" 4
.IX Item "-L, --localized-charset"
Jeu de caractères du fichier contenant le document traduit.
.IP "\fB\-p\fR, \fB\-\-po\fR" 4
.IX Item "-p, --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.
.IP "\fB\-o\fR, \fB\-\-option\fR" 4
.IX Item "-o, --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 ».
.IP "\fB\-h\fR, \fB\-\-help\fR" 4
.IX Item "-h, --help"
Affiche un message d’aide.
.IP "\fB\-\-help\-format\fR" 4
.IX Item "--help-format"
Énumère les formats de documentations connus de po4a.
.IP "\fB\-V\fR, \fB\-\-version\fR" 4
.IX Item "-V, --version"
Affiche la version du script et quitte.
.IP "\fB\-v\fR, \fB\-\-verbose\fR" 4
.IX Item "-v, --verbose"
Rend le programme plus bavard.
.IP "\fB\-d\fR, \fB\-\-debug\fR" 4
.IX Item "-d, --debug"
Affiche quelques informations de débogage.
.IP "\fB\-\-msgid\-bugs\-address\fR \fBadresse@email\fR" 4
.IX Item "--msgid-bugs-address adresse@email"
Fixe l’adresse à laquelle les bogues des msgid doivent être envoyés. Par
défaut, les fichiers \s-1POT\s0 créés n’ont pas de champ Report-Msgid-Bugs-To.
.IP "\fB\-\-copyright\-holder\fR \fIchaîne\fR" 4
.IX Item "--copyright-holder chaîne"
Fixe le détenteur du copyright dans l’en\-tête du fichier \s-1POT.\s0 La valeur par
défaut est « Free Software Foundation, Inc. ».
.IP "\fB\-\-package\-name\fR \fIchaîne\fR" 4
.IX Item "--package-name chaîne"
Fixe le nom du paquet pour l’en\-tête du fichier \s-1POT.\s0 La valeur par défaut
est « \s-1PACKAGE\s0 ».
.IP "\fB\-\-package\-version\fR \fIchaîne\fR" 4
.IX Item "--package-version chaîne"
Fixe la version du paquet pour l’en\-tête du fichier \s-1POT.\s0 La valeur par
défaut est « \s-1VERSION\s0 ».
.SS "Convertir une traduction manuelle vers po4a"
.IX Subsection "Convertir une traduction manuelle vers po4a"
\&\fBpo4a\-gettextize\fR va essayer d’extraire le contenu de n’importe quel
fichier de traduction fourni, et utiliser son contenu en tant que msgstr du
fichier \s-1PO\s0 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.
.PP
À 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 « chapître ») soit la traduction de la
quatrième chaîne du document original (de type « 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.
.PP
.Vb 1
\&    Original         Traduction
\&
\&  chapitre            chapitre
\&    paragraphe          paragraphe
\&    paragraphe          paragraphe
\&    paragraphe        chapitre
\&  chapitre              paragraphe
\&    paragraphe          paragraphe
.Ve
.PP
\&\fBpo4a\-gettextize\fR will verbosely diagnose any detected structure
desynchronization. When this happens, you should manually edit the files
(this probably requires that you have some notions of the target
language). You must add fake paragraphs or remove some content in one of the
documents (or both) to fix the reported disparities, until the structure of
both documents perfectly match. Some tricks are given in the next section.
.PP
Even when the document is successfully processed, undetected disparities and
silent errors are still possible. That is why any translation associated
automatically by po4a\-gettextize is marked as \fIfuzzy\fR to require an manual
inspection by humans. One has to check that each retrieved msgstr is
actually the translation of the associated msgid, and not the string before
or after.
.PP
As you can see, the key here is to have the exact same structure in the
translated document and in the original one. The best is to do the
gettextization on the exact version of \fImaster.doc\fR that was used for the
translation, and only update the \s-1PO\s0 file against the latest master file once
the gettextization was successful.
.PP
Si vous avez de la chance pour avoir une correspondance parfaite dans la
structure des fichiers, construire un fichier \s-1PO\s0 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.
.PP
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.
.SS "Hints and tricks for the gettextization process"
.IX Subsection "Hints and tricks for the gettextization process"
The gettextization stops as soon as a desynchronization is detected. In
theory, it should probably be possible resynchronize the gettextization
later in the documents using e.g. the same algorithm than the \fBdiff\fR\|(1)
utility. But a manual intervention would still be mandatory to manually
match the elements that couldn't be automatically matched, explaining why
automatic resynchronization is not implemented (yet?).
.PP
Que cela arrive, tout le jeu consiste à aligner de nouveaux de ces fichues
structures de fichier par des modifications manuelles. \fBpo4a\-gettextize\fR
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 \s-1PO\s0 généré ainsi sera
écrit dans \fIgettextization.failed.po\fR pour permettre leur inspection.
.PP
Here are some other tricks to help you in this tedious process:
.IP "\(bu" 4
Remove all extra content of the translations, such as the section giving
credits to the translators. You can add them back in po4a afterward, using
an addenda (see \fBpo4a\fR\|(7)).
.IP "\(bu" 4
If you need to edit the files to align their structures, you should prefer
editing the translation if possible. Indeed, if the changes to the original
are too intrusive, the old and new versions will not be matched during the
\&\s-1PO\s0 update, and the corresponding translation will be dumped anyway. But do
not hesitate to also edit the original document if required: the important
thing is to get a first \s-1PO\s0 file to start with.
.IP "\(bu" 4
Do not hesitate to kill any original content that would not exist in the
translated version. This content will be automatically reintroduced
afterward, when synchronizing the \s-1PO\s0 file with the document.
.IP "\(bu" 4
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 ;)
.IP "\(bu" 4
Parfois, le contenu des paragraphes correspond, mais pas leur type. Corriger
cela dépend du format. Pour les formats \s-1POD\s0 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 \s-1XML.\s0
.Sp
De la même façon, deux paragraphes peuvent avoir été combinés, dans le
format \s-1POD,\s0 si la ligne qui les sépare contient des espaces, ou s’il n’y a
pas de ligne vide entre la ligne \fB=item\fR et le contenu de cet élément.
.IP "\(bu" 4
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 \fIgettextization.failed.po\fR, et corrigez le problème là
où est vraiment.
.IP "\(bu" 4
Dans certaines configurations malheureuses, vous aurez l’impression que po4a
a oublié des parties du texte original ou de la
traduction. \fIgettextization.failed.po\fR 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.
.Sp
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 \s-1PO,\s0 mais une nouvelle référence est ajoutée à l’entrée existante.
.Sp
So, the previous situation occurs when two similar but different paragraphs
are translated in the exact same way. This will apparently remove a
paragraph of the translation. To fix the problem, it is sufficient to
slightly alter one of the translations in the document. You can also prefer
to kill the second paragraph in the original document.
.Sp
À 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.
.IP "\(bu" 4
As a final note, do not be too surprised if the first synchronization of
your \s-1PO\s0 file takes a long time. This is because most of the msgid of the \s-1PO\s0
file resulting from the gettextization don't match exactly any element of
the \s-1POT\s0 file built from the recent master files. This forces gettext to
search for the closest one using a costly string proximity algorithm.
.Sp
For example, the first \fBpo4a\-updatepo\fR of the Perl documentation's French
translation (5.5 \s-1MB PO\s0 file) took about 48 hours (yes, two days) while the
subsequent ones only take a dozen of seconds.
.SH "VOIR AUSSI"
.IX Header "VOIR AUSSI"
\&\fBpo4a\-gettextize\fR\|(1), \fBpo4a\-normalize\fR\|(1), \fBpo4a\-translate\fR\|(1),
\&\fBpo4a\-updatepo\fR\|(1), \fBpo4a\fR\|(7).
.SH "AUTEURS"
.IX Header "AUTEURS"
.Vb 3
\& Denis Barbier <barbier@linuxfr.org>
\& Nicolas François <nicolas.francois@centraliens.net>
\& Martin Quinson (mquinson#debian.org)
.Ve
.SH "TRADUCTION"
.IX Header "TRADUCTION"
.Vb 1
\& Martin Quinson (mquinson#debian.org)
.Ve
.SH "COPYRIGHT ET LICENCE"
.IX Header "COPYRIGHT ET LICENCE"
Copyright 2002\-2020 by \s-1SPI,\s0 inc.
.PP
Ce programme est un logiciel libre ; vous pouvez le copier et / ou le
modifier sous les termes de la \s-1GPL\s0 (voir le fichier \s-1COPYING\s0).