.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "PO4A-GETTEXTIZE 1p" .TH PO4A-GETTEXTIZE 1p "2020-12-09" "Outils po4a" "Outils po4a" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NOM" .IX Header "NOM" po4a\-gettextize \- Convertir un fichier original (et sa traduction) en fichier \s-1PO\s0 .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBpo4a\-gettextize\fR \fB\-f\fR \fIfmt\fR \fB\-m\fR \fImaître.doc\fR [\fB\-l\fR \fI\s-1XX\s0.doc\fR] \fB\-p\fR \&\fI\s-1XX\s0.po\fR .PP (\fI\s-1XX\s0.po\fR est le fichier de sortie, tous les autres sont des entrées) .SH "DESCRIPTION" .IX Header "DESCRIPTION" po4a (\s-1PO\s0 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 \fBpo4a\fR\|(7) pour une introduction en douceur à ce projet. .PP Le script \fBpo4a\-gettextize\fR sert à convertir des fichiers de documentation depuis leur format d’origine vers le format \s-1PO.\s0 Vous n’avez besoin de lui que pour configurer votre projet de traduction avec po4, jamais par la suite. .PP Si vous partez de zéro, \fBpo4a\-gettextize\fR extraira les chaînes traduisibles de la documentation et écrira un fichier \s-1POT.\s0 Si vous fournissez un fichier traduit pré\-existant avec l'indicateur \fB\-l\fR, \fBpo4a\-gettextize\fR essaiera d'utiliser les traductions qu'il contient dans le fichier \s-1PO\s0 produit. Ce processus reste fastidieux et manuel, comme expliqué dans la section «Convertir une traduction manuelle vers po4a» ci-dessous. .PP Si le document maître contient des caractères non \s-1ASCII,\s0 il convertit les fichiers \s-1PO\s0 en \s-1UTF\-8\s0 (si ce n’est pas déjà le cas). Sinon (si le document maître ne contient que des caractères \s-1ASCII\s0), le fichier \s-1PO\s0 généré utilisera l’encodage du document traduit donné en entrée, ou en \s-1UTF\-\s0 si aucun document traduit n’est fourni. .SH "OPTIONS" .IX Header "OPTIONS" .IP "\fB\-f\fR, \fB\-\-format\fR" 4 .IX Item "-f, --format" Type de format de la documentation que vous souhaitez traiter. Utilisez l’option \fB\-\-help\-format\fR pour afficher la liste des formats disponibles. .IP "\fB\-m\fR, \fB\-\-master\fR" 4 .IX Item "-m, --master" Fichier contenant le document maître à traduire. Vous pouvez utiliser cette option plusieurs fois si vous voulez gettextizer plusieurs documents. .IP "\fB\-M\fR, \fB\-\-master\-charset\fR" 4 .IX Item "-M, --master-charset" Jeu de caractères du fichier contenant les documents à traduire. .IP "\fB\-l\fR, \fB\-\-localized\fR" 4 .IX Item "-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. .IP "\fB\-L\fR, \fB\-\-localized\-charset\fR" 4 .IX Item "-L, --localized-charset" Jeu de caractères du fichier contenant le document traduit. .IP "\fB\-p\fR, \fB\-\-po\fR" 4 .IX Item "-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. .IP "\fB\-o\fR, \fB\-\-option\fR" 4 .IX Item "-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 ». .IP "\fB\-h\fR, \fB\-\-help\fR" 4 .IX Item "-h, --help" Affiche un message d’aide. .IP "\fB\-\-help\-format\fR" 4 .IX Item "--help-format" Énumère les formats de documentations connus de po4a. .IP "\fB\-V\fR, \fB\-\-version\fR" 4 .IX Item "-V, --version" Affiche la version du script et quitte. .IP "\fB\-v\fR, \fB\-\-verbose\fR" 4 .IX Item "-v, --verbose" Rend le programme plus bavard. .IP "\fB\-d\fR, \fB\-\-debug\fR" 4 .IX Item "-d, --debug" Affiche quelques informations de débogage. .IP "\fB\-\-msgid\-bugs\-address\fR \fBadresse@email\fR" 4 .IX Item "--msgid-bugs-address adresse@email" Fixe l’adresse à laquelle les bogues des msgid doivent être envoyés. Par défaut, les fichiers \s-1POT\s0 créés n’ont pas de champ Report-Msgid-Bugs-To. .IP "\fB\-\-copyright\-holder\fR \fIchaîne\fR" 4 .IX Item "--copyright-holder chaîne" Fixe le détenteur du copyright dans l’en\-tête du fichier \s-1POT.\s0 La valeur par défaut est « Free Software Foundation, Inc. ». .IP "\fB\-\-package\-name\fR \fIchaîne\fR" 4 .IX Item "--package-name chaîne" Fixe le nom du paquet pour l’en\-tête du fichier \s-1POT.\s0 La valeur par défaut est « \s-1PACKAGE\s0 ». .IP "\fB\-\-package\-version\fR \fIchaîne\fR" 4 .IX Item "--package-version chaîne" Fixe la version du paquet pour l’en\-tête du fichier \s-1POT.\s0 La valeur par défaut est « \s-1VERSION\s0 ». .SS "Convertir une traduction manuelle vers po4a" .IX Subsection "Convertir une traduction manuelle vers po4a" \&\fBpo4a\-gettextize\fR va essayer d’extraire le contenu de n’importe quel fichier de traduction fourni, et utiliser son contenu en tant que msgstr du fichier \s-1PO\s0 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. .PP À 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. .PP .Vb 1 \& Original Traduction \& \& chapitre chapitre \& paragraphe paragraphe \& paragraphe paragraphe \& paragraphe chapitre \& chapitre paragraphe \& paragraphe paragraphe .Ve .PP \&\fBpo4a\-gettextize\fR 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. .PP 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 \fIfuzzy\fR 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. .PP 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 \fImaster.doc\fR qui a été utilisée pour la traduction, et de ne mettre à jour le fichier \s-1PO\s0 par rapport au dernier fichier maître qu'une fois la «gettextisation» réussie. .PP Si vous avez de la chance pour avoir une correspondance parfaite dans la structure des fichiers, construire un fichier \s-1PO\s0 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. .PP 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. .SS "Trucs et astuces pour le processus de «gettextisation»" .IX Subsection "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 \fBdiff\fR\|(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. .PP Que cela arrive, tout le jeu consiste à aligner de nouveaux de ces fichues structures de fichier par des modifications manuelles. \fBpo4a\-gettextize\fR 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 \s-1PO\s0 généré ainsi sera écrit dans \fIgettextization.failed.po\fR pour permettre leur inspection. .PP Voici encore quelques astuces pour vous aider dans ce processus fastidieux : .IP "\(bu" 4 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 \fBpo4a\fR\|(7)). .IP "\(bu" 4 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 \s-1PO,\s0 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 \s-1PO.\s0 .IP "\(bu" 4 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 \s-1PO\s0 avec le document. .IP "\(bu" 4 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 ;) .IP "\(bu" 4 Parfois, le contenu des paragraphes correspond, mais pas leur type. Corriger cela dépend du format. Pour les formats \s-1POD\s0 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 \s-1XML.\s0 .Sp De la même façon, deux paragraphes peuvent avoir été combinés, dans le format \s-1POD,\s0 si la ligne qui les sépare contient des espaces, ou s’il n’y a pas de ligne vide entre la ligne \fB=item\fR et le contenu de cet élément. .IP "\(bu" 4 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 \fIgettextization.failed.po\fR, et corrigez le problème là où est vraiment. .IP "\(bu" 4 Dans certaines configurations malheureuses, vous aurez l’impression que po4a a oublié des parties du texte original ou de la traduction. \fIgettextization.failed.po\fR 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. .Sp 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 \s-1PO,\s0 mais une nouvelle référence est ajoutée à l’entrée existante. .Sp 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. .Sp À 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. .IP "\(bu" 4 Pour finir, ne soyez pas trop surpris si la première synchronisation de votre fichier \s-1PO\s0 prend du temps. En effet, la plupart des «msgid» du fichier \&\s-1PO\s0 résultant de la «gettextisation» ne correspondent exactement à aucun élément du fichier \s-1POT\s0 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. .Sp Par exemple, le premier \fBpo4a\-updatepo\fR de la traduction française de la documentation Perl (fichier \s-1PO\s0 de 5,5 Mo) a pris environ 48 heures (oui, deux jours) tandis que les suivants ne prennent qu'une dizaine de secondes. .SH "VOIR AUSSI" .IX Header "VOIR AUSSI" \&\fBpo4a\-gettextize\fR\|(1), \fBpo4a\-normalize\fR\|(1), \fBpo4a\-translate\fR\|(1), \&\fBpo4a\-updatepo\fR\|(1), \fBpo4a\fR\|(7). .SH "AUTEURS" .IX Header "AUTEURS" .Vb 3 \& Denis Barbier \& Nicolas François \& Martin Quinson (mquinson#debian.org) .Ve .SH "TRADUCTION" .IX Header "TRADUCTION" .Vb 1 \& Martin Quinson (mquinson#debian.org) .Ve .SH "COPYRIGHT ET LICENCE" .IX Header "COPYRIGHT ET LICENCE" Copyright 2002\-2020 by \s-1SPI,\s0 inc. .PP Ce programme est un logiciel libre ; vous pouvez le copier et / ou le modifier sous les termes de la \s-1GPL\s0 (voir le fichier \s-1COPYING\s0).