Provided by: po4a_0.36.1-1_all bug

NOM

       Locale::Po4a::Xml - Convertit les documents XML (ou dérivés)
       depuis/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 «Writing derivate modules» 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.

       tags
           Space-separated list of tags you want to translate or skip.  By
           default, the specified tags will be excluded, but if you use the
           "tagsonly" option, the specified tags will be the only ones
           included.  The tags must be in the form <aaa>, but you can join
           some (<bbb><aaa>) to say that the content of the tag <aaa> will
           only be translated when it’s into a <bbb> tag.

           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
           Space-separated list of tag’s attributes you want to translate.
           You can specify the attributes by their name (for example, "lang"),
           but you can prefix it with a tag hierarchy, to specify that this
           attribute will only be translated when it’s into the specified tag.
           For example: <bbb><aaa>lang specifies that the lang attribute will
           only be translated if it’s into an <aaa> tag, and it’s into a <bbb>
           tag.

       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.

       break
           Space-separated list of tags which should break the sequence.  By
           default, all tags break the sequence.

           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
           Space-separated list of tags which should be treated as
           placeholders.  Placeholders do not break the sequence, but the
           content of placeholders is translated separately.

           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
           Space separated list of tags that the module should not try to set
           by default in any category.

       cpp Support C preprocessor directives.  When this option is set, po4a
           will consider preprocessor directives as paragraph separators.
           This is important if the XML file must be preprocessed because
           otherwise the directives may be inserted in the middle of lines if
           po4a consider it belong to the current paragraph, and they won’t be
           recognized by the preprocessor.  Note: the preprocessor directives
           must only appear between tags (they must not break a tag).

       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
           The default categories for tags that are not in any of the
           translated, untranslated, break, inline, or placeholder.

           This is a set of letters:

           w   Tags should be translated and content can be re-wrapped.

           W   Tags should be translated and content should not be re-wrapped.

           i   Tags should be translated inline.

           p   Tags should be translated as placeholders.

É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;

       You should use the _default_inline, _default_break,
       _default_placeholder, _default_translated, _default_untranslated, and
       _default_attributes options in derivated modules. This allow users to
       override the default behavior defined in your module with command line
       options.

   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 utiliser 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>.

           An additional array of tags (without brackets) can be passed in
           argument.  These path elements are added to the end of the current
           path.

       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 DENTRÉ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

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

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).