PO4A-GETTEXTIZE.1P(1)

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