.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" 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 7" .TH PO4A 7 "2023-01-03" "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 \- Cadre de travail pour la traduction de documentations et autres documents .SH "Introduction" .IX Header "Introduction" po4a (\s-1PO\s0 for anything = \s-1PO\s0 pour tout) facilite la maintenance de la traduction de la documentation en utilisant les outils classiques de gettext. La principale caractéristique de po4a est qu'il dissocie la traduction du contenu et la structure du document. .PP Ce document sert d'introduction au projet po4a en mettant l'accent sur les utilisateurs potentiels qui envisagent d'utiliser cet outil et sur les curieux qui souhaitent comprendre pourquoi les choses sont comme elles sont. .SH "Pourquoi po4a ?" .IX Header "Pourquoi po4a ?" Le concept des logiciels à sources ouverts est de rendre la technologie réellement disponible pour tout le monde. Mais, la licence n’est pas la seule préoccupation, un logiciel ouvert est inutile pour des utilisateurs non anglophones. En conséquence, nous avons encore du travail pour rendre le logiciel disponible pour tous. .PP Cette situation est bien comprise par la plupart des projets et tout le monde est désormais convaincu de la nécessité de tout traduire. Pourtant, les traductions représentent un effort énorme de nombreuses personnes, paralysées par de petites difficultés techniques. .PP Heureusement, les logiciels ouverts sont réllement très bien traduits en utilisant la suite d’outils gettext. Ces outils sont utilisés pour extraire les chaînes à traduire d’un programme et pour présenter les chaînes à traduire dans un format standardisé (appelés fichiers \s-1PO\s0 ou catalogue de traduction). Tout un écosystème d’outils a émergé pour aider les traducteurs à traduire réellement ces fichiers \s-1PO.\s0 Le résultat est alors utilisé par gettext à l'exécution pour afficher les messages traduits aux utilisateurs. .PP En ce qui concerne la documentation, cependant, la situation est quelque peu décevante. Au début, la traduction de la documentation peut sembler plus facile que la traduction d'un programme car il semblerait que vous deviez simplement copier le fichier source de la documentation et commencer à traduire le contenu. Cependant, lorsque la documentation originale est modifiée, le suivi des modifications se transforme rapidement en cauchemar pour les traducteurs. Si elle est effectuée manuellement, cette tâche est désagréable et sujette aux erreurs. .PP Les traductions obsolètes sont souvent pires que pas de traduction du tout. Les utilisateurs finaux peuvent être trompés par la documentation décrivant un ancien comportement du programme. De plus, ils ne peuvent pas interagir directement avec les mainteneurs car ils ne parlent pas anglais. De plus, le mainteneur ne peut pas résoudre le problème car il ne connaît pas toutes les langues dans lesquelles sa documentation est traduite. Ces difficultés, souvent causées par un mauvais outillage, peuvent miner la motivation des traducteurs bénévoles, aggravant encore le problème. .PP \&\fBLe but du projet po4a est de faciliter le travail des traducteurs de documentation\fR. En particulier, il rend les traductions de documentation \fImaintenables\fR. .PP L'idée est de réutiliser et d'adapter l'approche gettext à ce domaine. Comme pour gettext, les textes sont extraits de leur emplacement d'origine et présentés aux traducteurs sous forme de catalogues de traduction \s-1PO.\s0 Les traducteurs peuvent exploiter les outils classiques de gettext pour suivre le travail à faire, collaborer et s'organiser en équipes. po4a injecte ensuite les traductions directement dans la structure de la documentation pour produire des fichiers source traduits qui peuvent être traités et distribués comme les fichiers anglais. Tout paragraphe qui n'est pas traduit est laissé en anglais dans le document résultant, garantissant que les utilisateurs finaux ne voient jamais une traduction obsolète dans la documentation. .PP Ceci automatise la plupart des gros travaux de maintenance de la traduction. La découverte des paragraphes nécessitant une mise à jour devient très facile et le processus est complètement automatisé lorsque les éléments sont réorganisés sans autre modification. Une vérification spécifique peut également être utilisée pour réduire le risque d'erreurs de formatage qui entraîneraient un document altéré. .PP Veuillez également consulter la \fB\s-1FAQ\s0\fR plus bas dans ce document pour une liste plus complète des avantages et inconvénients de cette approche. .SS "Formats pris en charge" .IX Subsection "Formats pris en charge" Actuellement, cette approche a été implémentée avec succès pour un certain nombre de formats de mise en page de texte : .IP "man (analyseur stable)" 4 .IX Item "man (analyseur stable)" Le bon vieux format des pages de manuel, utilisé par beaucoup de programmes. Le support de po4a pour ce format est très utile parce que ce format est assez compliqué, surtout pour les débutants. .Sp Le module \fBLocale::Po4a::Man\fR\|(3pm) prend également en charge le format mdoc, utilisé par les pages de manuel \s-1BSD\s0 (ils sont également assez courants sous Linux). .IP "AsciiDoc (analyseur stable)" 4 .IX Item "AsciiDoc (analyseur stable)" Ce format est un format de balisage léger destiné à faciliter la création de documentation. Il est par exemple utilisé pour documenter le système git. Ces pages de manuel sont traduites à l'aide de po4a. .Sp Voir Locale::Po4a::AsciiDoc pour plus de détails. .IP "pod (analyseur stable)" 4 .IX Item "pod (analyseur stable)" C’est le format pour la documentation en ligne de Perl (« Perl Online Documentation »). Le langage et ses documentations sont documentés en utilisant ce format en plus de la majorité des scripts Perl existants. Il permet de garder la documentation plus fidèle au code en les intégrant tous deux au même fichier. Il rend la vie du programmeur plus simple, mais malheureusement pas celle du traducteur jusqu'à ce que vous utilisiez po4a. .Sp Voir Locale::Po4a::Pod pour plus de détails. .IP "sgml (analyseur stable)" 4 .IX Item "sgml (analyseur stable)" Même s’il est de plus en plus remplacé par le \s-1XML,\s0 ce format est encore assez utilisé pour les documents dont la taille dépasse plusieurs écrans. Il permet même de faire des livres complets. Des documents aussi longs peuvent être vraiment complexes à traduire. \fBdiff\fR se montre souvent inutile quand le document original a été réindenté après une mise à jour. Heureusement, po4a vous aide dans cette tâche. .Sp Actuellement, seules les \s-1DTD\s0 DebianDoc et DocBook sont prises en charge, mais l’ajout d’une nouvelle \s-1DTD\s0 est très facile. Il est même possible d’utiliser po4a avec une \s-1DTD SGML\s0 inconnue sans modifier le code en fournissant les informations nécessaires sur la ligne de commande. Veuillez consulter \fBLocale::Po4a::Sgml\fR\|(3pm) pour plus de détails. .IP "TeX / LaTeX (analyseur stable)" 4 .IX Item "TeX / LaTeX (analyseur stable)" Le format LaTeX est un format majeur utilisé pour les documentations dans le monde du logiciel libre ou pour des publications. .Sp Le module \fBLocale::Po4a::LaTeX\fR\|(3pm) a été testé avec la documentation de Python, un livre et avec quelques présentations. .IP "text (analyseur stable)" 4 .IX Item "text (analyseur stable)" Le format Text est le format de base pour de nombreux formats qui incluent de longs blocs de texte, y compris Markdown, fortunes, sections préliminaires \s-1YAML,\s0 debian/changelog et debian/control. .Sp Ceci prend en charge le format commun utilisé dans les générateurs de sites statiques, les \s-1README\s0 et d'autres systèmes de documentation. Voir \fBLocale::Po4a::Text\fR\|(3pm) pour plus de détails. .IP "xml and \s-1XHMTL\s0 (analyseur probablement stable)" 4 .IX Item "xml and XHMTL (analyseur probablement stable)" Le format \s-1XML\s0 est à la base de beaucoup de formats pour la documentation. .Sp À ce jour, la \s-1DTD\s0 DocBook (veuillez consulter \fBLocale::Po4a::Docbook\fR\|(3pm) pour plus de détails) et \s-1XHTML\s0 sont pris en charge par po4a. .IP "BibTex (analyseur probablement stable)" 4 .IX Item "BibTex (analyseur probablement stable)" Le format BibTex est utilisé conjointement avec LaTex pour la mise en forme des listes de références (bibliographies). .Sp Voir Locale::Po4a::BibTex pour plus de détails. .IP "DocBook (analyseur probablement stable)" 4 .IX Item "DocBook (analyseur probablement stable)" Un langage de balisage basé sur \s-1XML\s0 qui utilise des balises sémantiques pour décrire des documents. .Sp Voir Locale::Po4a:Docbook pour plus de détails. .IP "Guide \s-1XML\s0 (analyseur probablement stable)" 4 .IX Item "Guide XML (analyseur probablement stable)" Un format de documentation \s-1XML.\s0 Ce module a été développé spécifiquement pour aider à prendre en charge et à maintenir les traductions de la documentation de Gentoo Linux jusqu'à au moins mars 2016 (basé sur la Wayback Machine). Gentoo est depuis passé au format DevBook \s-1XML.\s0 .Sp Voir Locale::Po4a:Guide pour plus de détails. .IP "Wml (analyseur probablement stable)" 4 .IX Item "Wml (analyseur probablement stable)" Le Web Markup Language, ne pas confondre le \s-1WML\s0 avec le \s-1WAP\s0 utilisé sur les téléphones portables. Ce module s'appuie sur le module Xhtml, qui lui\-même s'appuie sur le module XmL. .Sp Voir Locale::Po4a::Wml pour plus de détails. .IP "Yaml (analyseur probablement stable)" 4 .IX Item "Yaml (analyseur probablement stable)" Un sur-ensemble strict de \s-1JSON. YAML\s0 est souvent utilisé comme systèmes ou projets de configuration. \s-1YAML\s0 est au cœur d’Ansible de Red Hat. .Sp Voir Locale::Po4a::Yaml pour plus de détails. .IP "RubyDoc (analyseur probablement stable)" 4 .IX Item "RubyDoc (analyseur probablement stable)" Le format Ruby Document (\s-1RD\s0), à l'origine le format de documentation par défaut pour Ruby et les projets Ruby avant d'être la conversion à RDoc en 2002. Bien qu'apparemment la version japonaise du Manuel de Référence Ruby utilise toujours le \s-1RD.\s0 .Sp Voir Locale::Po4a::RubyDoc pour plus de détails. .IP "Halibut (analyseur très expérimental)" 4 .IX Item "Halibut (analyseur très expérimental)" Un système de production de documentation, avec des éléments similaires à TeX, debiandoc-sgml, TeXinfo, et autres, développé par Simon Tatham, le développeur de PuTTY. .Sp Voir Locale::Po4a:Halibut pour plus de détails. .IP "Ini (analyseur très expérimental)" 4 .IX Item "Ini (analyseur très expérimental)" Format de fichier de configuration popularisé par MS-DOS. .Sp Voir Locale::Po4a::Ini pour plus de détails. .IP "texinfo (analyseur très expérimental)" 4 .IX Item "texinfo (analyseur très expérimental)" Toutes les documentations du projet \s-1GNU\s0 sont écrites dans ce format (c’est même une des exigences pour devenir un projet officiel du projet \s-1GNU\s0). La prise en charge pour \fBLocale::Po4a::Texinfo\fR\|(3pm) dans po4a en est encore à ses début. Veuillez nous envoyer des rapports de bogue ou des demandes de nouvelle fonctionnalité. .IP "Autres formats supportés" 4 .IX Item "Autres formats supportés" Po4a peut également gérer des formats plus rares et plus spécifiques, tels que celui de la documentation des options de compilation des noyaux Linux 2.4+ (Locale::Po4a::KernelHelp) ou les diagrammes produits par l’outil dia (Locale::Po4a:Dia). L’ajout d’un nouveau format est souvent très simple, et consiste principalement à fournir un interpréteur pour le format voulu. Consulter \fBLocale::Po4a::TransTractor\fR\|(3pm) pour en savoir plus. .IP "Formats non supportés" 4 .IX Item "Formats non supportés" Malheureusement, po4a soufre d’un manque de prise en charge de divers formats de documentation. Beaucoup d’entre eux seraient simple à prendre en charge dans po4a. Cela inclut des formats étant utilisés pour plus que de la documentation, tels que les descriptions de paquets (deb et rpm), aux questions posées par les scripts d’installation, en passant par les fichiers changelog, et de tous les formats spécifiques tels que les scénarios de jeux ou les fichiers de ressource pour wine. .SH "Utiliser po4a" .IX Header "Utiliser po4a" Historiquement, po4a a été construit autour de quatre scripts, chacun remplissant une tâche spécifique. \fBpo4a\-gettextize\fR\|(1) aide à amorcer les traductions et éventuellement à convertir les projets de traduction existants en po4a. \fBpo4a\-updatepo\fR\|(1) reporte les modifications apportées à la documentation d'origine dans les fichiers po correspondants. \fBpo4a\-translate\fR\|(1) construit le fichier source traduit à partir du fichier d'origine et du fichier \s-1PO\s0 correspondant. De plus, \fBpo4a\-normalize\fR\|(1) est surtout utile pour déboguer les analyseurs po4a, car il produit un document non traduit à partir de l'original. Il permet de repérer plus facilement les problèmes introduits par le processus d'analyse. .PP Most projects only require the features of \fBpo4a\-updatepo\fR\|(1) and \fBpo4a\-translate\fR\|(1), but these scripts proved to be cumbersome and error prone to use. If the documentation to translate is split over several source files, it is difficult to keep the \s-1PO\s0 files up to date and build the documentation files correctly. As an answer, a all-in-one tool was provided: \fBpo4a\fR\|(1). This tool takes a configuration file describing the structure of the translation project: the location of the \s-1PO\s0 files, the list of files to translate, and the options to use, and it fully automates the process. When you invoke \fBpo4a\fR\|(1), it both updates the \s-1PO\s0 files and regenerate the translation files that need to. If everything is already up to date, \fBpo4a\fR\|(1) does not change any file. .PP Le reste de cette section donne un aperçu de la façon d'utiliser l'interface des scripts de po4a. La plupart des utilisateurs préféreront probablement utiliser l'outil tout-en-un, qui est décrit dans la documentation de \fBpo4a\fR\|(1). .SS "Résumé graphique des scripts po4a" .IX Subsection "Résumé graphique des scripts po4a" Le schéma suivant donne un aperçu de la façon dont chaque script po4a peut être utilisé. Ici, \fImaster.doc\fR est un exemple de nom pour la documentation à traduire ; \fI\s-1XX\s0.doc\fR est le même document traduit dans la langue \s-1XX\s0 tandis que \fIdoc.XX.po\fR est le catalogue de traduction de ce document dans la langue \s-1XX.\s0 Les auteurs de la documentation seront principalement concernés par \fImaster.doc\fR (qui peut être une page de manuel, un document \s-1XML,\s0 un fichier asciidoc ou similaire) ; les traducteurs seront principalement concernés par le fichier \s-1PO,\s0 tandis que les utilisateurs finaux ne verront que le fichier \fI\s-1XX\s0.doc\fR. .PP .Vb 10 \& maître.doc \& | \& V \& +<\-\-\-\-\-<\-\-\-\-+<\-\-\-\-\-<\-\-\-\-\-<\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\->\-\-\-\-\-\-\-\->\-\-\-\-\-\-\-+ \& : | | : \&{traduction} | { mise à jour de maître.doc } : \& : | | : \& XX.doc | V V \&(optionnel) | maître.doc \->\-\-\-\-\-\-\-\->\-\-\-\-\-\->+ \& : | (nouveau) | \& V V | | \& [po4a\-gettextize] doc.XX.po\-\-\->+ | | \& | (ancien) | | | \& | ^ V V | \& | | [po4a\-updatepo] | \& V | | V \& traduction.pot ^ V | \& | | doc.XX.po | \& | | (fuzzy) | \& { traduction } | | | \& | ^ V V \& | | {édition manuelle} | \& | | | | \& V | V V \& doc.XX.po \-\-\->\-\-\-\->+<\-\-\-<\-\- doc.XX.po addendum maître.doc \& (initial) (à jour) (optionnel) (à jour) \& : | | | \& : V | | \& +\-\-\-\-\->\-\-\-\-\->\-\-\-\-\->\-\-\-\-\-\-> + | | \& | | | \& V V V \& +\-\-\-\-\-\->\-\-\-\-\-+\-\-\-\-\-\-<\-\-\-\-\-\-+ \& | \& V \& [po4a\-translate] \& | \& V \& XX.doc \& (à jour) .Ve .PP Ce schéma est compliqué, mais en pratique, seule la partie de droite (impliquant \fBpo4a\-updatepo\fR\|(1) et \fBpo4a\-translate\fR\|(1)) est utilisée une fois le projet installé et configuré. .PP La partie à gauche montre comment \fBpo4a\-gettextize\fR\|(1) peut être utilisé pour convertir un projet de traduction existant en infrastructure po4a. Ce script prend un document original et son équivalent traduit, et essaie de créer le fichier \s-1PO\s0 correspondant. Une telle conversion manuelle est assez lourde (voir la documentation \fBpo4a\-gettextize\fR\|(1) pour plus de détails), mais elle n'est nécessaire qu'une seule fois pour convertir vos traductions existantes. Si vous n'avez aucune traduction à convertir, vous pouvez oublier cela et vous concentrer sur la partie droite du schéma. .PP En haut à droite est décrit ce qui est relève de l’auteur du document d’origine, la mise à jour de la documentation. Au milieu à droite sont décrites les actions automatisées par \fBpo4a\-updatepo\fR\|(1). Les nouvelles chaînes sont extraites et comparées avec la traduction existante. La traduction existante est utilisée pour les parties n’ayant pas changé, alors que celles qui ont été en partie modifiées sont également associées à leur ancienne traduction, mais avec un marquage \*(L"fuzzy\*(R" indiquant que la traduction doit être mise à jour. Un contenu nouveau ou fortement modifié est laissé non traduit. .PP Ensuite, l'étape \fImanual editing\fR (= édition manuelle) décrit l'action des traducteurs, qui modifient les fichiers \s-1PO\s0 pour fournir des traductions à chaque chaîne et paragraphe d'origine. Cela peut être fait en utilisant un éditeur spécifique tel que \fB\s-1GNOME\s0 Translation Editor\fR, \fBLokalize\fR de \s-1KDE\s0 ou \fBpoedit\fR, ou en utilisant une plateforme de localisation en ligne telle que \fBweblate\fR ou \fBpootle\fR. Le résultat de la traduction est un ensemble de fichiers \s-1PO,\s0 un par langue. Veuillez vous référer à la documentation de gettext pour plus de détails. .PP La partie inférieure de la figure montre comment \fBpo4a\-translate\fR\|(1) crée un document source traduit à partir du document original \fImaster.doc\fR et du catalogue de traduction \fIdoc.XX.po\fR mis à jour par les traducteurs . La structure du document est réutilisée, tandis que le contenu original est remplacé par son équivalent traduit. En option, un addendum peut être utilisé pour ajouter du texte supplémentaire à la traduction. Ceci est souvent utilisé pour ajouter le nom du traducteur au document final. Voir ci-dessous pour plus de détails. .PP Comme indiqué précédemment, le programme \fBpo4a\fR\|(1) combine les effets des scripts séparés, mettant à jour les fichiers \s-1PO\s0 et le document traduit en un seul appel. La logique sous-jacente reste la même. .SS "Commencer une nouvelle traduction" .IX Subsection "Commencer une nouvelle traduction" Si vous utilisez \fBpo4a\fR\|(1), il n'y a pas d'étape spécifique pour démarrer une traduction. Il vous suffit de lister les langues dans le fichier de configuration et les fichiers \s-1PO\s0 manquants sont automatiquement créés. Naturellement, le traducteur doit alors fournir des traductions pour chaque contenu utilisé dans vos documents. \fBpo4a\fR\|(1) crée également un fichier \s-1POT,\s0 qui est un fichier modèle \s-1PO.\s0 Les traducteurs potentiels peuvent traduire votre projet dans une nouvelle langue en renommant ce fichier et en fournissant les traductions dans leur langue. .PP Si vous préférez utiliser les scripts individuels séparément, vous devez utiliser \fBpo4a\-gettextize\fR\|(1) comme suit pour créer le fichier \s-1POT.\s0 Ce fichier peut ensuite être copié dans \fI\s-1XX\s0.po\fR pour initialiser une nouvelle traduction. .PP .Vb 1 \& $ po4a\-gettextize \-\-format \-\-master \-\-po .Ve .PP Le document maître est utilisé en entrée, tandis que le fichier \s-1POT\s0 est la sortie de ce processus. .SS "Intégrer les modifications du document d'origine" .IX Subsection "Intégrer les modifications du document d'origine" Le script à utiliser pour cela est \fBpo4a\-updatepo\fR\|(1) (veuillez vous référer à sa documentation pour plus de détails) : .PP .Vb 1 \& $ po4a\-updatepo \-\-format \-\-master \-\-po .Ve .PP Le document maître est utilisé en entrée, tandis que le fichier \s-1PO\s0 est mis à jour : il est utilisé à la fois en entrée et en sortie. .SS "Générer un document traduit" .IX Subsection "Générer un document traduit" Une fois que la traduction est effectuée, il faut générer la documentation traduite et la distribuer avec l’original. Pour cela, utilisez \fBpo4a\-translate\fR\|(1) de la façon suivante : .PP .Vb 1 \& $ po4a\-translate \-\-format \-\-master \-\-po \-\-localized .Ve .PP Les fichiers maître et \s-1PO\s0 sont utilisés en entrée, tandis que le fichier traduit est la sortie de ce processus. .SS "Utiliser les addenda pour ajouter du texte supplémentaire aux traductions" .IX Subsection "Utiliser les addenda pour ajouter du texte supplémentaire aux traductions" Ajouter un nouveau texte à la traduction est probablement la seule chose qui soit plus facile à long terme lorsque vous traduisez des fichiers manuellement :). Cela se produit lorsque vous souhaitez ajouter une section supplémentaire au document traduit, ne correspondant à aucun contenu du document d'origine. Le cas d'usage classique consiste à donner des crédits à l'équipe de traduction et à indiquer comment signaler les problèmes spécifiques à la traduction. .PP Avec po4a, vous devez spécifier les fichiers \fBaddendum\fR, qui peuvent être conceptuellement considérés comme des correctifs appliqués au document localisé après traitement. Chaque addendum doit être fourni dans un fichier séparé, dont le format est cependant très différent des correctifs classiques. La première ligne est une \fIligne d'en\-tête\fR, définissant le point d'insertion de l'addendum (avec une syntaxe malheureusement obscure \- voir ci-dessous) tandis que le reste du fichier est ajouté textuellement à la position déterminée. .PP La ligne d'en\-tête doit commencer par la chaîne \fB\s-1PO4A\-HEADER:\s0\fR, suivie d'une liste de champs \fIclé\fR\fB=\fR\fIvaleur\fR séparés par des points-virgules. .PP Par exemple, l'en\-tête suivant déclare un addendum qui doit être placé à la toute fin de la traduction. .PP .Vb 1 \& PO4A\-HEADER: mode=eof .Ve .PP Les choses sont plus complexes lorsque vous souhaitez ajouter votre contenu supplémentaire au milieu du document. L'en\-tête suivant déclare un addendum qui doit être placé après la section \s-1XML\s0 contenant la chaîne \f(CW\*(C`About this document\*(C'\fR en traduction. .PP .Vb 1 \& PO4A\-HEADER: position=Au sujet de…; mode=after; endboundary= .Ve .PP En pratique, en essayant d'appliquer un addendum, po4a recherche la première ligne correspondant à l'argument \f(CW\*(C`position\*(C'\fR (cela peut être une expression régulière regexp). N'oubliez pas que po4a considère ici le document \fBtraduit\fR. Cette documentation est en anglais, mais votre ligne devrait probablement se lire comme suit si vous souhaitez que votre addendum s'applique à la traduction française du document. .PP .Vb 1 \& PO4A\-HEADER: position=À propos de ce document; mode=after; endboundary= .Ve .PP Une fois que la \f(CW\*(C`position\*(C'\fR est trouvée dans le document cible, po4a recherche la ligne suivante après la \f(CW\*(C`position\*(C'\fR qui correspond au \f(CW\*(C`endboundary\*(C'\fR fourni. L'addendum est ajouté juste \fBaprès\fR cette ligne (car nous avons fourni un \fIendboundary\fR, c'est\-à\-dire une limite terminant la section courante). .PP Le même effet pourrait être obtenu avec l'en\-tête suivant, qui est équivalent : .PP .Vb 1 \& PO4A\-HEADER: position=Au sujet de…; mode=after; beginboundary=
.Ve .PP Ici, po4a recherche la première ligne correspondant à \f(CW\*(C` après la ligne correspondant à \f(CW\*(C`About this document\*(C'\fR dans la traduction, et ajoute l'addendum \fBavant\fR cette ligne puisque nous avons fourni un \fIbeginboundary\fR, c'est\-à\-dire une limite marquant le début de la section suivante. Donc, cette ligne d'en\-tête impose de placer l'addendum après la section contenant \f(CW\*(C`About this document\*(C'\fR, et d'informer po4a qu'une section commence par une ligne contenant la balise \f(CW\*(C`. C'est équivalent à l'exemple précédent car ce que vous voulez vraiment, c'est ajouter cet addendum soit après \f(CW\*(C`/section\*(C'\fR> soit avant \f(CW\*(C`. .PP Vous pouvez également définir le \fImode\fR insertion sur la valeur \f(CW\*(C`before\*(C'\fR, avec une sémantique similaire : combiner \f(CW\*(C`mode=before\*(C'\fR avec un \f(CW\*(C`endboundary\*(C'\fR mettra l'addendum juste \fBaprès\fR la limite correspondante, qui est la dernière limite potentielle avant la \f(CW\*(C`position\*(C'\fR. La combinaison de \f(CW\*(C`mode=before\*(C'\fR avec un \f(CW\*(C`beginboundary\*(C'\fR placera l'addendum juste \fBavant\fR la limite correspondante, c'est\-à\-dire la dernière limite potentielle avant la \f(CW\*(C`position\*(C'\fR. .PP .Vb 7 \& Mode | Type de limite | Limite utilisée | Point d\*(Aqinsertion par rapport à la limite \& ========|===============|========================|========================================= \& \*(Aqbefore\*(Aq| \*(Aqendboundary\*(Aq | dernière avant la \*(Aqposition\*(Aq | Juste après la limite \& \*(Aqbefore\*(Aq|\*(Aqbeginboundary\*(Aq| dernière avant la \*(Aqposition\*(Aq | Juste avant la limite \& \*(Aqafter\*(Aq | \*(Aqendboundary\*(Aq | première après la \*(Aqposition\*(Aq | Juste après la limite \& \*(Aqafter\*(Aq |\*(Aqbeginboundary\*(Aq| première après la \*(Aqposition\*(Aq | Juste avant la limite \& \*(Aqeof\*(Aq | (rien) | sans objet | Fin de fichier .Ve .PP \fITrucs et astuces sur les addenda\fR .IX Subsection "Trucs et astuces sur les addenda" .IP "\(bu" 4 Gardez à l’esprit que ce sont des expressions rationnelle. Par exemple, si vous voulez correspondre à la fin d’une section nroff terminant par la ligne \f(CW\*(C`.fi\*(C'\fR, n’utilisez pas \f(CW\*(C`.fi\*(C'\fR comme valeur pour \fBendboundary\fR, parce que cala correspondra également à \f(CW\*(C`ce[ fi]chier\*(C'\fR, ce qui n’est évidemment pas ce que vous voulez. La valeur du champ \fBendboundary\fR dans ce cas est \f(CW\*(C`^\e.fi$\*(C'\fR. .IP "\(bu" 4 Les espaces \s-1SONT\s0 importants dans le contenu de la \f(CW\*(C`position\*(C'\fR et des limites. Donc les deux lignes suivantes \fBsont différentes\fR. La seconde ne sera trouvé que s'il y a suffisamment d'espaces de fin dans le document traduit. .Sp .Vb 2 \& PO4A\-HEADER: position=À propos de ce document; mode=after; beginboundary=
\& PO4A\-HEADER: position=À propos de ce document; mode=after; beginboundary=
.Ve .IP "\(bu" 4 Bien que cette recherche contextuelle puisse être considérée comme opérant à peu près sur toutes les lignes du document \fBtraduit\fR, elle opère en fait sur la chaîne de caractères des données internes à po4a. Cette chaîne de caractères des données internes peut être aussi bien un texte s'étendant sur un paragraphe et contenant plusieurs lignes, ou bien peut être un marqueur \s-1XML\s0 isolé. Le \fIpoint d'insertion\fR exact de l'addendum doit donc être placé avant ou après cette chaîne de caractères des données internes et ne peut pas être à l'intérieur de celle-ci. .IP "\(bu" 4 Passez l'argument \fB\-vv\fR à po4a pour comprendre comment les addenda sont ajoutés à la traduction. Il peut également être utile d'exécuter po4a en mode débogage pour voir la chaîne de données interne réelle lorsque votre addendum ne s'applique pas. .PP \fIExemples d'addenda\fR .IX Subsection "Exemples d'addenda" .IP "\(bu" 4 Si vous voulez ajouter quelque chose après la section nroff suivante : .Sp .Vb 1 \& .SH "AUTEURS" .Ve .Sp Vous devez sélectionner une approche en deux étapes en définissant \fBmode=after\fR. D'abord, vous devez restreindre la recherche à la ligne après \fB\s-1AUTHORS\s0\fR avec l'argument de \fBposition\fR. Ensuite, vous devez faire correspondre le début de la section suivante (c'est\-à\-dire, \fB^\e.SH\fR) avec l'argument de \fBbeginboundary\fR. C'est\-à\-dire : .Sp .Vb 1 \& PO4A\-HEADER:mode=after;position=AUTEURS;beginboundary=\e.SH .Ve .IP "\(bu" 4 Si vous voulez ajouter quelque chose juste après une ligne donnée (par exemple après « Copyright Bidule »), utilisez une \fBposition\fR correspondant à cette ligne, un \fBmode=after\fR et renseignez un champ \fBbeginboundary\fR correspondant à n’importe quelle ligne. .Sp .Vb 1 \& PO4A\-HEADER:mode=after;position=Copyright Tralala, 2004;beginboundary=^ .Ve .IP "\(bu" 4 Si vous voulez ajouter quelque chose à la fin du document, donnez une position correspondant à n’importe quelle ligne du document (mais à une seule ligne, puisque po4a n’acceptera pas que la position ne corresponde pas à une ligne unique), et donnez un champ \fBendboundary\fR ne correspondant à aucune ligne. N’utilisez pas de chaîne simple, comme \fB\*(L"\s-1EOF\*(R"\s0\fR, mais préférez\-en une qui a une chance moindre de se trouver dans votre document. .Sp .Vb 1 \& PO4A\-HEADER:mode=after;position=Au sujet de…;beginboundary=FausseLimitePo4a .Ve .PP \fIExemple plus détaillé\fR .IX Subsection "Exemple plus détaillé" .PP Document original (au format \s-1POD :\s0 .PP .Vb 7 \& |=head1 NAME \& | \& |dummy \- a dummy program \& | \& |=head1 AUTHOR \& | \& |me .Ve .PP Voici maintenant un addendum qui s’assure qu’une section est ajoutée à la fin du fichier pour indiquer le traducteur. .PP .Vb 6 \& |PO4A\-HEADER:mode=after;position=AUTEUR;beginboundary=^=head \& | \& |=head1 TRADUCTEUR \& | \& |moi \& | .Ve .PP Pour placer l’addendum avant l’AUTEUR (section nommée \s-1AUTHOR\s0 dans le document original), utilisez l’en\-tête suivant : .PP .Vb 1 \& PO4A\-HEADER:mode=after;position=NOM;beginboundary=^=head1 .Ve .PP Ceci fonctionne parce que la première ligne correspondant à l’expression rationnelle donnée dans le champ \fBbeginboundary\fR (/^=head1/) après la section « \s-1NOM\s0 » (correspondant à la section « \s-1NAME\s0 » dans le document original), est celle indiquant les auteurs. De cette façon, l’addendum est placé entre les deux sections. Notez que si une autre section est ajoutée entre \s-1NOM\s0 et \s-1AUTEUR,\s0 po4a ajoutera l’addendum par erreur avant la nouvelle section. .PP Pour éviter cela, vous pouvez utiliser \fBmode\fR=\fIbefore\fR : .PP .Vb 1 \& PO4A\-HEADER:mode=before;position=^=head1 AUTEUR .Ve .SH "Comment ça marche ?" .IX Header "Comment ça marche ?" Cette section vous donne un bref aperçu des rouages internes de po4a afin que vous vous sentiez plus à même de nous aider à le maintenir et l’améliorer. Elle peut également vous permettre de comprendre pourquoi cela ne fait pas ce que vous souhaitez et corriger vos problèmes par vous\-même. .PP L’architecture po4a est orientée objet. La classe \fBLocale::Po4a::TransTractor\fR\|(3pm) est l’ancêtre commun à tous les analyseurs de po4a. Ce nom étrange provient du fait qu’il est à la fois chargé de la traduction et de l’extraction des chaînes du document. .PP Plus formellement, il prend un document à traduire et un fichier \s-1PO\s0 contenant les traductions en entrée et produit en sortie deux autres fichiers : un autre fichier \s-1PO\s0 (résultant de l’extraction des chaînes à traduire du document d’entrée), et un document traduit (avec la même structure que le document d’entrée, mais dont toutes les chaînes à traduire ont été remplacées par leur traduction donnée par le \s-1PO\s0 fournit en entrée). Voici une représentation graphique de tout ceci : .PP .Vb 6 \& document entrée \-\-\e /\-\-\-> document sortie \& \e TransTractor:: / (traduit) \& +\-\->\-\- parse() \-\-\-\-\-\-\-\-+ \& / \e \& PO entrée \-\-\-\-\-\-\-\-/ \e\-\-\-> PO sortie \& (extrait) .Ve .PP Cette forme d’os est le cœur de l’architecture de po4a. Sans le fichier \s-1PO\s0 en entrée et le document en sortie, cela donne \fBpo4a\-gettextize\fR. Si vous fournissez les deux entrées et ignorez le \s-1PO\s0 de sortie, vous aurez \fBpo4a\-translate\fR. Le \fBpo4a\fR appelle deux fois TransTract et appelle \fBmsgmerge \-U\fR entre ces appels pour fournir une solution unique à partir d’un seul fichier de configuration. Lisez \fBLocale::Po4a::TransTractor\fR\|(3pm) pour plus d’informations. .SH "Projets open-source utilisant po4a" .IX Header "Projets open-source utilisant po4a" Voici une liste très partielle des projets qui utilisent po4a en production pour leur documentation. Si vous souhaitez ajouter votre projet à la liste, envoyez-nous simplement un e\-mail (ou une demande de fusion (Merge Request)). .IP "\(bu" 4 adduser (man) : outil de gestion des utilisateurs et des groupes. .IP "\(bu" 4 apt (man, docbook) : Gestionnaire de paquets Debian. .IP "\(bu" 4 aptitude (docbook, svg) : gestionnaire de paquets en mode commande pour Debian .IP "\(bu" 4 site internet F\-Droid (markdown) : catalogue de logiciels libres pour la plateforme Android. .IP "\(bu" 4 git (asciidoc) : système de contrôle de version distribué pour suivre les modifications du code source. .IP "\(bu" 4 manuel Linux (man) .Sp Ce projet fournit une infrastructure pour traduire de nombreuses pages de manuel dans différents langages, prête à être intégrée dans plusieurs distributions majeures (Arch Linux, Debian et dérivés, Fedora). .IP "\(bu" 4 Stellarium (\s-1HTML\s0) : un planétarium open source gratuit pour votre ordinateur. po4a est utilisé pour traduire les descriptions des objets célestes. .IP "\(bu" 4 Autres éléments à trier : .SH "FAQ" .IX Header "FAQ" .SS "Comment prononcer po4a ?" .IX Subsection "Comment prononcer po4a ?" Personnellement, je le prononce comme pouah , qui est une interjection française équivalente à l'anglais yuck :) J'ai peut\-être un étrange sens de l'humour :) .SS "Qu’en est-il des autres outils de traduction de documentation utilisant gettext ?" .IX Subsection "Qu’en est-il des autres outils de traduction de documentation utilisant gettext ?" Il y en a quelques-uns. Voici une liste potentiellement incomplète, et d’autres outils arrivent à l’horizon. .IP "\fBpoxml\fR" 4 .IX Item "poxml" C’est l’outil développé au sein du projet \s-1KDE\s0 pour gérer les \s-1XML\s0 DocBook. C’est à notre connaissance le premier programme qui a extrait des chaînes à traduire d’une documentation pour les mettre dans un fichier \s-1PO,\s0 et les réinjecter ensuite dans le document après la traduction. .Sp Il ne peut gérer que le format \s-1XML,\s0 avec une \s-1DTD\s0 particulière. Je n’aime pas beaucoup la façon dont les listes sont gérées, elles sont rassemblées en un seul gros msgid. Lorsque la liste est de taille importante, les éléments sont assez durs à gérer. .IP "\fBpo-debiandoc\fR" 4 .IX Item "po-debiandoc" Ce programme écrit par Denis Barbier est un précurseur du module \s-1SGML\s0 de po4a, qui le remplace plus ou moins. Comme son nom l’indique, il ne gère que la \s-1DTD\s0 DebianDoc, qui est en voie d’extinction. .IP "\fBxml2po.py\fR" 4 .IX Item "xml2po.py" Utilisé par l'équipe de documentation de \s-1GIMP\s0 depuis 2004, il fonctionne assez bien même si, comme son nom l'indique, il ne fonctionne qu'avec des fichiers \s-1XML\s0 et nécessite des makefiles spécialement configurés. .IP "\fBSphinx\fR" 4 .IX Item "Sphinx" Le projet de documentation Sphinx utilise également gettext de manière intensive pour gérer ses traductions. Malheureusement, il ne fonctionne que pour quelques formats de texte, rest et markdown, bien qu'il soit peut\-être le seul outil à faire cela en gérant l'ensemble du processus de traduction. .PP Le principal avantage de po4a par rapport à eux est la facilité d’ajouter du contenu additionnel (ce qui est encore plus difficile avec ces outils) et la possibilité de faire une gettextization. .SS "RÉSUMÉ des avantages de l’approche basée sur gettext" .IX Subsection "RÉSUMÉ des avantages de l’approche basée sur gettext" .IP "\(bu" 2 Les traductions ne sont pas stockées indépendamment de l’original, ce qui rend possible la détection des parties à mettre à jour. .IP "\(bu" 2 Les traductions sont stockées dans des fichiers différents pour chaque langue, ce qui évite les interférences entre traducteurs. Que ce soit pour la soumission de rustines ou pour le choix d’un encodage. .IP "\(bu" 2 En interne, tout est basé sur \fBgettext\fR (mais \fBpo4a\fR offre une interface simple qui ne nécessite pas de comprendre comment ça marche en interne pour pouvoir l’utiliser). Ce qui permet de ne pas réinventer la roue, et du fait de leur utilisation importante, nous pouvons supposer qu’ils ont peu ou pas de bogue. .IP "\(bu" 2 Pour l’utilisateur final, rien ne change (à part que les documentations seront probablement mieux maintenues :). La documentation distribuée reste la même. .IP "\(bu" 2 Il n’est pas nécessaire pour les traducteurs d’apprendre une nouvelle syntaxe et leur éditeur de fichier \s-1PO\s0 préféré (qui peut être le mode \s-1PO\s0 d’Emacs, Lokalize ou Gtranslator) sera parfait. .IP "\(bu" 2 gettext permet d’obtenir facilement des statistiques sur ce qui a été fait, ce qui doit être revu et mis à jour, et sur ce qu’il reste à faire. Vous trouverez des exemples à ces adresses : .Sp .Vb 2 \& \- https://docs.kde.org/stable5/en/kdesdk/lokalize/project\-view.html \&\- http://www.debian.org/intl/l10n/ .Ve .PP Mais tout n’est pas rose, et cette approche a aussi quelques désavantages que nous devons gérer. .IP "\(bu" 2 Les addenda sont… surprenants au premier abord. .IP "\(bu" 2 Il n’est pas possible d’adapter le texte traduit à votre goût, comme de décomposer ou recomposer des paragraphes. Mais d’un autre côté, s’il s’agit d’un problème dans le document original, celui-ci doit être signalé de toute façon. .IP "\(bu" 2 Même s’il a une interface simple, il reste un nouvel outil qu’il faudra apprendre à maîtriser. .Sp Un de mes rêves serait d’intégrer po4a à Gtranslator ou Lokalize. Lorsqu’un fichier de documentation serait ouvert, ses chaînes seraient extraites automatiquement. Lors de l’enregistrement, le fichier traduit + un fichier po seraient écrits sur le disque. Si nous arrivons à faire un module pour \s-1MS\s0 Word (\s-1TM\s0) (ou au moins pour le format \s-1RTF\s0), des traducteurs professionnels pourraient même l’utiliser. .SH "VOIR AUSSI" .IX Header "VOIR AUSSI" .IP "\(bu" 4 La documentation de l'outil tout-en-un que vous devriez utiliser : \fBpo4a\fR\|(1). .IP "\(bu" 4 La documentation des scripts po4a individuels : \fBpo4a\-gettextize\fR\|(1), \fBpo4a\-updatepo\fR\|(1), \fBpo4a\-translate\fR\|(1), \fBpo4a\-normalize\fR\|(1). .IP "\(bu" 4 Les scripts d'assistance supplémentaires : \fBmsguntypot\fR\|(1), \fBpo4a\-display\-man\fR\|(1), \fBpo4a\-display\-pod\fR\|(1). .IP "\(bu" 4 Les parsers de chaque format, en particulier pour consulter les options acceptées par chacun d'entre eux : \fBLocale::Po4a::AsciiDoc\fR\|(3pm) \fBLocale::Po4a::Dia\fR\|(3pm), \fBLocale::Po4a::Guide\fR\|(3pm), \fBLocale::Po4a::Ini\fR\|(3pm), \fBLocale::Po4a::KernelHelp\fR\|(3pm), \fBLocale::Po4a::Man\fR\|(3pm), \fBLocale::Po4a::RubyDoc\fR\|(3pm), \fBLocale::Po4a::Texinfo\fR\|(3pm), \fBLocale::Po4a::Text\fR\|(3pm), \fBLocale::Po4a::Xhtml\fR\|(3pm), \fBLocale::Po4a::Yaml\fR\|(3pm), \fBLocale::Po4a::BibTeX\fR\|(3pm), \fBLocale::Po4a::Docbook\fR\|(3pm), \fBLocale::Po4a::Halibut\fR\|(3pm), \fBLocale::Po4a::LaTeX\fR\|(3pm), \fBLocale::Po4a::Pod\fR\|(3pm), \fBLocale::Po4a::Sgml\fR\|(3pm), \fBLocale::Po4a::TeX\fR\|(3pm), \fBLocale::Po4a::Wml\fR\|(3pm), \fBLocale::Po4a::Xml\fR\|(3pm). .IP "\(bu" 4 La mise en œuvre de l'infrastructure de base : \fBLocale::Po4a::TransTractor\fR\|(3pm) (particulièrement important pour comprendre l'organisation du code), \fBLocale::Po4a::Chooser\fR\|(3pm), \fBLocale::Po4a::Po\fR\|(3pm), \fBLocale::Po4a::Common\fR\|(3pm). Veuillez également consulter le fichier \fI\s-1CONTRIBUTING\s0.md\fR dans l'arborescence des sources. .SH "AUTEURS" .IX Header "AUTEURS" .Vb 2 \& Denis Barbier \& Martin Quinson (mquinson#debian.org) .Ve .SH "TRADUCTION" .IX Header "TRADUCTION" .Vb 1 \& Martin Quinson (mquinson#debian.org) .Ve