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