Linux Manpages Online - man.cx manual pages

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)

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.

If you start from scratch, po4a-gettextize will extract the translatable strings from the documentation and write a POT file. If you provide a previously existing translated file with the -l flag, po4a-gettextize will try to use the translations that it contains in the produced PO file. This process remains tedious and manual, as explained in Section ’Converting a manual translation to po4a’ below.

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 will verbosely diagnose any detected structure desynchronization. When this happens, you should manually edit the files (this probably requires that you have some notions of the target language). You must add fake paragraphs or remove some content in one of the documents (or both) to fix the reported disparities, until the structure of both documents perfectly match. Some tricks are given in the next section.

Even when the document is successfully processed, undetected disparities and silent errors are still possible. That is why any translation associated automatically by po4a-gettextize is marked as fuzzy to require an manual inspection by humans. One has to check that each retrieved msgstr is actually the translation of the associated msgid, and not the string before or after.

As you can see, the key here is to have the exact same structure in the translated document and in the original one. The best is to do the gettextization on the exact version of master.doc that was used for the translation, and only update the PO file against the latest master file once the gettextization was successful.

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.

Hints and tricks for the gettextization process
The gettextization stops as soon as a desynchronization is detected. In theory, it should probably be possible resynchronize the gettextization later in the documents using e.g. the same algorithm than the diff(1) utility. But a manual intervention would still be mandatory to manually match the elements that couldn’t be automatically matched, explaining why automatic resynchronization is not implemented (yet?).

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.

Here are some other tricks to help you in this tedious process:

	•		Remove all extra content of the translations, such as the section giving credits to the translators. You can add them back in po4a afterward, using an addenda (see po4a(7)).
	•		If you need to edit the files to align their structures, you should prefer editing the translation if possible. Indeed, if the changes to the original are too intrusive, the old and new versions will not be matched during the PO update, and the corresponding translation will be dumped anyway. But do not hesitate to also edit the original document if required: the important thing is to get a first PO file to start with.
	•		Do not hesitate to kill any original content that would not exist in the translated version. This content will be automatically reintroduced afterward, when synchronizing the PO file with the 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.

So, the previous situation occurs when two similar but different paragraphs are translated in the exact same way. This will apparently remove a paragraph of the translation. To fix the problem, it is sufficient to slightly alter one of the translations in the document. You can also prefer to kill the second paragraph in the original document.

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

•

As a final note, do not be too surprised if the first synchronization of your PO file takes a long time. This is because most of the msgid of the PO file resulting from the gettextization don’t match exactly any element of the POT file built from the recent master files. This forces gettext to search for the closest one using a costly string proximity algorithm.

For example, the first po4a-updatepo of the Perl documentation’s French translation (5.5 MB PO file) took about 48 hours (yes, two days) while the subsequent ones only take a dozen of seconds.

VOIR AUSSI

po4a-gettextize(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a(7).

AUTEURS

 Denis Barbier <barbier [AT] linuxfr.org>
 Nicolas François <nicolas.francois [AT] centraliens.net>
 Martin Quinson (mquinson#debian.org)

TRADUCTION

 Martin Quinson (mquinson#debian.org)

COPYRIGHT ET LICENCE

Ce programme est un logiciel libre ; vous pouvez le copier et / ou le modifier sous les termes de la GPL (voir le fichier COPYING ).