Provided by: po4a_0.66-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 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, 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 -l, 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.
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.
-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 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 « 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.
Original Traduction
chapitre chapitre
paragraphe paragraphe
paragraphe paragraphe
paragraphe chapitre
chapitre paragraphe
paragraphe paragraphe
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 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 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.
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 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. 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 gettextization.failed.po pour
permettre leur inspection.
Voici encore quelques astuces pour vous aider dans ce processus fastidieux :
• 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
po4a(7)).
• 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.
• 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 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 ;)
• 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’une problème non détecté en amont dans le processus. Cherchez le
point de synchronisation réel en inspectant gettextization.failed.po, et corrigez le problème là où
est vraiment.
• Dans certaines configurations malheureuses, vous aurez l’impression que po4a a oublié des parties du
texte original ou de la traduction. 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.
• 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 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.
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-2020 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 2022-01-02 PO4A-GETTEXTIZE(1p)