PO4A.7(1) User Contributed Perl Documentation PO4A.7(1) NOM po4a - Cadre de travail pour la traduction de documentations et autres documents 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 caracteristique de po4a est qu'il dissocie la traduction du contenu et la structure du document. Ce document sert d'introduction au projet po4a en mettant l'accent sur personnes qui envisagent eventuellement d'utiliser cet outil et qui sont simplement curieuses et souhaitent comprendre pourquoi les choses sont comme elles sont. Pourquoi po4a ? La philosophie des logiciels libres est de rendre la technologie reellement disponible a tout le monde. Cependant, la licence n'est pas la seule preoccupation car un logiciel libre non traduit est inutilisable par des publics non anglophones. En consequence, nous avons encore du travail pour rendre les logiciels globalement disponibles. Cette situation est bien comprise par la plupart des projets et tout le monde est desormais convaincu de la necessite de tout traduire. Pourtant, les traductions representent un effort enorme de nombreuses personnes, paralysees par de petites difficultes techniques. Heureusement, les logiciels libres sont reellement tres bien traduits grace a la suite d'outils gettext. Ces outils sont utilises pour extraire les chaines traduisibles d'un programme et pour presenter ces dans un format standardise (appeles fichiers PO, ou catalogue de traduction). Tout un ecosysteme d'outils a emerge pour aider les equipes de traduction a traduire ces fichiers PO. Le resultat est alors utilise par gettext a l'execution du logiciel pour afficher les messages traduits dans l'interface d'utilisation. En ce qui concerne la documentation, cependant, la situation est quelque peu decevante. Au debut, 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 a traduire le contenu. Cependant, lorsque la documentation originale est modifiee, le suivi des modifications se transforme rapidement en cauchemar pour les equipes de traduction. Si elle est effectuee manuellement, cette tache est desagreable et sujette aux erreurs. Les traductions obsoletes sont souvent pires qu'une absence de traduction. Une documentation qui decrit un comportement desormais obsolete du programme sera trompeuse. De plus, la prise de contact avec les responsables du logiciels est impossible a cause de la barriere de la langue. De plus, les responsables ne peuvent pas forcement resoudre les problemes sans une connaissance de toutes les langues dans lesquelles la documentation est traduite. Ces difficultes, souvent causees par un mauvais outillage, peuvent miner la motivation des equipes de traduction, aggravant encore les problemes. Le but du projet po4a est de faciliter le travail de traduction de la documentation. En particulier, il facilite la maintenance des traductions de documentation. L'idee est de reutiliser et d'adapter l'approche gettext a ce domaine. Comme pour gettext, les textes sont extraits de leur emplacement d'origine et presentes aux equipes de traduction sous forme de catalogues de traduction PO. Les equipes de traduction peuvent utiliser les outils classiques de gettext pour suivre le travail a faire, collaborer et s'organiser. po4a injecte ensuite les traductions directement dans la structure de la documentation pour produire des fichiers traduits qui peuvent etre traites et distribues comme les fichiers anglais. Tout paragraphe qui n'est pas traduit est laisse en anglais dans le document resultant, garantissant que des traductions obsoletes ne voient jamais le jour. Ceci automatise la plupart des gros travaux de maintenance de la traduction. La decouverte des paragraphes necessitant une mise a jour devient tres facile et le processus est completement automatise lorsque les elements sont reorganises sans autre modification. Une verification specifique peut egalement etre utilisee pour reduire le risque d'erreurs de formatage qui entraineraient un document altere. Veuillez egalement consulter la FAQ plus bas dans ce document pour une liste plus complete des avantages et inconvenients de cette approche. Formats pris en charge Actuellement, cette approche a ete implementee avec succes pour un certain nombre de formats de mise en page de texte : man (analyseur stable) Le bon vieux format des pages de manuel, utilise par beaucoup de programmes. Le support de po4a pour ce format est tres utile parce que ce format est assez complique, surtout pour les debutants. Le module Locale::Po4a::Man(3pm) prend egalement en charge le format mdoc, utilise par les pages de manuel BSD (ils sont egalement assez courants sous Linux). AsciiDoc (analyseur stable) Ce format est un format de balisage leger destine a faciliter la creation de documentation. Il est par exemple utilise pour documenter le systeme git. Ces pages de manuel sont traduites a l'aide de po4a. Voir Locale::Po4a::AsciiDoc pour en savoir plus. pod (analyseur stable) C'est le format pour la documentation en ligne de Perl (<< Perl Online Documentation> >>). Le langage et ses documentations sont documentes en utilisant ce format en plus de la majorite des scripts Perl existants. Il permet de garder la documentation plus fidele au code en les integrant tous deux au meme fichier. Il rend la vie du programmeur plus simple, mais malheureusement pas celle des equipes de traduction jusqu'a ce que vous utilisiez po4a. Voir Locale::Po4a::Pod pour en savoir plus. sgml (analyseur stable) Meme s'il est de plus en plus remplace par le XML, ce format est encore assez utilise pour les documents dont la taille depasse plusieurs ecrans. Il permet meme de faire des livres complets. Des documents aussi longs peuvent etre vraiment complexes a traduire. diff se montre souvent inutile quand le document original a ete reindente apres une mise a jour. Heureusement, po4a vous aide dans cette tache. Actuellement, seules les DTD DebianDoc et DocBook sont prises en charge, mais l'ajout d'une nouvelle DTD est tres facile. Il est meme possible d'utiliser po4a avec une DTD SGML inconnue sans modifier le code en fournissant les informations necessaires sur la ligne de commande. Consultez Locale::Po4a::Sgml(3pm) pour en savoir plus. TeX / LaTeX (analyseur stable) Le format LaTeX est un format majeur utilise pour les documentations dans le monde du logiciel libre ou pour des publications. Le module Locale::Po4a::LaTeX(3pm) a ete teste avec la documentation de Python, un livre et avec quelques presentations. 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 preliminaires YAML, debian/changelog et debian/control. Ceci prend en charge le format commun utilise dans les generateurs de sites statiques, les README et d'autres systemes de documentation. Voir Locale::Po4a::Text(3pm) pour en savoir plus. xml and XHMTL (analyseur probablement stable) Le format XML est a la base de beaucoup de formats pour la documentation. A ce jour, la DTD DocBook et XHTML sont pris en charge par po4a. Consultez Locale::Po4a::Docbook(3pm) pour en savoir plus. BibTex (analyseur probablement stable) Le format BibTex est utilise conjointement avec LaTeX pour la mise en forme des listes de references (bibliographies). Voir Locale::Po4a::BibTex pour en savoir plus. DocBook (analyseur probablement stable) Un langage de balisage base sur XML qui utilise des balises semantiques pour decrire des documents. Voir Locale::Po4a:Docbook pour en savoir plus. Guide XML (analyseur probablement stable) Un format de documentation XML. Ce module a ete developpe specifiquement pour aider a prendre en charge et a maintenir les traductions de la documentation de Gentoo Linux jusqu'a au moins mars 2016 (base sur la Wayback Machine). Gentoo est depuis passe au format DevBook XML. Voir Locale::Po4a:Guide pour en savoir plus. Wml (analyseur probablement stable) Le Web Markup Language, ne pas confondre le WML avec le WAP utilise sur les telephones portables. Ce module s'appuie sur le module Xhtml, qui lui-meme s'appuie sur le module XmL. Voir Locale::Po4a::Wml pour en savoir plus. Yaml (analyseur probablement stable) Un surensemble strict de JSON. YAML est souvent utilise comme systemes ou projets de configuration. YAML est au coeur d'Ansible de Red Hat. Voir Locale::Po4a::Yaml pour en savoir plus. RubyDoc (analyseur probablement stable) Le format Ruby Document (RD), a l'origine le format de documentation par defaut pour Ruby et les projets Ruby avant d'etre la conversion a RDoc en 2002. Bien qu'apparemment la version japonaise du Manuel de Reference Ruby utilise toujours le RD. Voir Locale::Po4a::RubyDoc pour en savoir plus. Halibut (analyseur tres experimental) Un systeme de production de documentation, avec des elements similaires a TeX, debiandoc-sgml, TeXinfo, et autres, developpe par Simon Tatham, le developpeur de PuTTY. Voir Locale::Po4a:Halibut pour en savoir plus. Ini (analyseur tres experimental) Format de fichier de configuration popularise par MS-DOS. Voir Locale::Po4a::Ini pour en savoir plus. texinfo (analyseur tres experimental) Toutes les documentations du projet GNU sont ecrites dans ce format (c'est meme une des exigences pour devenir un projet officiel du projet GNU). La prise en charge pour Locale::Po4a::Texinfo(3pm) dans po4a en est encore a ses debuts. N'hesitez pas a nous envoyer des rapports de bogue ou des demandes de nouvelle fonctionnalite. gemtext (analyseur tres experimental) Le format texte natif du protocole Gemini. L'extension <<.gmi>> est generalement utilisee. La prise en charge de ce module dans po4a en est encore a ses debuts. Si vous trouvez des problemes, n'hesitez pas a faire un rapport de bogue ou a demander des ameliorations. Autres formats supportes Po4a peut egalement gerer des formats plus rares et plus specifiques, 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 tres simple, et consiste principalement a fournir un interpreteur pour le format voulu. Consulter Locale::Po4a::TransTractor(3pm) pour en savoir plus. Formats non supportes Malheureusement, po4a soufre d'un manque de prise en charge de divers formats de documentation. Beaucoup d'entre eux seraient simples a prendre en charge dans po4a. Cela inclut des formats etant utilises pour plus que de la documentation, tels que les descriptions de paquets (deb et rpm), aux questions posees par les scripts d'installation, en passant par les fichiers changelog, et de tous les formats specifiques tels que les scenarios de jeux ou les fichiers de ressource pour wine. Utiliser po4a La maniere la plus simple d'utiliser cet outil dans votre projet est d'ecrire un fichier de configuration pour le programme po4a, et de n'interagir qu'avec ce programme. Referez-vous a sa documentation, dans po4a(1). Le reste de cette section fournit plus de details pour une utilisation avancee et une comprehension approfondie de po4a. Schema detaille du flux de travail de po4a Assurez-vous d'avoir lu po4a(1) avant d'aborder cette section trop detaillee afin d'obtenir une vue d'ensemble simplifiee du flux de travail de po4a. Revenez ici pour obtenir l'image complete et effrayante, avec presque tous les details. Le schema suivant, chapi.doc est un exemple de nom pour la documentation a traduire; XX.doc est le meme document traduit dans la langue XX tandis que doc.XX.po est le catalogue de traduction de ce document dans la langue XX. Les responsables de la documentation auront principalement la charge de chapi.doc (qui peut etre une page de manuel, un document XML, un fichier AsciiDoc, etc.); les equipes de traduction seront principalement concernees par le fichier PO, tandis que seul le fichier XX.doc sera publie. Les transitions entre crochets telles que "[po4a met a jour le po]" representent l'execution d'un outil po4a, tandis que les transitions entre accolades telles que "{mise a jour de chapi.doc}" representent une modification manuelle des fichiers du projet. chapi.doc | V +<----------+<--------------------+----------------------->+ : | | : {traduction} | { mise a jour de chapi.doc } : : | | : XX.doc | V V (optionnel) | chapi.doc ------------------>+ : | (nouveau) | V V | | [po4a-gettextize] doc.XX.po --->+ | | | (vieux) | | | | ^ V V | | | [po4a met a jour le po] | V | | | traduction.pot | V | | | doc.XX.po | | | (correspondances) | | | | | {traduction} | | | | | V | | | {modifications manuelles} | | | | | V | V V doc.XX.po --------->+<------- doc.XX.po addendum chapi.doc (initial) (a jour) (optionnel) (a jour) : | | | : V | | +-------------------------> + | | | | | V V V +----------->+<------------+ | V [po4a met a jour les traductions] | V XX.doc (a jour) La encore, ce schema est particulierement complique. Consultez po4a(1) pour un apercu simplifie. La partie a gauche montre comment po4a-gettextize(1) peut etre utilise pour convertir un projet de traduction existant en infrastructure po4a. Ce script prend un document original et son equivalent traduit, et essaie de creer le fichier PO correspondant. Une telle conversion manuelle est assez lourde (voir la documentation po4a-gettextize(1) pour en savoir plus), mais elle n'est necessaire qu'une seule fois pour convertir vos traductions existantes. Si vous n'avez aucune traduction a convertir, vous pouvez oublier cela et vous concentrer sur la partie droite du schema. En haut a droite est decrit ce qui releve de l'auteur du document d'origine, la mise a jour de la documentation. Au milieu a droite sont decrites les mises a jour automatisees des fichiers a traduire: les nouvelles chaines sont extraites et comparees avec la traduction existante. La traduction existante est utilisee pour les parties n'ayant pas change, alors que celles qui ont ete en partie modifiees sont egalement associees a leur ancienne traduction, mais avec un marquage << fuzzy >> indiquant que la traduction doit etre mise a jour. Un contenu nouveau ou fortement modifie est laisse non traduit. Ensuite, le bloc modifications manuelles decrit l'action des equipes de traduction qui modifient les fichiers PO pour fournir des traductions a chaque chaine et paragraphe d'origine. Cela peut etre fait en utilisant un editeur specifique tel que GNOME Translation Editor, Lokalize de KDE ou poedit, ou en utilisant une plateforme de localisation en ligne telle que weblate ou pootle. Le resultat de la traduction est un ensemble de fichiers PO, un par langue. Referez-vous a la documentation de gettext pour en savoir plus. La partie inferieure de la figure montre comment po4a cree un document source traduit a partir du document original chapi.doc et du catalogue de traduction doc.XX.po mis a jour par les equipes de traduction. La structure du document est reutilisee, tandis que le contenu original est remplace par son equivalent traduit. En option, un addendum peut etre utilise pour ajouter du texte supplementaire a la traduction. Ceci est souvent utilise pour ajouter le nom des membres des equipes de traduction au document final. Voir ci-dessous pour en savoir plus. L'appel a po4a met a jour automatiquement aussi bien les fichiers a traduire que les fichiers traduits. Commencer un nouveau projet de traduction Si vous partez de zero, il vous suffit d'ecrire un fichier de configuration pour po4a pour commencer. Des modeles appropries sont crees pour les fichiers manquants, ce qui permet a vos contributeurs de traduire votre projet dans leur langue. Consultez po4a(1) pour un tutoriel de demarrage rapide et pour tous les details. Si vous disposez d'une traduction existante, c'est-a-dire d'un fichier de documentation qui a ete traduit manuellement, vous pouvez integrer son contenu dans votre flux de travail po4a en utilisant po4a-gettextize. Cette tache est un peu lourde (comme decrit dans la page de man de l'outil), mais une fois que votre projet est mis en adaptation au flux de travail po4a, tout sera mis a jour automatiquement. Mettre a jour les traductions et les documents Une fois configure, il suffit d'invoquer po4a pour mettre a jour a la fois les fichiers PO de traduction et les documents traduits. Vous pouvez passer l'argument "--no-translations" a po4a pour ne pas mettre a jour les traductions (et donc juste mettre a jour les fichiers PO) ou l'argument "--no-update" pour ne pas mettre a jour les fichiers PO (et donc juste mettre a jour les traductions). Cela correspond a peu pres aux scripts individuels po4a-updatepo et po4a-translate qui sont maintenant obsoletes (voir <> dans la FAQ ci-dessous). Utiliser les addendas pour ajouter du texte supplementaire aux traductions Ajouter un nouveau texte a la traduction est probablement la seule chose qui soit plus facile a long terme lorsque vous traduisez des fichiers manuellement:). Cela se produit lorsque vous souhaitez ajouter une section supplementaire au document traduit, ne correspondant a aucun contenu du document d'origine. Le cas d'usage classique consiste a mentionner l'equipe de traduction et a indiquer comment signaler les problemes specifiques a la traduction. Avec po4a, vous devez specifier les fichiers addendum, qui peuvent etre conceptuellement consideres comme des correctifs appliques au document localise apres traitement. Chaque addendum doit etre fourni dans un fichier separe, dont le format est cependant tres different des correctifs classiques. La premiere ligne est une ligne d'en-tete, definissant le point d'insertion de l'addendum (avec une syntaxe malheureusement obscure - voir ci-dessous) tandis que le reste du fichier est ajoute textuellement a la position determinee. La ligne d'entete doit commencer par la chaine PO4A-HEADER:, suivie d'une liste de champs cle=valeur separes par des points-virgules. Par exemple, l'entete suivant declare un addendum qui doit etre place a la toute fin de la traduction. PO4A-HEADER: mode=eof Les choses sont plus complexes lorsque vous souhaitez ajouter votre contenu supplementaire au milieu du document. L'entete suivant declare un addendum qui doit etre place apres la section XML contenant la chaine "A propos de ce document" en traduction. PO4A-HEADER: position=A propos de ce document; mode=after; endboundary= En pratique, en essayant d'appliquer un addendum, po4a recherche la premiere ligne correspondant a l'argument "position" (cela peut etre une expression reguliere regexp). N'oubliez pas que po4a considere ici le document traduit. Cette documentation est en anglais, mais votre ligne devrait probablement se lire comme suit si vous souhaitez que votre addendum s'applique a la traduction francaise du document. PO4A-HEADER: position=A propos de ce document; mode=after; endboundary= Une fois que la "position" est trouvee dans le document cible, po4a recherche la ligne suivante apres la "position" qui correspond au "endboundary" fourni. L'addendum est ajoute juste apres cette ligne (car nous avons fourni un endboundary, c'est-a-dire une limite terminant la section courante). Le meme effet pourrait etre obtenu avec l'entete suivant, qui est equivalent: PO4A-HEADER: position=A propos de ce document; mode=after; beginboundary=
Ici, po4a recherche la premiere ligne correspondant a "
" apres la ligne correspondant a "A propos de ce document" dans la traduction, et ajoute l'addendum avant cette ligne puisque nous avons fourni un beginboundary, c'est-a-dire une limite marquant le debut de la section suivante. Donc, cette ligne d'entete impose de placer l'addendum apres la section contenant "A propos de ce document", et d'informer po4a qu'une section commence par une ligne contenant la balise "
". C'est equivalent a l'exemple precedent, car ce que vous voulez vraiment, c'est ajouter cet addendum soit apres "
" soit avant ": combiner "mode=before" avec un "endboundary" mettra l'addendum juste apres la limite correspondante, qui est la derniere limite potentielle avant la "position". La combinaison de "mode=before" avec un "beginboundary" placera l'addendum juste avant la limite correspondante, c'est-a-dire la derniere limite potentielle avant la "position". Mode | Type de limite | Limite utilisee | Point d'insertion par rapport a la limite ========|===============|========================|========================================= 'before'| 'endboundary' | derniere avant la 'position' | Juste apres la limite 'before'|'beginboundary'| derniere avant la 'position' | Juste avant la limite 'after' | 'endboundary' | premiere apres la 'position' | Juste apres la limite 'after' |'beginboundary'| premiere apres la 'position' | Juste avant la limite 'eof' | (rien) | sans objet | Fin de fichier Trucs et astuces sur les addendas o Gardez a l'esprit que ce sont des expressions rationnelles. Par exemple, si vous voulez correspondre a la fin d'une section nroff terminant par la ligne ".fi", n'utilisez pas ".fi" comme valeur pour endboundary, parce que cala correspondra egalement a "ce[ fi]chier", ce qui n'est evidemment pas ce que vous voulez. La valeur du champ endboundary dans ce cas est "^\.fi$". o Les espaces SONT importants dans le contenu de la "position" et des limites. Donc les deux lignes suivantes sont differentes. La seconde ne sera trouve que s'il y a suffisamment d'espaces de fin dans le document traduit. PO4A-HEADER: position=A propos de ce document; mode=after; beginboundary=
PO4A-HEADER: position=A propos de ce document; mode=after; beginboundary=
o Bien que cette recherche contextuelle puisse etre consideree comme operant a peu pres sur toutes les lignes du document traduit, elle opere en fait sur la chaine de caracteres des donnees internes a po4a. Cette chaine de caracteres des donnees internes peut etre aussi bien un texte s'etendant sur un paragraphe et contenant plusieurs lignes, ou bien peut etre un marqueur XML isole. Le point d'insertion exact de l'addendum doit donc etre place avant ou apres cette chaine de caracteres des donnees internes et ne peut pas etre a l'interieur de celle-ci. o Passez l'argument "-vv" a po4a pour comprendre comment les addendas sont ajoutes a la traduction. Il peut egalement etre utile d'executer po4a en mode debogage pour voir la chaine de donnees interne reelle lorsque votre addendum ne s'applique pas. Exemples d'addenda o Si vous voulez ajouter quelque chose apres la section nroff suivante : .SH "AUTEURS" Vous devez selectionner une approche en deux etapes en definissant mode=after. D'abord, vous devez restreindre la recherche a la ligne apres AUTHORS avec l'argument de position. Ensuite, vous devez faire correspondre le debut de la section suivante (c'est-a-dire, ^\.SH) avec l'argument de beginboundary. C'est-a-dire: PO4A-HEADER:mode=after;position=AUTEURS;beginboundary=\.SH o Si vous voulez ajouter quelque chose juste apres une ligne donnee (par exemple apres << Copyright Bidule >>), utilisez une position correspondant a cette ligne, un mode=after et renseignez un champ beginboundary correspondant a n'importe quelle ligne. PO4A-HEADER:mode=after;position=Copyright Tralala, 2004;beginboundary=^ o Si vous voulez ajouter quelque chose a la fin du document, donnez une position correspondant a n'importe quelle ligne du document (mais a une seule ligne, puisque po4a n'acceptera pas que la position ne corresponde pas a une ligne unique), et donnez un champ endboundary ne correspondant a aucune ligne. N'utilisez pas de chaine simple, comme "EOF", mais preferez-en une qui a une chance moindre de se trouver dans votre document. PO4A-HEADER:mode=after;position=A propos de ce document;beginboundary=FausseLimitePo4a Exemple plus detaille Document original (au format POD : |=head1 NOM | |beta - un programme un peu beta | |=head1 AUTEUR | |moi Voici maintenant un addendum qui s'assure qu'une section est ajoutee a la fin du fichier pour indiquer le nom des membres des equipes de traduction. |PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head | |=head1 TRADUCTEUR | |encore moi | Pour placer l'addendum avant l'AUTEUR (section nommee AUTHOR dans le document original), utilisez l'en-tete suivant : PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1 Ceci fonctionne parce que la premiere ligne correspondant a l'expression rationnelle donnee dans le champ beginboundary "/^=head1/" apres la section << NOM >> (correspondant a la section << NAME >> dans le document original), est celle indiquant les auteurs. De cette facon, l'addendum est place entre les deux sections. Notez que si une autre section est ajoutee entre NOM et AUTEUR, po4a ajoutera l'addendum par erreur avant la nouvelle section. Pour eviter cela, vous pouvez utiliser mode=before : PO4A-HEADER:mode=before;position=^=head1 AUTEUR Comment ca marche ? Cette section vous donne un bref apercu des rouages internes de po4a afin que vous vous sentiez plus a meme de nous aider a le maintenir et l'ameliorer. Elle peut egalement vous permettre de comprendre pourquoi cela ne fait pas ce que vous souhaitez et corriger vos problemes par vous-meme. TransTractors et l'architecture du projet Au coeur du projet po4a se trouve la classe Locale::Po4a::TransTractor(3pm) qui est l'ancetre commun a tous les analyseurs de po4a. Ce nom etrange provient du fait qu'elle est a la fois chargee de la traduction et de l'extraction des chaines du document. Plus formellement, il prend un document a traduire et un fichier PO contenant les traductions en entree et produit en sortie deux autres fichiers: un autre fichier PO (resultant de l'extraction des chaines a traduire du document d'entree), et un document traduit (avec la meme structure que le document d'entree, mais dont toutes les chaines a traduire ont ete remplacees par leur traduction donnee par le PO fournit en entree). Voici une representation graphique de tout ceci: document en entree --\ /---> document en sortie \ TransTractor:: / (traduit) +-->-- parse() --------+ / \ PO en entree --------/ \---> PO en sortie (extrait) Cette forme d'os est le coeur de l'architecture de po4a. Si vous fournissez l'entree mais ignorez la sortie PO, vous obtenez po4a-translate. Si vous ignorez la sortie document a la place, vous obtenez po4a-updatepo. utilise un premier TransTractor pour obtenir un fichier de sortie POT mis a jour (en ignorant les documents en sortie), appelle msgmerge -U pour mettre a jour les fichiers PO de traduction sur le disque et cree un second TransTractor a l'aide de ces fichiers PO mis a jour pour mettre a jour les documents de sortie. En d'autres termes, po4a vous offre une solution unique pour mettre a jour ce qui doit l'etre, a l'aide d'un seul fichier de configuration. po4a-gettextize utilise egalement deux TransTractors, mais d'une autre maniere: 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 tres attention a ce que les chaines qui sont ainsi mises en correspondance correspondent reellement, comme indique dans po4a-gettextize(1). Analyseurs specifiques aux formats Tous les analyseurs de format sont implementes au-dessus de TransTractor. Certains sont tres simples, comme les analyseurs Text, Markdown et AsciiDoc. Ils chargent les lignes une par une en utilisant TransTractor::shiftline() et accumulent le contenu des paragraphes ou autre. Une fois qu'une chaine est completement analysee, l'analyseur utilise TransTractor::translate() pour (1) ajouter cette chaine au fichier PO de sortie et (2) obtenir la traduction du fichier PO d'entree. L'analyseur pousse ensuite le resultat vers le fichier de sortie a l'aide de TransTractor::pushline(). D'autres analyseurs sont plus complexes, car ils s'appuient sur un analyseur externe pour analyser le document d'entree. Les analyseurs Xml, HTML, SGML et Pod sont construits sur les analyseurs SAX. Ils declarent des rappels a des evenements tels que "J'ai trouve un nouveau titre dont le contenu est ceci" pour mettre a jour le document de sortie et les fichiers POT de sortie en fonction du contenu d'entree en utilisant TransTractor::translate() et TransTractor::pushline(). L'analyseur Yaml est similaire, mais different: il serialise une structure de donnees produite par l'analyseur YAML::Tiny. C'est pourquoi le module Yaml de po4a ne parvient pas a declarer les lignes de reference: l'emplacement de chaque chaine dans le fichier d'entree n'est pas conserve par l'analyseur, de sorte que nous ne pouvons fournir que "$filename:1" comme emplacement de la chaine. Les analyseurs orientes SAX utilisent des globaux et d'autres astuces pour enregistrer le nom de fichier et les numeros de ligne des references. Un probleme specifique est lie a l'encodage des fichiers et aux marqueurs BOM. Les analyseurs simples peuvent ignorer ce point qui est gere par TransTractor::read() (utilise en interne pour obtenir les lignes d'un document d'entree), mais les modules qui s'appuient sur un analyseur externe doivent s'assurer que tous les fichiers sont lus avec une couche de decodage PerlIO appropriee. Le plus simple est d'ouvrir le fichier vous-meme, et de fournir un identificateur de fichier ou directement la chaine complete a votre analyseur externe. Consultez Pod::read() et Pod::parse() pour un exemple. Le contenu lu par le TransTractor est ignore, mais un nouvel identificateur de fichier est transmis a l'analyseur externe. La partie importante est le mode "<"<:encoding($charset)""> qui est transmis a la fonction perl open(). Objets Po La classe Locale::Po4a::Po(3pm) a la tache de charger et d'utiliser les fichiers PO et POT. En principe, vous pouvez lire un fichier, ajouter des entrees, obtenir des traductions avec la methode gettext(), puis ecrire le PO dans un fichier. Les fonctions plus avancees telles que la fusion d'un fichier PO avec un fichier POT ou la validation d'un fichier sont respectivement deleguees a msgmerge et msgfmt. Contribuer a po4a Meme si vous n'avez jamais contribue a un projet libre, bienvenue! Nous sommes prets a vous aider et a vous encadrer. po4a est aujourd'hui mieux maintenu par sa communaute. Comme nous manquons d'aide, nous essayons de rendre le projet accueillant en ameliorant 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. Projets open-source utilisant po4a Voici une liste tres partielle des projets qui utilisent po4a en production pour leur documentation. Si vous souhaitez ajouter votre projet a la liste, envoyez-nous simplement un e-mail (ou une demande de fusion (Merge Request)). o adduser (man) : outil de gestion des utilisateurs et des groupes. o apt (man, docbook) : Gestionnaire de paquets Debian. o aptitude (docbook, svg) : gestionnaire de paquets en mode commande pour Debian o site internet F-Droid (markdown): catalogue de logiciels libres pour la plateforme Android. o git (asciidoc) : systeme de controle de version distribue pour suivre les modifications du code source. o manuel Linux (man) Ce projet fournit une infrastructure pour traduire de nombreuses pages de manuel dans differents langages, prete a etre integree dans plusieurs distributions majeures (Arch Linux, Debian et derives, Fedora). o Stellarium (HTML) : un planetarium open source gratuit pour votre ordinateur. po4a est utilise pour traduire les descriptions des objets celestes. o Jamulus (markdown, yaml, HTML): une application FOSS pour le brouillage en ligne en temps reel. La documentation du site web est maintenue en plusieurs langues a l'aide de po4a. o Autres elements a trier : FAQ Comment prononcer po4a ? Personnellement, je le prononce comme pouah , qui est une interjection francaise equivalente a l'anglais yuck :) J'ai peut-etre un etrange sens de l'humour :) Pourquoi les scripts individuels sont-ils obsoletes? En effet, po4a-updatepo et po4a-translate sont deprecies au profit de po4a. La raison en est que, bien que po4a puisse etre utilise comme un remplacement direct de ces scripts, on y trouve beaucoup de duplication de code. Les scripts individuels font environ 150 lignes de code alors que le programme po4a en fait 1200, ils font donc beaucoup de choses en plus des elements internes communs. La duplication du code entraine l'apparition de bogues dans les deux versions et necessite des corrections doubles. On peut voir une telle duplication dans les bogues #1022216 de Debian et le probleme #442 sur GitHub qui avaient exactement la meme correction, avec une dans po4a et l'autre dans po4a-updatepo. A long terme, j'aimerais abandonner les scripts individuels et ne maintenir qu'une seule version de ce code. Ce qui est sur, c'est que les scripts individuels ne seront plus ameliores, et que seul po4a beneficiera de nouvelles fonctionnalites. Ceci etant dit, la depreciation n'est pas immediate. Je prevois de conserver les scripts individuels aussi longtemps que possible, et au moins jusqu'en 2030. Cependant, si votre projet utilise encore po4a-updatepo et po4a-translate a cette date, vous pourriez avoir un probleme. Nous pourrions egalement annuler la depreciation de ces scripts a un moment donne, si une reecriture elimine la duplication du code. Si vous avez des idees (ou mieux: un correctif), votre aide est la bienvenue. Qu'en est-il des autres outils de traduction de documentation utilisant gettext ? Il y en a quelques-uns. Voici une liste potentiellement incomplete, et d'autres outils arrivent a l'horizon. poxml C'est l'outil developpe au sein du projet KDE pour gerer les XML DocBook. C'est a notre connaissance le premier programme qui a extrait des chaines a traduire d'une documentation pour les mettre dans un fichier PO, et les reinjecter ensuite dans le document apres la traduction. Il ne peut gerer que le format XML, avec une DTD particuliere. Je n'aime pas beaucoup la facon dont les listes sont gerees, elles sont rassemblees en un seul gros msgid. Lorsque la liste est de taille importante, les elements sont assez durs a gerer. po-debiandoc Ce programme ecrit par Denis Barbier est un precurseur du module SGML de po4a, qui le remplace plus ou moins. Comme son nom l'indique, il ne gere que la DTD DebianDoc, qui est en voie d'extinction. xml2po.py Utilise par l'equipe de documentation de GIMP depuis 2004, il fonctionne assez bien meme si, comme son nom l'indique, il ne fonctionne qu'avec des fichiers XML et necessite des makefiles specialement configures. Sphinx Le projet de documentation Sphinx utilise egalement gettext de maniere intensive pour gerer ses traductions. Malheureusement, il ne fonctionne que pour quelques formats de texte, rest et markdown, bien qu'il soit peut-etre le seul outil a faire cela en gerant l'ensemble du processus de traduction. Le principal avantage de po4a par rapport a eux est la facilite d'ajouter du contenu additionnel (ce qui est encore plus difficile avec ces outils) et la possibilite de faire une gettextisation. RESUME des avantages de l'approche basee sur gettext o Les traductions ne sont pas stockees independamment de l'original, ce qui rend possible la detection des parties a mettre a jour. o Les traductions sont stockees dans des fichiers differents pour chaque langue, ce qui evite les interferences entre equipes de traduction. Que ce soit pour la soumission de rustines ou pour le choix d'un encodage. o En interne, tout est base sur gettext (mais po4a offre une interface simple qui ne necessite pas de comprendre comment tout marche en interne pour pouvoir l'utiliser). Ce qui permet de ne pas reinventer la roue, et du fait de leur utilisation importante, nous pouvons supposer qu'ils ont peu ou pas de bogue. o Pour l'utilisation finale, rien ne change (a part que les documentations seront probablement mieux maintenues :). La documentation distribuee reste la meme. o Il n'est pas necessaire pour les membres des equipes de traduction d'apprendre une nouvelle syntaxe et leur editeur de fichier PO prefere (qui peut etre le mode PO d'Emacs, Lokalize ou Gtranslator) sera parfait. o gettext permet d'obtenir facilement des statistiques sur ce qui a ete fait, ce qui doit etre revu et mis a jour, et sur ce qu'il reste a faire. Vous trouverez des exemples a ces adresses : - https://docs.kde.org/stable5/en/kdesdk/lokalize/project-view.html - http://www.debian.org/intl/l10n/ Mais tout n'est pas rose, et cette approche a aussi quelques desavantages que nous devons gerer. o Les addendas sont surprenants au premier abord. o Il n'est pas possible d'adapter le texte traduit a votre gout, comme de decomposer ou recomposer des paragraphes. Mais d'un autre cote, s'il s'agit d'un probleme dans le document original, celui-ci doit etre signale de toute facon. o Meme s'il a une interface simple, il reste un nouvel outil qu'il faudra apprendre a maitriser. Un de mes reves serait d'integrer po4a a Gtranslator ou Lokalize. Lorsqu'un fichier de documentation serait ouvert, ses chaines seraient extraites automatiquement. Lors de l'enregistrement, le fichier traduit + un fichier po seraient ecrits sur le disque. Si nous arrivions a faire un module pour MS Word (TM) (ou au moins pour le format RTF), po4a pourrait meme etre utilises dans le milieu de la traduction professionnelle. VOIR AUSSI o La documentation de l'outil tout-en-un que vous devriez utiliser : po4a(1). o La documentation des scripts po4a individuels : po4a-gettextize(1), po4a-updatepo(1), po4a-translate(1), po4a-normalize(1). o Les scripts d'assistance supplementaires : msguntypot(1), po4a-display-man(1), po4a-display-pod(1). o Les parsers de chaque format, en particulier pour consulter les options acceptees par chacun d'entre eux : Locale::Po4a::AsciiDoc(3pm) Locale::Po4a::Dia(3pm), Locale::Po4a::Guide(3pm), Locale::Po4a::Ini(3pm), Locale::Po4a::KernelHelp(3pm), Locale::Po4a::Man(3pm), Locale::Po4a::RubyDoc(3pm), Locale::Po4a::Texinfo(3pm), Locale::Po4a::Text(3pm), Locale::Po4a::Xhtml(3pm), Locale::Po4a::Yaml(3pm), Locale::Po4a::BibTeX(3pm), Locale::Po4a::Docbook(3pm), Locale::Po4a::Halibut(3pm), Locale::Po4a::LaTeX(3pm), Locale::Po4a::Pod(3pm), Locale::Po4a::Sgml(3pm), Locale::Po4a::TeX(3pm), Locale::Po4a::Wml(3pm), Locale::Po4a::Xml(3pm). o La mise en oeuvre de l'infrastructure de base: Locale::Po4a::TransTractor(3pm) (particulierement important pour comprendre l'organisation du code), Locale::Po4a::Chooser(3pm), Locale::Po4a::Po(3pm), Locale::Po4a::Common(3pm). Consultez egalement le fichier CONTRIBUTING.md dans l'arborescence des sources. AUTEURS Denis Barbier Martin Quinson (mquinson#debian.org) TRADUCTION Martin Quinson (mquinson#debian.org) perl v5.38.2 2024-06-26 PO4A.7(1)