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.

           = élément -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 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 certains cas, po4a ajoute un espace à la fin des chaînes de caractères originales
           ou traduites. Ceci est dû au fait que chaque chaîne doit être dédupliquée pendant le
           processus gettextize. Imaginez qu'une chaîne apparaisse plusieurs fois à l'identique
           dans l'original, mais qu'elle soit traduite de manières différentes, ou que différents
           paragraphes soient traduits exactement de la même manière.

           Sans déduplication, un tel cas mettrait en défaut l'algorithme de gettexisation, car
           il s'agit d'un simple appariement un à un entre les msgids des fichiers maître et
           localisés. Comme il manquerait une entrée dans l'un des fichiers PO (qui serait
           signalée comme un doublon, avec deux références), l'appariement échouerait.

           Puisque po4a utilise le type d'entrée ("title" ou "plain paragraph", etc) pour
           détecter si les flux d'analyse ont été désynchronisés, des problèmes similaires
           pourraient se produire si deux entrées identiques (même contenu mais type différent)
           du fichier maître sont traduites exactement de la même manière dans le fichier
           localisé. po4a détecterait une fausse désynchronisation dans ce cas.

           Dans la plupart des cas, l'espace supplémentaire ajouté par po4a pour dédupliquer les
           chaînes de caractères n'a aucun impact sur le formatage. Les chaînes de caractères
           sont de toute façon marquées comme floues, et msgmerge les fera probablement
           correspondre en conséquence par la suite.

       •   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).