.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) .\" .\" 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 .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . 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 .\" .\" Required to disable full justification in groff 1.23.0. .if n .ds AD l .\" ======================================================================== .\" .IX Title "PO4A.7 1" .TH PO4A.7 1 2025-11-22 "perl v5.42.0" "User Contributed Perl Documentation" .\" 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 (PO pour tout – PO for anything) facilite la maintenance de la traduction de la documentation en utilisant les outils classiques de gettext. La principale caractéristique de po4a est qu\*(Aqil dissocie la traduction du contenu et la structure du document. .PP Ce document sert d\*(Aqintroduction au projet po4a en mettant l\*(Aqaccent sur personnes qui envisagent éventuellement d\*(Aqutiliser cet outil et qui sont simplement curieuses et souhaitent comprendre pourquoi les choses sont comme elles sont. .SH "Pourquoi po4a ?" .IX Header "Pourquoi po4a ?" La philosophie des logiciels libres est de rendre la technologie réellement disponible à tout le monde. Cependant, la licence n’est pas la seule préoccupation car un logiciel libre non traduit est inutilisable par des publics non anglophones. En conséquence, nous avons encore du travail pour rendre les logiciels globalement disponibles. .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 libres sont réellement très bien traduits grâce à la suite d’outils gettext. Ces outils sont utilisés pour extraire les chaines traduisibles d’un programme et pour présenter ces dans un format standardisé (appelés fichiers PO, ou catalogue de traduction). Tout un écosystème d’outils a émergé pour aider les équipes de traduction à traduire ces fichiers PO. Le résultat est alors utilisé par gettext à l\*(Aqexécution du logiciel pour afficher les messages traduits dans l’interface d’utilisation. .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\*(Aqun 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 équipes de traduction. 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 qu’une absence de traduction. Une documentation qui décrit un comportement désormais obsolète du programme sera trompeuse. De plus, la prise de contact avec les responsables du logiciels est impossible à cause de la barrière de la langue. De plus, les responsables ne peuvent pas forcément résoudre les problèmes sans une connaissance de toutes les langues dans lesquelles la documentation est traduite. Ces difficultés, souvent causées par un mauvais outillage, peuvent miner la motivation des équipes de traduction, aggravant encore les problèmes. .PP \&\fBLe but du projet po4a est de faciliter le travail de traduction de la documentation\fR. En particulier, il facilite la \fImaintenance\fR des traductions de documentation. .PP L\*(Aqidée est de réutiliser et d\*(Aqadapter l\*(Aqapproche gettext à ce domaine. Comme pour gettext, les textes sont extraits de leur emplacement d\*(Aqorigine et présentés aux équipes de traduction sous forme de catalogues de traduction PO. Les équipes de traduction peuvent utiliser les outils classiques de gettext pour suivre le travail à faire, collaborer et s\*(Aqorganiser. po4a injecte ensuite les traductions directement dans la structure de la documentation pour produire des fichiers traduits qui peuvent être traités et distribués comme les fichiers anglais. Tout paragraphe qui n\*(Aqest pas traduit est laissé en anglais dans le document résultant, garantissant que des traductions obsolètes ne voient jamais le jour. .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\*(Aqerreurs de formatage qui entraineraient un document altéré. .PP Veuillez également consulter la \fBFAQ\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 BSD (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\*(Aqaide de po4a. .Sp Voir Locale::Po4a::AsciiDoc pour en savoir plus. .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 des équipes de traduction jusqu\*(Aqà ce que vous utilisiez po4a. .Sp Voir Locale::Po4a::Pod pour en savoir plus. .IP "sgml (analyseur stable)" 4 .IX Item "sgml (analyseur stable)" Même s’il est de plus en plus remplacé par le XML, 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 DTD\ DebianDoc et DocBook sont prises en charge, mais l’ajout d’une nouvelle DTD est très facile. Il est même possible d’utiliser po4a avec une DTD\ SGML inconnue sans modifier le code en fournissant les informations nécessaires sur la ligne de commande. Consultez \&\fBLocale::Po4a::Sgml\fR\|(3pm) pour en savoir plus. .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 YAML, debian/changelog et debian/control. .Sp Ceci prend en charge le format commun utilisé dans les générateurs de sites statiques, les README et d\*(Aqautres systèmes de documentation. Voir \&\fBLocale::Po4a::Text\fR\|(3pm) pour en savoir plus. .IP "xml and XHMTL (analyseur probablement stable)" 4 .IX Item "xml and XHMTL (analyseur probablement stable)" Le format XML est à la base de beaucoup de formats pour la documentation. .Sp À ce jour, la DTD\ DocBook et XHTML sont pris en charge par po4a. Consultez \&\fBLocale::Po4a::Docbook\fR\|(3pm) pour en savoir plus. .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 en savoir plus. .IP "DocBook (analyseur probablement stable)" 4 .IX Item "DocBook (analyseur probablement stable)" Un langage de balisage basé sur XML qui utilise des balises sémantiques pour décrire des documents. .Sp Voir Locale::Po4a:Docbook pour en savoir plus. .IP "Guide XML (analyseur probablement stable)" 4 .IX Item "Guide XML (analyseur probablement stable)" Un format de documentation XML. Ce module a été développé spécifiquement pour aider à prendre en charge et à maintenir les traductions de la documentation de Gentoo Linux jusqu\*(Aqà au moins mars 2016 (basé sur la Wayback Machine). Gentoo est depuis passé au format DevBook XML. .Sp Voir Locale::Po4a:Guide pour en savoir plus. .IP "Wml (analyseur probablement stable)" 4 .IX Item "Wml (analyseur probablement stable)" Le Web Markup Language, ne pas confondre le WML avec le WAP utilisé sur les téléphones portables. Ce module s\*(Aqappuie sur le module Xhtml, qui lui\-même s\*(Aqappuie sur le module XmL. .Sp Voir Locale::Po4a::Wml pour en savoir plus. .IP "Yaml (analyseur probablement stable)" 4 .IX Item "Yaml (analyseur probablement stable)" Un surensemble strict de JSON. YAML est souvent utilisé comme systèmes ou projets de configuration. YAML est au cœur d’Ansible de Red Hat. .Sp Voir Locale::Po4a::Yaml pour en savoir plus. .IP "RubyDoc (analyseur probablement stable)" 4 .IX Item "RubyDoc (analyseur probablement stable)" Le format Ruby Document (RD), à l\*(Aqorigine le format de documentation par défaut pour Ruby et les projets Ruby avant d\*(Aqêtre la conversion à RDoc en 2002. Bien qu\*(Aqapparemment la version japonaise du Manuel de Référence Ruby utilise toujours le RD. .Sp Voir Locale::Po4a::RubyDoc pour en savoir plus. .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 en savoir plus. .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 en savoir plus. .IP "texinfo (analyseur très expérimental)" 4 .IX Item "texinfo (analyseur très expérimental)" Toutes les documentations du projet GNU sont écrites dans ce format (c’est même une des exigences pour devenir un projet officiel du projet GNU). La prise en charge pour \fBLocale::Po4a::Texinfo\fR\|(3pm) dans po4a en est encore à ses débuts. N’hésitez pas à nous envoyer des rapports de bogue ou des demandes de nouvelle fonctionnalité. .IP "gemtext (analyseur très expérimental)" 4 .IX Item "gemtext (analyseur très expérimental)" The native plain text format of the Gemini protocol. The extension \f(CW\*(C`.gmi\*(C'\fR is commonly used. Support for this module in po4a is still in its infancy. If you find anything, please file a bug or feature request. .IP "org (very highly experimental parser)" 4 .IX Item "org (very highly experimental parser)" The document format used by the Org mode. Support for this module in po4a is still in its infancy. If you find anything, please file a bug or feature request. .IP "vimhelp (very highly experimental parser)" 4 .IX Item "vimhelp (very highly experimental parser)" The format used for Vim help files (and some third\-party plugin documentation). Support for this format in po4a is still in its infancy. If you find anything, please file a bug report or feature request. .IP "simplepod (very highly experimental parser)" 4 .IX Item "simplepod (very highly experimental parser)" Similar to the previously mentioned \fIpod\fR, this one adopts the new Pod::Simple as its parser. Since it is newly created, some bugs are expected. If you notice any strange behavior, please let us know. Eventually, this module will replace \fIpod\fR. .IP "Autres formats supportés" 4 .IX Item "Autres formats supportés" Po4a can also handle some more rare or specialized formats, such as the documentation of compilation options for the 2.4+ Linux kernels (Locale::Po4a::KernelHelp) or the diagrams produced by the dia tool (Locale::Po4a::Dia). Adding a new format is often very easy and the main task is to come up with a parser for your target format. See \&\fBLocale::Po4a::TransTractor\fR\|(3pm) for more information about this. .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 simples à 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" La manière la plus simple d\*(Aqutiliser cet outil dans votre projet est d\*(Aqécrire un fichier de configuration pour le programme \fBpo4a\fR, et de n\*(Aqinteragir qu\*(Aqavec ce programme. Référez\-vous à sa documentation, dans \&\fBpo4a\fR\|(1). Le reste de cette section fournit plus de détails pour une utilisation avancée et une compréhension approfondie de po4a. .SS "Schéma détaillé du flux de travail de po4a" .IX Subsection "Schéma détaillé du flux de travail de po4a" Assurez\-vous d\*(Aqavoir lu \fBpo4a\fR\|(1) avant d\*(Aqaborder cette section trop détaillée afin d\*(Aqobtenir une vue d\*(Aqensemble simplifiée du flux de travail de po4a. Revenez ici pour obtenir l\*(Aqimage complète et effrayante, avec presque tous les détails. .PP In the following schema, \fImaster.doc\fR is an example name for the documentation to be translated; \fIXX.doc\fR is the same document translated in the language XX while \fIdoc.XX.po\fR is the translation catalog for that document in the XX language. Documentation authors will mostly be concerned with \fImaster.doc\fR (which can be a manpage, an XML document, an AsciiDoc file, etc); the translators will be mostly concerned with the PO file, while the end users will only see the \fIXX.doc\fR file. .PP Les transitions entre crochets telles que \f(CW\*(C`[po4a met à jour le po]\*(C'\fR représentent l\*(Aqexécution d\*(Aqun outil po4a, tandis que les transitions entre accolades telles que \f(CW\*(C`{mise à jour de chapi.doc}\*(C'\fR représentent une modification manuelle des fichiers du projet. .PP .Vb 10 \& master.doc \& | \& V \& +<\-\-\-\-\-<\-\-\-\-+<\-\-\-\-\-<\-\-\-\-\-<\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\->\-\-\-\-\-\-\-\->\-\-\-\-\-\-\-+ \& : | | : \&{translation} | {update of master.doc} : \& : | | : \& XX.doc | V V \& (optional) | master.doc \->\-\-\-\-\-\-\-\->\-\-\-\-\-\->+ \& : | (new) | \& V V | | \& [po4a\-gettextize] doc.XX.po \-\->+ | | \& | (old) | | | \& | ^ V V | \& | | [po4a updates po] | \& V | | V \& translation.pot ^ V | \& | | doc.XX.po | \& | | (fuzzy) | \& {translation} | | | \& | ^ V V \& | | {manual editing} | \& | | | | \& V | V V \& doc.XX.po \-\-\->\-\-\-\->+<\-\-\-<\-\- doc.XX.po addendum master.doc \& (initial) (up\-to\-date) (optional) (up\-to\-date) \& : | | | \& : V | | \& +\-\-\-\-\->\-\-\-\-\->\-\-\-\-\->\-\-\-\-\-\-> + | | \& | | | \& V V V \& +\-\-\-\-\-\->\-\-\-\-\-+\-\-\-\-\-\-<\-\-\-\-\-\-+ \& | \& V \& [po4a updates translations] \& | \& V \& XX.doc \& (up\-to\-date) .Ve .PP Là encore, ce schéma est particulièrement compliqué. Consultez \fBpo4a\fR\|(1) pour un aperçu simplifié. .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 PO correspondant. Une telle conversion manuelle est assez lourde (voir la documentation \fBpo4a\-gettextize\fR\|(1) pour en savoir plus), mais elle n\*(Aqest nécessaire qu\*(Aqune seule fois pour convertir vos traductions existantes. Si vous n\*(Aqavez 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 relève de l’auteur du document d’origine, la mise à jour de la documentation. Au milieu à droite sont décrites les mises à jour automatisées des fichiers à traduire : les nouvelles chaines 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 «\ fuzzy\ » indiquant que la traduction doit être mise à jour. Un contenu nouveau ou fortement modifié est laissé non traduit. .PP Ensuite, le bloc \fImodifications manuelles\fR décrit l\*(Aqaction des équipes de traduction qui modifient les fichiers PO pour fournir des traductions à chaque chaine et paragraphe d\*(Aqorigine. Cela peut être fait en utilisant un éditeur spécifique tel que \fBGNOME Translation Editor\fR, \fBLokalize\fR de KDE 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 PO, un par langue. Référez\-vous à la documentation de gettext pour en savoir plus. .PP La partie inférieure de la figure montre comment \fBpo4a\fR crée un document source traduit à partir du document original \fIchapi.doc\fR et du catalogue de traduction \fIdoc.XX.po\fR mis à jour par les équipes de traduction. 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 des membres des équipes de traduction au document final. Voir ci\-dessous pour en savoir plus. .PP L\*(Aqappel à \fBpo4a\fR met à jour automatiquement aussi bien les fichiers à traduire que les fichiers traduits. .SS "Commencer un nouveau projet de traduction" .IX Subsection "Commencer un nouveau projet de traduction" Si vous partez de zéro, il vous suffit d\*(Aqécrire un fichier de configuration pour po4a pour commencer. Des modèles appropriés sont créés pour les fichiers manquants, ce qui permet à vos contributeurs de traduire votre projet dans leur langue. Consultez \fBpo4a\fR\|(1) pour un tutoriel de démarrage rapide et pour tous les détails. .PP Si vous disposez d\*(Aqune traduction existante, c\*(Aqest\-à\-dire d\*(Aqun fichier de documentation qui a été traduit manuellement, vous pouvez intégrer son contenu dans votre flux de travail po4a en utilisant \&\fBpo4a\-gettextize\fR. Cette tâche est un peu lourde (comme décrit dans la page de man de l\*(Aqoutil), mais une fois que votre projet est mis en adaptation au flux de travail po4a, tout sera mis à jour automatiquement. .SS "Mettre à jour les traductions et les documents" .IX Subsection "Mettre à jour les traductions et les documents" Une fois configuré, il suffit d\*(Aqinvoquer \fBpo4a\fR pour mettre à jour à la fois les fichiers PO de traduction et les documents traduits. Vous pouvez passer l\*(Aqargument \f(CW\*(C`\-\-no\-translations\*(C'\fR à \fBpo4a\fR pour ne pas mettre à jour les traductions (et donc juste mettre à jour les fichiers PO) ou l\*(Aqargument \&\f(CW\*(C`\-\-no\-update\*(C'\fR pour ne pas mettre à jour les fichiers PO (et donc juste mettre à jour les traductions). Cela correspond à peu près aux scripts individuels \fBpo4a\-updatepo\fR et \fBpo4a\-translate\fR qui sont maintenant obsolètes (voir «Pourquoi les scripts individuels sont\-ils obsolètes» dans la FAQ ci\-dessous). .SS "Utiliser les addendas pour ajouter du texte supplémentaire aux traductions" .IX Subsection "Utiliser les addendas 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\*(Aqorigine. Le cas d\*(Aqusage classique consiste à mentionner l\*(Aqé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\*(Aqen\-tête\fR, définissant le point d\*(Aqinsertion de l\*(Aqaddendum (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\*(Aqentête doit commencer par la chaine \fBPO4A\-HEADER:\fR, suivie d\*(Aqune liste de champs \fIclé\fR\fB=\fR\fIvaleur\fR séparés par des points\-virgules. .PP Par exemple, l\*(Aqentê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\*(Aqentête suivant déclare un addendum qui doit être placé après la section XML contenant la chaine \f(CW\*(C`À propos de ce document\*(C'\fR en traduction. .PP .Vb 1 \& PO4A\-HEADER: position=About this document; mode=after; endboundary= .Ve .PP En pratique, en essayant d\*(Aqappliquer un addendum, po4a recherche la première ligne correspondant à l\*(Aqargument \f(CW\*(C`position\*(C'\fR (cela peut être une expression régulière regexp). N\*(Aqoubliez 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\*(Aqapplique à 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\*(Aqaddendum est ajouté juste \fBaprès\fR cette ligne (car nous avons fourni un \fIendboundary\fR, c\*(Aqest\-à\-dire une limite terminant la section courante). .PP Le même effet pourrait être obtenu avec l\*(Aqentête suivant, qui est équivalent : .PP .Vb 1 \& PO4A\-HEADER: position=About this document; mode=after; beginboundary=
.Ve .PP Ici, po4a recherche la première ligne correspondant à \f(CW\*(C`
\*(C'\fR après la ligne correspondant à \f(CW\*(C`À propos de ce document\*(C'\fR dans la traduction, et ajoute l\*(Aqaddendum \fBavant\fR cette ligne puisque nous avons fourni un \&\fIbeginboundary\fR, c\*(Aqest\-à\-dire une limite marquant le début de la section suivante. Donc, cette ligne d\*(Aqentête impose de placer l\*(Aqaddendum après la section contenant \f(CW\*(C`À propos de ce document\*(C'\fR, et d\*(Aqinformer po4a qu\*(Aqune section commence par une ligne contenant la balise \f(CW\*(C`
\*(C'\fR. C\*(Aqest équivalent à l\*(Aqexemple précédent, car ce que vous voulez vraiment, c\*(Aqest ajouter cet addendum soit après \f(CW\*(C`
\*(C'\fR soit avant \f(CW\*(C` \& PO4A\-HEADER: position=About this 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\*(Aqétendant sur un paragraphe et contenant plusieurs lignes, ou bien peut être un marqueur XML isolé. Le \fIpoint d\*(Aqinsertion\fR exact de l\*(Aqaddendum doit donc être placé avant ou après cette chaîne de caractères des données internes et ne peut pas être à l\*(Aqintérieur de celle\-ci. .IP \(bu 4 Passez l\*(Aqargument \f(CW\*(C`\-vv\*(C'\fR à \fBpo4a\fR pour comprendre comment les addendas sont ajoutés à la traduction. Il peut également être utile d\*(Aqexécuter \fBpo4a\fR en mode débogage pour voir la chaîne de données interne réelle lorsque votre addendum ne s\*(Aqapplique pas. .PP \fIExemples d\*(Aqaddenda\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 "AUTHORS" .Ve .Sp Vous devez sélectionner une approche en deux étapes en définissant \&\fBmode=after\fR. D\*(Aqabord, vous devez restreindre la recherche à la ligne après \&\fBAUTHORS\fR avec l\*(Aqargument de \fBposition\fR. Ensuite, vous devez faire correspondre le début de la section suivante (c\*(Aqest\-à\-dire, \fB^\e.SH\fR) avec l\*(Aqargument de \fBbeginboundary\fR. C\*(Aqest\-à\-dire : .Sp .Vb 1 \& PO4A\-HEADER:mode=after;position=AUTHORS;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 Big Dude, 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"EOF"\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=About this document;beginboundary=FakePo4aBoundary .Ve .PP \fIExemple plus détaillé\fR .IX Subsection "Exemple plus détaillé" .PP Document original (au format POD : .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 nom des membres des équipes de traduction. .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 AUTHOR 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 \f(CW\*(C`/^=head1/\*(C'\fR après la section «\ NOM\ » (correspondant à la section «\ NAME\ » 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 NOM et AUTEUR, 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. .SS "TransTractors et l\*(Aqarchitecture du projet" .IX Subsection "TransTractors et l'architecture du projet" Au cœur du projet po4a se trouve la classe \&\fBLocale::Po4a::TransTractor\fR\|(3pm) qui est l’ancêtre commun à tous les analyseurs de po4a. Ce nom étrange provient du fait qu\*(Aqelle est à la fois chargée de la traduction et de l’extraction des chaînes du document. .PP Plus formellement, il prend un document à traduire et un fichier PO contenant les traductions en entrée et produit en sortie deux autres fichiers : un autre fichier PO (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 PO fournit en entrée). Voici une représentation graphique de tout ceci : .PP .Vb 6 \& Input document \-\-\e /\-\-\-> Output document \& \e TransTractor:: / (translated) \& +\-\->\-\- parse() \-\-\-\-\-\-\-\-+ \& / \e \& Input PO \-\-\-\-\-\-\-\-/ \e\-\-\-> Output PO \& (extracted) .Ve .PP Cette forme d’os est le cœur de l’architecture de po4a. Si vous fournissez l\*(Aqentrée mais ignorez la sortie PO, vous obtenez \fBpo4a\-translate\fR. Si vous ignorez la sortie document à la place, vous obtenez \fBpo4a\-updatepo\fR. utilise un premier TransTractor pour obtenir un fichier de sortie POT mis à jour (en ignorant les documents en sortie), appelle \fBmsgmerge \-U\fR pour mettre à jour les fichiers PO de traduction sur le disque et crée un second TransTractor à l\*(Aqaide de ces fichiers PO mis à jour pour mettre à jour les documents de sortie. En d\*(Aqautres termes, \fBpo4a\fR vous offre une solution unique pour mettre à jour ce qui doit l\*(Aqêtre, à l\*(Aqaide d\*(Aqun seul fichier de configuration. .PP \&\fBpo4a\-gettextize\fR utilise également deux TransTractors, mais d\*(Aqune autre manière : il construit un TransTractor par langue, puis construit un nouveau fichier PO en utilisant les msgids du document originel en tant que msgids, et les msgids du document traduit en tant que msgstrs. Il faut faire très attention à ce que les chaînes qui sont ainsi mises en correspondance correspondent réellement, comme indiqué dans \fBpo4a\-gettextize\fR\|(1). .SS "Analyseurs spécifiques aux formats" .IX Subsection "Analyseurs spécifiques aux formats" Tous les analyseurs de format sont implémentés au\-dessus de TransTractor. Certains sont très simples, comme les analyseurs Text, Markdown et AsciiDoc. Ils chargent les lignes une par une en utilisant \&\f(CWTransTractor::shiftline()\fR et accumulent le contenu des paragraphes ou autre. Une fois qu\*(Aqune chaîne est complètement analysée, l\*(Aqanalyseur utilise \&\f(CWTransTractor::translate()\fR pour (1) ajouter cette chaîne au fichier PO de sortie et (2) obtenir la traduction du fichier PO d\*(Aqentrée. L\*(Aqanalyseur pousse ensuite le résultat vers le fichier de sortie à l\*(Aqaide de \&\f(CWTransTractor::pushline()\fR. .PP D\*(Aqautres analyseurs sont plus complexes, car ils s\*(Aqappuient sur un analyseur externe pour analyser le document d\*(Aqentrée. Les analyseurs Xml, HTML, SGML et Pod sont construits sur les analyseurs SAX. Ils déclarent des rappels à des événements tels que "J\*(Aqai trouvé un nouveau titre dont le contenu est ceci" pour mettre à jour le document de sortie et les fichiers POT de sortie en fonction du contenu d\*(Aqentrée en utilisant \f(CWTransTractor::translate()\fR et \&\f(CWTransTractor::pushline()\fR. L\*(Aqanalyseur Yaml est similaire, mais différent : il sérialise une structure de données produite par l\*(Aqanalyseur YAML::Tiny. C\*(Aqest pourquoi le module Yaml de po4a ne parvient pas à déclarer les lignes de référence : l\*(Aqemplacement de chaque chaîne dans le fichier d\*(Aqentrée n\*(Aqest pas conservé par l\*(Aqanalyseur, de sorte que nous ne pouvons fournir que "$filename:1" comme emplacement de la chaîne. Les analyseurs orientés SAX utilisent des globaux et d\*(Aqautres astuces pour enregistrer le nom de fichier et les numéros de ligne des références. .PP Un problème spécifique est lié à l\*(Aqencodage des fichiers et aux marqueurs BOM. Les analyseurs simples peuvent ignorer ce point qui est géré par \&\f(CWTransTractor::read()\fR (utilisé en interne pour obtenir les lignes d\*(Aqun document d\*(Aqentrée), mais les modules qui s\*(Aqappuient sur un analyseur externe doivent s\*(Aqassurer que tous les fichiers sont lus avec une couche de décodage PerlIO appropriée. Le plus simple est d\*(Aqouvrir le fichier vous\-même, et de fournir un identificateur de fichier ou directement la chaine complète à votre analyseur externe. Consultez \f(CWPod::read()\fR et \f(CWPod::parse()\fR pour un exemple. Le contenu lu par le TransTractor est ignoré, mais un nouvel identificateur de fichier est transmis à l\*(Aqanalyseur externe. La partie importante est le mode \f(CW\*(C`<"<:encoding($charset)"\*(C'\fR> qui est transmis à la fonction perl \fBopen()\fR. .SS "Objets Po" .IX Subsection "Objets Po" La classe \fBLocale::Po4a::Po\fR\|(3pm) a la tâche de charger et d\*(Aqutiliser les fichiers PO et POT. En principe, vous pouvez lire un fichier, ajouter des entrées, obtenir des traductions avec la méthode \fBgettext()\fR, puis écrire le PO dans un fichier. Les fonctions plus avancées telles que la fusion d\*(Aqun fichier PO avec un fichier POT ou la validation d\*(Aqun fichier sont respectivement déléguées à \fBmsgmerge\fR et \fBmsgfmt\fR. .SS "Contribuer à po4a" .IX Subsection "Contribuer à po4a" Même si vous n\*(Aqavez jamais contribué à un projet libre, bienvenue ! Nous sommes prêts à vous aider et à vous encadrer. po4a est aujourd\*(Aqhui mieux maintenu par sa communauté. Comme nous manquons d\*(Aqaide, nous essayons de rendre le projet accueillant en améliorant la documentation et les tests automatiques afin de vous rendre la contribution au projet plus facile. Consultez le fichier CONTRIBUTING.md pour en savoir plus. .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 (HTML) : un planétarium open source gratuit pour votre ordinateur. po4a est utilisé pour traduire les descriptions des objets célestes. .IP \(bu 4 Jamulus (markdown, yaml, HTML) : une application FOSS pour le brouillage en ligne en temps réel. La documentation du site web est maintenue en plusieurs langues à l\*(Aqaide de po4a. .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\*(Aqanglais yuck :) J\*(Aqai peut\-être un étrange sens de l\*(Aqhumour :) .SS "Pourquoi les scripts individuels sont\-ils obsolètes ?" .IX Subsection "Pourquoi les scripts individuels sont-ils obsolètes ?" Indeed, \fBpo4a\-updatepo\fR and \fBpo4a\-translate\fR are deprecated in favor of \&\fBpo4a\fR. The reason is that while \fBpo4a\fR can be used as a drop\-in replacement to these scripts, there is quite a lot of code duplication here. Individual scripts last around 150 lines of codes while the \fBpo4a\fR program lasts 1200 lines, so they do a lot in addition of the common internals. The code duplication results in bugs occurring in both versions and needing two fixes. One example of such duplication are the bugs #1022216 in Debian and the issue #442 in GitHub that had the exact same fix, but one in \fBpo4a\fR and the other \fBpo4a\-updatepo\fR. .PP À long terme, j\*(Aqaimerais abandonner les scripts individuels et ne maintenir qu\*(Aqune seule version de ce code. Ce qui est sûr, c\*(Aqest que les scripts individuels ne seront plus améliorés, et que seul \fBpo4a\fR bénéficiera de nouvelles fonctionnalités. Ceci étant dit, la dépréciation n\*(Aqest pas immédiate. Je prévois de conserver les scripts individuels aussi longtemps que possible, et au moins jusqu\*(Aqen 2030. Cependant, si votre projet utilise encore \fBpo4a\-updatepo\fR et \fBpo4a\-translate\fR à cette date, vous pourriez avoir un problème. .PP Nous pourrions également annuler la dépréciation de ces scripts à un moment donné, si une réécriture élimine la duplication du code. Si vous avez des idées (ou mieux : un correctif), votre aide est la bienvenue. .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 KDE pour gérer les XML\ DocBook. C’est à notre connaissance le premier programme qui a extrait des chaînes à traduire d’une documentation pour les mettre dans un fichier PO, et les réinjecter ensuite dans le document après la traduction. .Sp Il ne peut gérer que le format XML, avec une DTD 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 SGML de po4a, qui le remplace plus ou moins. Comme son nom l’indique, il ne gère que la DTD DebianDoc, qui est en voie d’extinction. .IP \fBxml2po.py\fR 4 .IX Item "xml2po.py" Utilisé par l\*(Aqéquipe de documentation de GIMP depuis 2004, il fonctionne assez bien même si, comme son nom l\*(Aqindique, il ne fonctionne qu\*(Aqavec des fichiers XML 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\*(Aqil soit peut\-être le seul outil à faire cela en gérant l\*(Aqensemble 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 gettextisation. .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 équipes de traduction. 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 tout 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’utilisation finale, 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 membres des équipes de traduction d’apprendre une nouvelle syntaxe et leur éditeur de fichier PO préféré (qui peut être le mode PO 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 addendas 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 arrivions à faire un module pour MS\ Word (TM) (ou au moins pour le format RTF), po4a pourrait même être utilisés dans le milieu de la traduction professionnelle. .SH "VOIR AUSSI" .IX Header "VOIR AUSSI" .IP \(bu 4 La documentation de l\*(Aqoutil 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\*(Aqassistance supplémentaires : \fBmsguntypot\fR\|(1), \&\fBpo4a\-display\-man\fR\|(1), \fBpo4a\-display\-pod\fR\|(1). .IP \(bu 4 The parsers of each formats, in particular to see the options accepted by each of them: \fBLocale::Po4a::AsciiDoc\fR\|(3pm) \fBLocale::Po4a::Dia\fR\|(3pm), \&\fBLocale::Po4a::Gemtext\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::Org\fR\|(3pm), \fBLocale::Po4a::Pod\fR\|(3pm), \&\fBLocale::Po4a::SimplePod\fR\|(3pm), \fBLocale::Po4a::Sgml\fR\|(3pm), \&\fBLocale::Po4a::TeX\fR\|(3pm), Locale::Po4a::VimHelp, \&\fBLocale::Po4a::Wml\fR\|(3pm), \fBLocale::Po4a::Xml\fR\|(3pm). .IP \(bu 4 La mise en œuvre de l\*(Aqinfrastructure de base : \&\fBLocale::Po4a::TransTractor\fR\|(3pm) (particulièrement important pour comprendre l\*(Aqorganisation du code), \fBLocale::Po4a::Chooser\fR\|(3pm), \&\fBLocale::Po4a::Po\fR\|(3pm), \fBLocale::Po4a::Common\fR\|(3pm). Consultez également le fichier \fICONTRIBUTING.md\fR dans l\*(Aqarborescence 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