po4a-gettextize - Convertir un fichier original (et sa traduction) en fichier PO
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)
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.
-
-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 ».
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.
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.
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.
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.
,
po4a-normalize(1),
po4a-translate(1),
po4a-updatepo(1),
po4a(7).
Denis Barbier <[email protected]>
Nicolas François <[email protected]>
Martin Quinson (mquinson#debian.org)
Martin Quinson (mquinson#debian.org)
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).