Provided by: po4a_0.69-1_all 
NOM
po4a-gettextize - Convertir un fichier original (et sa traduction) en fichier PO
SYNOPSIS
po4a-gettextize -f fmt -m maître.doc -l XX.doc -p XX.po
(XX.po est le fichier de sortie, tous les autres sont des entrées)
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 po4a(7) pour une introduction en
douceur à ce projet.
Le script po4a-gettextize vous aide à porter vos traductions existantes vers un flux de travail basé sur
po4a. Cette opération ne doit être effectuée qu'une seule fois pour sauver une traduction existante lors
de la conversion à po4a, et non de manière régulière après la conversion de votre projet. Ce processus
fastidieux est expliqué en détail dans la section « Conversion d'une traduction manuelle à po4a » ci-
dessous.
Vous devez fournir à la fois un fichier maître (par exemple, la source en anglais) et un fichier traduit
existant (par exemple, une tentative de traduction précédente sans po4a). Si vous fournissez plus d'un
fichier maître ou de traduction, ils seront utilisés en séquence, mais il peut être plus facile de
gettextiser chaque page ou chapitre séparément, puis d'utiliser msgmerge pour fusionner tous les fichiers
PO produits. Comme vous le souhaitez.
Si le document maître contient des caractères non ASCII, le nouveau fichier PO généré sera en UTF-8 (si
ce n’est pas déjà le cas). 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.
OPTIONS
-f, --format
Type de format de la documentation que vous souhaitez traiter. Utilisez l’option --help-format pour
afficher la liste des formats disponibles.
-m, --master
Fichier contenant le document maître à traduire. Vous pouvez utiliser cette option plusieurs fois si
vous voulez gettextizer plusieurs documents.
-M, --master-charset
Jeu de caractères du fichier contenant les documents à traduire.
-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.
-L, --localized-charset
Jeu de caractères du fichier contenant le document traduit.
-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.
-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 ».
-h, --help
Affiche un message d’aide.
--help-format
Énumère les formats de documentations connus de po4a.
-k --keep-temps
Conservez les fichiers POT maîtres et localisés temporaires générés avant la fusion. Cela peut être
utile pour comprendre pourquoi ces fichiers sont désynchronisés, conduisant à des problèmes de
gettextization
-V, --version
Affiche la version du script et quitte.
-v, --verbose
Rend le programme plus bavard.
-d, --debug
Affiche quelques informations de débogage.
--msgid-bugs-address 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.
--copyright-holder chaîne
Fixe le détenteur du copyright dans l’en-tête du fichier POT. La valeur par défaut est « Free
Software Foundation, Inc. ».
--package-name chaîne
Fixe le nom du paquet pour l’en-tête du fichier POT. La valeur par défaut est « PACKAGE ».
--package-version chaîne
Fixe la version du paquet pour l’en-tête du fichier POT. La valeur par défaut est « VERSION ».
Convertir une traduction manuelle vers po4a
po4a-gettextize synchronise les fichiers maître et localisé pour extraire leur contenu dans un fichier
PO. Le contenu du fichier maître donne le msgid tandis que le contenu du fichier localisé donne le
msgstr. Ce processus est quelque peu fragile : la Nième chaîne du fichier traduit est censée être la
traduction de la Nième chaîne de l'original.
La gettextisation fonctionne mieux si vous parvenez à récupérer la version exacte du document original
utilisée pour la traduction. Même dans ce cas, il se peut que vous deviez manipuler les fichiers maître
et localisé pour aligner leurs structures si elles ont été désynchronisées par le traducteur d'origine.
Il est donc conseillé de travailler sur des copies des fichiers.
En interne, chaque parseur po4a rapporte le type syntaxique de chaque chaîne extraite. C’est ainsi que
les désynchronisations sont détectées durant la transformation en gettext. Dans l'exemple illustré ci-
dessous, il y a très peu de chance pour que la quatrième chaîne de la traduction (de type « chapitre »)
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.
Original Traduction
chapitre chapitre
paragraphe paragraphe
paragraphe paragraphe
paragraphe chapitre
chapitre paragraphe
paragraphe paragraphe
po4a-gettextize diagnostiquera de manière verbeuse toute désynchronisation de structure. Lorsque cela se
produit, vous devez manuellement modifier les fichiers pour ajouter de faux paragraphes ou supprimer du
contenu ici et là jusqu'à ce que la structure des deux fichiers corresponde réellement. Quelques astuces
sont données ci-dessous pour sauver le maximum de la traduction existantepar ces moyens.
Si vous avez assez de chance pour avoir une correspondance parfaite dans les structures de fichiers prête
à l’emploi, générer un fichier PO correct est une affaire de secondes. Dans le cas contraire, vous
comprendrez vite pourquoi ce processus porte un nom si affreux :) Malgré cela, la gettextisation reste
souvent plus rapide que de tout retraduire. J'ai gettextisé la traduction française de toute la
documentation Perl en une journée malgré les nombreux problèmes de synchronisation. Vu la quantité de
texte (2Mo de texte original), recommencer la traduction sans avoir au préalable récupéré les anciennes
traductions aurait nécessité plusieurs mois de travail. De plus, ce travail fastidieux est le prix à
payer pour bénéficier du confort de po4a. Une fois converti, la synchronisation entre les documents
maîtres et les traductions sera toujours entièrement automatique.
Après une gettextization réussie, les documents produits doivent être vérifiés manuellement pour détecter
les disparités non détectées et les erreurs silencieuses, comme expliqué ci-dessous.
Trucs et astuces pour le processus de «gettextisation»
La gettextisation s'arrête dès qu'une désynchronisation est détectée. Lorsque cela se produit, vous devez
modifier les fichiers autant que nécessaire pour réaligner les structures des fichiers. po4a-gettextize
est plutôt verbeux lorsque les choses se passent mal. Il signale les chaînes de caractères 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é jusqu'à présent est sauvegardé sous gettextization.failed.po pour une inspection plus
approfondie.
Voici quelques astuces pour vous aider dans ce processus fastidieux et vous assurer de récupérer le
maximum de la traduction précédente :
• Supprimez tout le contenu superflu des traductions, comme la section créditant les traducteurs. Ils
doivent être ajoutés séparément en tant qu'addenda (voir po4a(7)).
• Lorsque vous éditez les fichiers pour aligner leurs structures, préférez si possible éditer la
traduction. En effet, si les modifications de l'original sont trop intrusives, l'ancienne et la
nouvelle version ne seront pas appariées lors de la première exécution de po4a après la
gettextisation (voir ci-dessous). Toute traduction non appariée sera de toute façon abandonnée. Ceci
étant dit, vous pouvez toujours éditer le document original s'il est trop difficile d'obtenir la
gettextisation autrement, même si cela signifie qu'un paragraphe de la traduction est abandonné.
L'important est d'obtenir un premier fichier PO pour commencer.
• 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.
• Vous devriez probablement informer l’auteur original de toute modification structurelle dans la
traduction qui semble nécessaire. Les problèmes du document originel doivent être signalés à
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 ;) Mais vous voudrez probablement attendre la fin
de la conversion vers po4a avant de modifier les fichiers originaux.
• 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 =item et le contenu
de cet élément.
• Parfois, le message de désynchronisation semble étrange car la traduction est attachée au mauvais
paragraphe source. C’est le signe d’un problème non détecté en amont dans le processus. Cherchez le
point de synchronisation réel en inspectant le fichier gettextization.failed.po généré, et corrigez
le problème là où est vraiment.
• D'autres problèmes peuvent provenir de chaînes de caractères dupliquées, que ce soit dans l'original
ou dans la traduction. Les chaînes dupliquées sont fusionnées dans les fichiers PO, avec deux
références. Cela constitue une difficulté pour l'algorithme de gettextisation, qui est un simple
appariement un à un entre les msgids du fichier maître et du fichier localisé. Cependant, les
versions récentes de po4a devraient correctement traiter les chaînes de caractères dupliquées, et
vous devriez donc signaler tout problème restant que vous pourriez rencontrer.
Examen des fichiers produits par po4a-gettextize
Tout fichier produit par po4a-gettextize doit être examiné manuellement, même lorsque le script se
termine avec succès. Vous devez parcourir le fichier PO en vous assurant que les msgid et msgstr
correspondent réellement. Il n'est pas encore nécessaire de s'assurer que la traduction est parfaitement
correcte, car toutes les entrées sont de toute façon marquées comme des traductions floues ("fuzzy").
Vous devez seulement vérifier les problèmes de correspondance évidents, car les traductions mal assorties
seront abandonnées lors des étapes suivantes si vous voulez les sauver.
Heureusement, cette étape ne nécessite pas de maîtriser les langues cibles puisque vous voulez seulement
reconnaître des éléments similaires dans chaque msgid et son msgstr correspondant. Parlant moi-même le
français, l'anglais et un peu l'allemand, je peux faire cela pour toutes les langues européennes au
moins, même si je ne peux pas dire un mot de la plupart de ces langues. Je parviens parfois à détecter
des problèmes de correspondance dans les langues non latines en examinant la longueur des chaînes de
caractères, les structures des phrases (la quantité de points d'interrogation correspond-elle ?) et
d'autres indices, mais je préfère que quelqu'un d'autre examine ces langues.
Si vous détectez une discordance, éditez les fichiers d'origine et de traduction comme si po4a-gettextize
avait signalé une erreur, et réessayez. Une fois que vous avez un fichier PO décent pour votre traduction
existante, sauvegardez-le jusqu'à ce que vous obteniez un fonctionnement correct de po4a.
Exécuter po4a pour la première fois
La manière la plus simple de configurer po4a est d'écrire un fichier de configuration po4a.conf, et
d'utiliser le programme po4a unifié (po4a-updatepo et po4a-translate sont obsolètes). Veuillez consulter
la section « FICHIER DE CONFIGURATION » dans la documentation de po4a(1) pour plus de détails.
Lorsque po4a est exécuté pour la première fois, la version actuelle des documents maîtres sera utilisée
pour mettre à jour les fichiers PO contenant les anciennes traductions que vous avez récupérées par
gettextisation. Cela peut prendre beaucoup de temps, car beaucoup des msgids de la gettextisation ne
correspondent pas exactement aux éléments du fichier POT construit à partir des fichiers maîtres récents.
Cela oblige gettext à rechercher le plus proche en utilisant un algorithme coûteux de proximité des
chaînes de caractères. Par exemple, le premier passage sur la traduction française de la documentation
Perl (fichier PO de 5,5 Mo) a pris environ 48 heures (oui, deux jours) alors que les suivants ne prennent
que quelques secondes.
Mise en production de vos traductions
Après ce premier passage, les fichiers PO sont prêts à être revus par les traducteurs. Toutes les entrées
ont été marquées comme floues ("fuzzy") dans le fichier PO par po4a-gettextization, ce qui oblige à les
relire attentivement avant de les utiliser. Les traducteurs doivent examiner chaque entrée pour vérifier
que la traduction récupérée correspond bien au texte original actuel, actualiser la traduction si
nécessaire, et supprimer les marqueurs flous.
Une fois que suffisamment de marqueurs flous sont supprimés, po4a commencera à générer les fichiers de
traduction sur le disque, et vous serez prêt à passer votre flux de traduction à la production. Certains
projets trouvent utile de s'appuyer sur Weblate pour assurer la coordination entre les traducteurs et les
mainteneurs, mais cela dépasse le cadre de po4a.
VOIR AUSSI
po4a-gettextize(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a(7).
AUTEURS
Denis Barbier <barbier@linuxfr.org>
Nicolas François <nicolas.francois@centraliens.net>
Martin Quinson (mquinson#debian.org)
TRADUCTION
Martin Quinson (mquinson#debian.org)
COPYRIGHT ET LICENCE
Copyright 2002-2022 by SPI, inc.
Ce programme est un logiciel libre ; vous pouvez le copier et / ou le modifier sous les termes de la GPL
(voir le fichier COPYING).
Outils po4a 2023-01-03 PO4A-GETTEXTIZE(1p)