Provided by: po4a_0.45-1_all bug

NOM

       Locale::Po4a::Xml - Convertir les documents XML (ou dérivés) depuis ou vers des fichiers
       PO

DESCRIPTION

       L'objectif du projet po4a [PO for anything -- PO pour tout] est de simplifier la
       traduction (et de façon plus intéressante, la maintenance des traductions) en utilisant
       les outils gettext dans des domaines pour lesquels ils n'étaient pas destinés, comme la
       documentation.

       Locale::Po4a::Xml est un module qui permet d'aider à traduire des documents XML dans
       d'autres langues. Il peut aussi servir de base pour créer d'autres modules pour des
       documents basés sur le format XML.

TRADUCTION AVEC PO4A::XML

       Ce module peut être utilisé directement pour traiter des documents dans un format
       générique XML. Le contenu des balises sera extrait, mais pas celui des attributs, parce
       que c'est ainsi que sont écrits la plupart des documents basés sur XML.

       Il y a quelques options (décrites dans la section suivante) qui peuvent permettre de
       paramétrer ce comportement. Si ça ne correspond pas au format de votre document, vous êtes
       encouragé à écrire votre propre module dérivé de celui-ci, pour décrire en détails votre
       format. Consultez la section ÉCRITURE DE MODULES DÉRIVÉS plus bas, pour un descriptif de
       la procédure.

OPTIONS ACCEPTÉES PAR CE MODULE

       L'option globale de débogage permet d'indiquer à ce module d'afficher les chaînes exclues,
       de façon à voir s'il saute quelque chose d'important.

       Voici les options particulières à ce module :

       nostrip
           Évite que les espaces autour de la chaîne extraite ne soient éliminées.

       wrap
           Crée une forme canonique de la chaîne à traduire, en considérant que les espaces ne
           sont pas importants, et remet en forme le document traduit. Cette option peut être
           surchargée par l'option de personnalisation des balises. Veuillez voir l'option
           « tags » qui suit.

       caseinsensitive
           Rend la recherche des balises et attributs insensibles à la casse. Si elle n'est pas
           définie, <BooK>laNG et <BOOK>Lang seront traités comme <book>lang.

       includeexternal
           Lorsque cette option est définie, les entités externes sont incluses dans le document
           généré (la traduction) et pour l'extraction des chaînes. Sinon, vous devrez traduire
           ces entités externes séparément, comme des documents indépendants.

       ontagerror
           Cette option permet de changer le comportement du module lorsqu'il rencontre une
           construction XML non valable (une balise est fermée ne correspondant pas à la dernière
           balise ouverte, ou un attribut d'une balise sans valeur). Elle peut prendre les
           valeurs suivantes :

           fail
               Il s'agit de la valeur par défaut. Le module échouera avec un message d'erreur.

           warn
               Le module continuera, mais affichera un avertissement.

           silent
               Le module continuera, sans afficher de message d'avertissement.

           Faites attention avec cette option. Il est généralement recommandé de corriger le
           fichier d'entrée.

       tagsonly
           N'extrait que les balises spécifiées par l'option « tags ». Sinon, toutes seront
           extraites, sauf celles spécifiées.

           Note : Cette option est obsolète.

       doctype
           Chaîne qui sera comparée à la première ligne du doctype du document (s'il est défini).
           Si elle ne correspond pas, un avertissement indiquera que le document n'est peut-être
           pas du bon type.

       addlang
           Chaîne indiquant le chemin (par exemple, <bbb><aaa>) d'une balise pour laquelle un
           attribut lang="..." doit être ajouté. La langue sera définie comme étant le nom du
           fichier PO sans l'extension .po.

       tags
           Liste de balises (séparées par des espaces) que vous voulez traduire ou sauter. Par
           défaut, les balises spécifiées seront exclues, mais si vous utilisez l'option
           « tagsonly », les balises spécifiées seront les seules à être inclues. Les balises
           doivent être de la forme <aaa>, mais vous pouvez en joindre (<bbb><aaa>) pour indiquer
           que le contenu de la balise <aaa> ne sera traduit que lorsqu'elle est comprise dans
           une balise <bbb>.

           Vous pouvez également spécifier des options aux balises en précédant les hiérarchies
           de balises par des caractères. Par exemple, vous pouvez ajouter un « w » (wrap -
           remise en forme) ou « W » (pas de remise en forme) pour changer le comportement par
           défaut fourni par l'option « wrap » globale.

           Par exemple : W<chapitre><titre>

           Note : Cette option est obsolète. Vous devriez utiliser les options translated et
           untranslated à la place.

       attributes
           Liste d'attributs de balises (séparés par des espaces) que vous voulez traduire. Vous
           pouvez spécifier les attributs par leur nom (par exemple, « lang »), mais vous pouvez
           aussi les faire précéder d'une hiérarchie de balises pour indiquer que cet attribut ne
           sera traduit que quand il sera placé à l'intérieur d'une balise. Par exemple :
           <bbb><aaa>lang indique que l'attribut lang ne sera traduit que s'il se trouve dans une
           balise <aaa>, se trouvant elle-même dans une balise <bbb>.

       foldattributes
           Ne pas traduire les attributs des balises « inline ». À la place, remplacer tous les
           attributs de la balise par po4a-id=<id>.

           Ceci est utile quand des attributs ne doivent pas être traduits, puisque cela
           simplifie les chaînes pour les traducteurs et évite les fautes de typographie.

       customtag
           Liste de balises (séparées par des espaces) qui ne doivent pas être traitées comme des
           balises. Ces balises sont prisent en charge comme des balises en ligne, et n'ont pas
           besoin d'être fermées.

       break
           Liste de balises (séparées par des espaces) qui doivent interrompre les séquences. Par
           défaut, toutes les balises introduisent une césure.

           Les balises doivent être de la forme <aaa>, mais vous pouvez en joindre (<bbb><aaa>)
           si une balise (<aaa>) ne doit être prise en compte que si elle se trouve dans une
           autre balise (<bbb>).

       inline
           Liste de balises (séparées par des espaces) que vous voulez voir traitées en ligne.
           Par défaut, toutes les balises introduisent une césure.

           Les balises doivent être de la forme <aaa>, mais vous pouvez en joindre (<bbb><aaa>)
           si une balise (<aaa>) ne doit être prise en compte que si elle se trouve dans une
           autre balise (<bbb>).

       placeholder
           Liste de balises (séparées par des espaces) qui servent à conserver un emplacement.
           Ces balises n'introduisent pas de césure, mais leur contenu est traduit séparément.

           L'emplacement d'un « placeholder » dans son bloc sera marqué à l'aide d'un chaîne
           similaire à :

             <placeholder type=\"footnote\" id=\"0\"/>

           Les balises doivent être de la forme <aaa>, mais vous pouvez en joindre (<bbb><aaa>)
           si une balise (<aaa>) ne doit être prise en compte que si elle se trouve dans une
           autre balise (<bbb>).

       nodefault
           Liste de balises (séparées par des espaces) que le module doit placer par défaut dans
           aucune catégorie.

       cpp Prise en charge des directives du préprocesseur C. Quand cette option est activée,
           po4a considérera les directives du préprocesseur comme des césures de paragraphe.
           C'est important si le préprocesseur est utilisé pour le fichier XML car sinon, les
           directives pourraient être insérées au milieu de lignes si po4a considère qu'elles
           appartiennent au paragraphe en cours, et elles ne seraient plus reconnues par le
           préprocesseur. Note : les directive du préprocesseur ne doivent apparaître qu'entre
           des balises (elles ne doivent pas introduire de césure).

       translated
           Liste de balises, séparées par des espaces, que vous souhaitez traduire.

           Les balises doivent être de la forme <aaa>, mais vous pouvez en joindre (<bbb><aaa>)
           si une balise (<aaa>) ne doit être prise en compte que si elle se trouve dans une
           autre balise (<bbb>).

           Vous pouvez également spécifier des options aux balises en précédant les hiérarchies
           de balises par des caractères. Par exemple, vous pouvez ajouter un « w » (wrap -
           remise en forme) ou « W » (pas de remise en forme) pour changer le comportement par
           défaut fourni par l'option « wrap » globale.

           Par exemple : W<chapitre><titre>

       untranslated
           Liste de balises, séparées par des espaces, que vous ne souhaitez pas traduire.

           Les balises doivent être de la forme <aaa>, mais vous pouvez en joindre (<bbb><aaa>)
           si une balise (<aaa>) ne doit être prise en compte que si elle se trouve dans une
           autre balise (<bbb>).

       defaulttranslateoption
           Les catégories par défaut pour les balises qui ne sont dans aucune des catégories
           translated, untranslated, break, inline ou placeholder.

           Il s'agit d'un ensemble de lettres :

           w   Les balises doivent être traduites et leur contenu peut être remis en forme.

           W   Les balises doivent être traduites et leur contenu ne doit pas être remis en
               forme.

           i   Les balises doivent être traduites en ligne.

           p   Les balises doivent être traduites comme moyen de conserver un emplacement.

ÉCRITURE DE MODULES DÉRIVÉS

   DÉFINITION DES BALISES ET ATTRIBUTS À TRADUIRE
       La configuration la plus simple consiste à définir quelles balises et attributs vous
       voulez que l'analyseur traduise. Elle doit être faite dans la fonction initialize. Vous
       devez dans un premier temps appeler la fonction initialize principale, pour obtenir les
       options de la ligne de commande, puis ajouter vos propres configurations à la table de
       hachage options. Si vous voulez traiter de nouvelles options de la ligne de commande, vous
       devez les définir avant d'appeler la fonction initialize principale :

         $self->{options}{'new_option'}='';
         $self->SUPER::initialize(%options);
         $self->{options}{'_default_translated'}.=' <p> <head><title>';
         $self->{options}{'attributes'}.=' <p>lang id';
         $self->{options}{'_default_inline'}.=' <br>';
         $self->treat_options;

       Vous devriez utiliser les options _default_inline, _default_break, _default_placeholder,
       _default_translated, _default_untranslated et _default_attributes dans les modules
       dérivés. Ceci permet aux utilisateurs de surcharger en ligne de commande le comportement
       par défaut défini par votre module.

   SURCHARGE DE LA FONCTION found_string
       Une autre étape simple consiste à surcharger la fonction « found_string », qui prend les
       chaînes extraites par l'analyseur en paramètre, pour les traduire. Elle vous permet de
       contrôler quelles chaînes vous voulez traduire, et d'effectuer des transformations avant
       ou après la traduction en elle-même.

       Elle reçoit le texte extrait, la référence où elle se trouve, et une table de hachage qui
       contient des informations additionnelles permettant de contrôler quelles sont les chaînes
       à traduire, comment les traduire et de générer le commentaire.

       Le contenu de ces options dépend du type de la chaîne (spécifié dans une entrée de la
       table de hachage) :

       type="tag"
           La chaîne trouvée est le contenu d'une balise à traduire. L'entrée « tag_options »
           contient les caractères d'options se trouvant en tête de la hiérarchie de balise de
           l'option « tags » du module.

       type="attribute"
           Signifie que la chaîne trouvée correspond à la valeur d'un attribut à traduire.
           L'entrée « attribute » contient le nom de l'attribut.

       Elle doit renvoyer le texte qui remplacera l'original dans le document traduit. Voici un
       exemple simple d'implémentation de cette fonction :

         sub found_string {
           my ($self,$text,$ref,$options)=@_;
           $text = $self->translate($text,$ref,"type ".$options->{'type'},
             'wrap'=>$self->{options}{'wrap'});
           return $text;
         }

       Il y a également un exemple simple dans le module Dia, qui ne filtre que quelques chaînes.

   MODIFIER LE TYPE DES BALISES  FAIRE)
       Ceci est plus complexe, mais permet un contrôle (presque) total du paramétrage. C'est basé
       sur une liste de tables de hachage, chacune définissant le comportement d'un type de
       balise. La liste doit être triée de façon à ce que les balises les plus générales se
       trouvent après les plus concrètes (trié dans un premier temps par la clé « beginning »
       puis par « end »). Pour définir un type de balise, vous n'aurez qu'à créer une table de
       hachage avec les clés suivantes :

       beginning
           Spécifie le début de la balise, suivi de « < ».

       end Spécifie la fin de la balise, précédé de « > ».

       breaking
           Indique s'il s'agit d'une balise de césure. Une balise n'étant pas de césure (en
           ligne) peut être incluse dans le contenu d'une autre. L'option peut prendre les
           valeurs fausse (0), vraie (1) ou non définie. Si vous la laissez non définie, vous
           devrez définir la fonction f_breaking qui indique si une balise d'une classe donnée
           est une balise de césure ou pas.

       f_breaking
           C'est une fonction qui indique si la balise suivante est une balise de césure ou pas.
           Elle devrait être définie si l'option breaking ne l'est pas.

       f_extract
           Si vous ne définissez pas cette clé, la fonction générique d'extraction devra extraire
           la balise elle-même. Elle est utile pour les balises qui peuvent contenir d'autres
           balises ou structures particulières, de façon à ce que l'analyseur ne devienne pas
           fou. Cette fonction prend en paramètre un booléen qui indique si la balise doit être
           retirée du flux d'entrée ou non.

       f_translate
           Cette fonction prend en paramètre une balise (dans le format de get_string_until()) et
           renvoie la balise traduite (avec les attributs traduits ou n'importe quelle
           transformation nécessaire) en une seule chaîne.

FONCTIONS INTERNES utilisées pour dériver un analyseur (parser)

   TRAITEMENT DES BALISES
       get_path()
           Cette fonction renvoie le chemin vers la balise actuelle à partir de la racine du
           document, sous la forme <html><body><p>.

           Un tableau supplémentaire de balises (sans chevrons) peut être fourni en paramètre.
           Ces éléments du chemin sont ajoutés à la fin du chemin en cours.

       tag_type()
           Cette fonction renvoie l'index dans la liste tag_types qui correspond à la prochaine
           balise du flux d'entrée ou -1 s'il s'agit de la fin du fichier d'entrée.

       extract_tag($$)
           Cette fonction renvoie la balise suivante du flux d'entrée sans son début ou sa fin,
           sous la forme d'un tableau, pour maintenir les références du fichier d'entrée. Elle
           prend deux paramètres : le type de la balise (tel qu'il est renvoyé par tag_type) et
           un booléen indiquant s'il doit être retiré du flux d'entrée.

       get_tag_name(@)
           Cette fonction renvoie le nom de la balise passée en paramètre, dans la même forme que
           le tableau renvoyé par extract_tag.

       breaking_tag()
           Cette fonction renvoie un booléen qui indique si la prochaine balise est une balise de
           césure ou pas (balise en ligne). Le flux d'entrée n'est pas touché.

       treat_tag()
           Cette fonction traduit la balise suivante du flux d'entrée, en utilisant les fonctions
           de traduction personnalisées pour chaque balise.

       tag_in_list($@)
           Cette fonction renvoie une chaîne qui indique si son premier paramètre (une hiérarchie
           de balise) correspond à une des balises du second paramètre (une liste de balises ou
           une hiérarchie de balises). Si elle ne correspond pas, la valeur 0 est renvoyée.
           Sinon, elle renvoie les options de la balise qui correspond (les caractères qui la
           précèdent) ou 1 (si la balise n'a pas d'option).

   TRAITEMENT DES ATTRIBUTS
       treat_attributes(@)
           Cette fonction s'occupe de la traduction des attributs des balises. Elle reçoit les
           balises sans les marquer de début ou de fin, puis trouve les attributs, et traduit
           ceux qui doivent l'être (spécifiés par l'option « attributes » du module). Elle
           renvoie une chaîne brute avec les balises traduites.

   TRAITEMENT DES OPTIONS DU MODULE
       treat_options()
           Cette fonction remplit les structures internes qui contiennent les balises, les
           attributs et les données à mettre en ligne en fonction des options du module
           (spécifiées par la ligne de commande ou dans la fonction initialize).

   RÉCUPÉRER DU TEXTE DU DOCUMENT D'ENTRÉE
       get_string_until($%)
           Cette fonction renvoie un tableau des lignes (et leurs références) du document
           d'entrée de son début jusqu'à ce que soit trouvé son premier paramètre. Le second
           paramètre est une table de hachage d'options. La valeur 0 signifie que l'option est
           désactivée (par défaut) et 1, activée.

           Les options valables sont :

           include
               Fait en sorte que le tableau renvoyé contient le texte recherché

           remove
               Retire de l'entrée le flux renvoyé

           unquoted
               Permet de s'assurer que le texte recherché ne se trouve pas entre guillemets

       skip_spaces(\@)
           Cette fonction reçoit en paramètre la référence à un paragraphe (dans le format
           renvoyé par get_string_until), retire les espaces de tête et les renvoie comme une
           simple chaîne.

       join_lines(@)
           Cette fonction renvoie une simple chaîne à partir du texte fourni en paramètre sous la
           forme d'un tableau (en ignorant la référence).

ÉTAT DE CE MODULE

       Ce module peut traduire les balises et les attributs.

LISTE DES CHOSES À FAIRE

       DOCTYPE (ENTITÉS)

       La traduction des entités est à peine supportée. Les entités sont traduites telles
       quelles, et les balises qu'elles contiennent ne sont pas prises en compte. Les entités sur
       plusieurs lignes ne sont pas supportées. De plus, les entités sont remises en forme
       pendant la traduction.

       MODIFIER LES BALISES DEPUIS LES MODULES DÉRIVÉS (déplacer la structure tag_types à
       l'intérieur de la table de hachage $self ?)

VOIR AUSSI

       Locale::Po4a::TransTractor(3pm), po4a(7)

AUTEURS

        Jordi Vilalta <jvprat@gmail.com>
        Nicolas François <nicolas.francois@centraliens.net>

TRADUCTION

        Martin Quinson (mquinson#debian.org)

COPYRIGHT ET LICENCE

        Copyright (c) 2004 by Jordi Vilalta  <jvprat@gmail.com>
        Copyright (c) 2008-2009 by Nicolas François <nicolas.francois@centraliens.net>

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