Provided by: po4a_0.41-1_all bug

NOM

       Locale::Po4a::Xml - Convertir les documents XML (ou derives) 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 facon plus interessante, la maintenance
       des traductions) en utilisant les outils gettext dans des domaines pour
       lesquels ils n'etaient pas destines, comme la documentation.

       Locale::Po4a::Xml est un module qui permet d'aider a traduire des
       documents XML dans d'autres langues. Il peut aussi servir de base pour
       creer d'autres modules pour des documents bases sur le format XML.

TRADUCTION AVEC PO4A::XML

       Ce module peut etre utilise directement pour traiter des documents dans
       un format generique XML. Le contenu des balises sera extrait, mais pas
       celui des attributs, parce que c'est ainsi que sont ecrits la plupart
       des documents bases sur XML.

       Il y a quelques options (decrites dans la section suivante) qui peuvent
       permettre de parametrer ce comportement. Si ca ne correspond pas au
       format de votre document, vous etes encourage a ecrire votre propre
       module derive de celui-ci, pour decrire en details votre format.
       Consultez la section 'ECRITURE DE MODULES D'ERIV'ES plus bas, pour un
       descriptif de la procedure.

OPTIONS ACCEPT'EES PAR CE MODULE

       L'option globale de debogage permet d'indiquer a ce module d'afficher
       les chaines exclues, de facon a voir s'il saute quelque chose
       d'important.

       Voici les options particulieres a ce module:

       nostrip
           Evite que les espaces autour de la chaine extraite ne soient
           eliminees.

       wrap
           Cree une forme canonique de la chaine a traduire, en considerant
           que les espaces ne sont pas importants, et remet en forme le
           document traduit. Cette option peut etre surchargee par l'option de
           personnalisation des balises. Veuillez voir l'option <<tags>> qui
           suit.

       caseinsensitive
           Rend la recherche des balises et attributs insensibles a la casse.
           Si elle n'est pas definie, <BooK>laNG et <BOOK>Lang seront traites
           comme <book>lang.

       includeexternal
           Lorsque cette option est definie, les entites externes sont
           incluses dans le document genere (la traduction) et pour
           l'extraction des chaines. Sinon, vous devrez traduire ces entites
           externes separement, comme des documents independants.

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

           fail
               Il s'agit de la valeur par defaut. Le module echouera 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 generalement recommande
           de corriger le fichier d'entree.

       tagsonly
           N'extrait que les balises specifiees par l'option <<tags>>. Sinon,
           toutes seront extraites, sauf celles specifiees.

           Note: Cette option est obsolete.

       doctype
           Chaine qui sera comparee a la premiere ligne du doctype du document
           (s'il est defini). Si elle ne correspond pas, un avertissement
           indiquera que le document n'est peut-etre pas du bon type.

       addlang
           Chaine indiquant le chemin (par exemple, <bbb><aaa>) d'une balise
           pour laquelle un attribut lang="..." doit etre ajoute. La langue
           sera definie comme etant le nom du fichier PO sans l'extension .po.

       tags
           Liste de balises (separees par des espaces) que vous voulez
           traduire ou sauter. Par defaut, les balises specifiees seront
           exclues, mais si vous utilisez l'option <<tagsonly>>, les balises
           specifiees seront les seules a etre inclues. Les balises doivent
           etre 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 egalement specifier des options aux balises en
           precedant les hierarchies de balises par des caracteres. Par
           exemple, vous pouvez ajouter un <<w>> (wrap - remise en forme) ou
           <<W>> (pas de remise en forme) pour changer le comportement par
           defaut fourni par l'option <<wrap>> globale.

           Par exemple: W<chapitre><titre>

           Note: Cette option est obsolete. Vous devriez utiliser les options
           translated et untranslated a la place.

       attributes
           Liste d'attributs de balises (separes par des espaces) que vous
           voulez traduire. Vous pouvez specifier les attributs par leur nom
           (par exemple, <<lang>>), mais vous pouvez aussi les faire preceder
           d'une hierarchie de balises pour indiquer que cet attribut ne sera
           traduit que quand il sera place a l'interieur 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-meme
           dans une balise <bbb>.

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

           Ceci est utile quand des attributs ne doivent pas etre traduits,
           puisque cela simplifie les chaines pour les traducteurs et evite
           les fautes de typographie.

       customtag
           Liste de balises (separees par des espaces) qui ne doivent pas etre
           traitees comme des balises. Ces balises sont prisent en charge
           comme des balises en ligne, et n'ont pas besoin d'etre fermees.

       break
           Liste de balises (separees par des espaces) qui doivent interrompre
           les sequences. Par defaut, toutes les balises introduisent une
           cesure.

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

       inline
           Liste de balises (separees par des espaces) que vous voulez voir
           traitees en ligne. Par defaut, toutes les balises introduisent une
           cesure.

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

       placeholder
           Liste de balises (separees par des espaces) qui servent a conserver
           un emplacement. Ces balises n'introduisent pas de cesure, mais leur
           contenu est traduit separement.

           L'emplacement d'un <<placeholder>> dans son bloc sera marque a
           l'aide d'un chaine similaire a:

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

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

       nodefault
           Liste de balises (separees par des espaces) que le module doit
           placer par defaut dans aucune categorie.

       cpp Prise en charge des directives du preprocesseur C. Quand cette
           option est activee, po4a considerera les directives du
           preprocesseur comme des cesures de paragraphe. C'est important si
           le preprocesseur est utilise pour le fichier XML car sinon, les
           directives pourraient etre inserees au milieu de lignes si po4a
           considere qu'elles appartiennent au paragraphe en cours, et elles
           ne seraient plus reconnues par le preprocesseur. Note: les
           directive du preprocesseur ne doivent apparaitre qu'entre des
           balises (elles ne doivent pas introduire de cesure).

       translated
           Liste de balises, separees par des espaces, que vous souhaitez
           traduire.

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

           Vous pouvez egalement specifier des options aux balises en
           precedant les hierarchies de balises par des caracteres. Par
           exemple, vous pouvez ajouter un <<w>> (wrap - remise en forme) ou
           <<W>> (pas de remise en forme) pour changer le comportement par
           defaut fourni par l'option <<wrap>> globale.

           Par exemple: W<chapitre><titre>

       untranslated
           Liste de balises, separees par des espaces, que vous ne souhaitez
           pas traduire.

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

       defaulttranslateoption
           Les categories par defaut pour les balises qui ne sont dans aucune
           des categories translated, untranslated, break, inline ou
           placeholder.

           Il s'agit d'un ensemble de lettres:

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

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

           i   Les balises doivent etre traduites en ligne.

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

'ECRITURE DE MODULES D'ERIV'ES

   D'EFINITION DES BALISES ET ATTRIBUTS `A TRADUIRE
       La configuration la plus simple consiste a definir quelles balises et
       attributs vous voulez que l'analyseur traduise. Elle doit etre 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 a la table de
       hachage options. Si vous voulez traiter de nouvelles options de la
       ligne de commande, vous devez les definir 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_untranslatedet
       _default_attributes dans les modules derives. Ceci permet aux
       utilisateurs de surcharger en ligne de commande le comportement par
       defaut defini par votre module.

   SURCHARGE DE LA FONCTION found_string
       Une autre etape simple consiste a surcharger la fonction
       <<found_string>>, qui prend les chaines extraites par l'analyseur en
       parametre, pour les traduire. Elle vous permet de controler quelles
       chaines vous voulez traduire, et d'effectuer des transformations avant
       ou apres la traduction en elle-meme.

       Elle recoit le texte extrait, la reference ou elle se trouve, et une
       table de hachage qui contient des informations additionnelles
       permettant de controler quelles sont les chaines a traduire, comment
       les traduire et de generer le commentaire.

       Le contenu de ces options depend du type de la chaine (specifie dans
       une entree de la table de hachage):

       type="tag"
           La chaine trouvee est le contenu d'une balise a traduire. L'entree
           <<tag_options>> contient les caracteres d'options se trouvant en
           tete de la hierarchie de balise de l'option <<tags>> du module.

       type="attribute"
           Signifie que la chaine trouvee correspond a la valeur d'un attribut
           a traduire. L'entree <<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'implementation 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 egalement un exemple simple dans le module Dia, qui ne filtre
       que quelques chaines.

   MODIFIER LE TYPE DES BALISES (`A FAIRE)
       Ceci est plus complexe, mais permet un controle (presque) total du
       parametrage. C'est base sur une liste de tables de hachage, chacune
       definissant le comportement d'un type de balise. La liste doit etre
       triee de facon a ce que les balises les plus generales se trouvent
       apres les plus concretes (trie dans un premier temps par la cle
       <<beginning>> puis par <<end>>). Pour definir un type de balise, vous
       n'aurez qu'a creer une table de hachage avec les cles suivantes:

       beginning
           Specifie le debut de la balise, suivi de <<<>>.

       end Specifie la fin de la balise, precede de <<>>>.

       breaking
           Indique s'il s'agit d'une balise de cesure. Une balise n'etant pas
           de cesure (en ligne) peut etre incluse dans le contenu d'une autre.
           L'option peut prendre les valeurs fausse (0), vraie (1) ou non
           definie. Si vous la laissez non definie, vous devrez definir la
           fonction f_breaking qui indique si une balise d'une classe donnee
           est une balise de cesure ou pas.

       f_breaking
           C'est une fonction qui indique si la balise suivante est une balise
           de cesure ou pas. Elle devrait etre definie si l'option breaking ne
           l'est pas.

       f_extract
           Si vous ne definissez pas cette cle, la fonction generique
           d'extraction devra extraire la balise elle-meme. Elle est utile
           pour les balises qui peuvent contenir d'autres balises ou
           structures particulieres, de facon a ce que l'analyseur ne devienne
           pas fou. Cette fonction prend en parametre un booleen qui indique
           si la balise doit etre retiree du flux d'entree ou non.

       f_translate
           Cette fonction prend en parametre une balise (dans le format de
           get_string_until()) et renvoie la balise traduite (avec les
           attributs traduits ou n'importe quelle transformation necessaire)
           en une seule chaine.

FONCTIONS INTERNES utilis'ees pour d'eriver un analyseur (parser)

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

           Un tableau supplementaire de balises (sans chevrons) peut etre
           fourni en parametre. Ces elements du chemin sont ajoutes a la fin
           du chemin en cours.

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

       extract_tag($$)
           Cette fonction renvoie la balise suivante du flux d'entree sans son
           debut ou sa fin, sous la forme d'un tableau, pour maintenir les
           references du fichier d'entree. Elle prend deux parametres: le type
           de la balise (tel qu'il est renvoye par tag_type) et un booleen
           indiquant s'il doit etre retire du flux d'entree.

       get_tag_name(@)
           Cette fonction renvoie le nom de la balise passee en parametre,
           dans la meme forme que le tableau renvoye par extract_tag.

       breaking_tag()
           Cette fonction renvoie un booleen qui indique si la prochaine
           balise est une balise de cesure ou pas (balise en ligne). Le flux
           d'entree n'est pas touche.

       treat_tag()
           Cette fonction traduit la balise suivante du flux d'entree, en
           utilisant les fonctions de traduction personnalisees pour chaque
           balise.

       tag_in_list($@)
           Cette fonction renvoie une chaine qui indique si son premier
           parametre (une hierarchie de balise) correspond a une des balises
           du second parametre (une liste de balises ou une hierarchie de
           balises). Si elle ne correspond pas, la valeur 0 est renvoyee.
           Sinon, elle renvoie les options de la balise qui correspond (les
           caracteres qui la precedent) 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 recoit les balises sans les marquer de debut ou de fin, puis
           trouve les attributs, et traduit ceux qui doivent l'etre (specifies
           par l'option <<attributes>> du module). Elle renvoie une chaine
           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 donnees a mettre en ligne en fonction
           des options du module (specifiees par la ligne de commande ou dans
           la fonction initialize).

   R'ECUP'ERER DU TEXTE DU DOCUMENT D'ENTR'EE
       get_string_until($%)
           Cette fonction renvoie un tableau des lignes (et leurs references)
           du document d'entree de son debut jusqu'a ce que soit trouve son
           premier parametre. Le second parametre est une table de hachage
           d'options. La valeur 0 signifie que l'option est desactivee (par
           defaut) et 1, activee.

           Les options valables sont:

           include
               Fait en sorte que le tableau renvoye contient le texte
               recherche

           remove
               Retire de l'entree le flux renvoye

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

       skip_spaces(\@)
           Cette fonction recoit en parametre la reference a un paragraphe
           (dans le format renvoye par get_string_until), retire les espaces
           de tete et les renvoie comme une simple chaine.

       join_lines(@)
           Cette fonction renvoie une simple chaine a partir du texte fourni
           en parametre sous la forme d'un tableau (en ignorant la reference).

'ETAT DE CE MODULE

       Ce module peut traduire les balises et les attributs.

LISTE DES CHOSES `A FAIRE

       DOCTYPE (ENTITES)

       La traduction des entites est a peine supportee. Les entites sont
       traduites telles quelles, et les balises qu'elles contiennent ne sont
       pas prises en compte. Les entites sur plusieurs lignes ne sont pas
       supportees. De plus, les entites sont remises en forme pendant la
       traduction.

       MODIFIER LES BALISES DEPUIS LES MODULES DERIVES (deplacer la structure
       tag_types a l'interieur de la table de hachage $self?)

VOIR AUSSI

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

AUTEURS

        Jordi Vilalta <jvprat@gmail.com>
        Nicolas Francois <nicolas.francois@centraliens.net>

COPYRIGHT ET LICENCE

        Copyright (c) 2004 by Jordi Vilalta  <jvprat@gmail.com>
        Copyright (c) 2008-2009 by Nicolas Francois <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).