blib::man::Xml(3pm)

NOM
Locale::Po4a::Xml - convertit les documents XML (ou derives) depuis/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.

Veuillez noter que ce module est encore en developpement, et toujours pas distribue dans la livraison officielle de po4a parce que nous ne pensons pas qu'il soit suffisamment mature. Si vous insistez pour l'essayer, veuillez recuperer la version du CVS.

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 X Writing derivate modules X plus bas, pour un descriptif de la procedure.

OPTIONS ACCEPTEES 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 X tags X 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.

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

doctype
    Chaine qui sera comparee a la premiere ligne du doctype du document (s'il est defini). Si elle ne correspond pas, le document sera considere comme etant du mauvais type.

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 X tagsonly X, 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 X w X (wrap - remise en forme) ou X W X (pas de remise en forme) pour changer le comportement par defaut fourni par l'option X wrap X globale.

    Par exemple : W<chapitre><titre>

attributes
    Liste d'attributs de balises (separes par des espaces) que vous voulez traduire. Vous pouvez specifier les attributs par leur nom (par exemple, X lang X), 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>.

inline
    Liste de balises (separees par des espaces) que vous voulez voir traitees en ligne. Par defaut, toutes les balises introduisent une cesure. La meme syntaxe que celle de l'option tags est utilisee.

nodefault
    Liste de balises (separees par des espaces) que le module ne doit pas placer, par defaut, dans les categories X tags X ou X inline X.

ECRITURE DE MODULES DERIVES

  DEFINITION 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}{'tags'}.=' <p> <head><title>';
  $self->{options}{'attributes'}.=' <p>lang id';
  $self->{options}{'inline'}.=' <br>';
  $self->treat_options;

  SURCHARGE DE LA FONCTION found_string
Une autre etape simple consiste a surcharger la fonction X found_string X, 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 X tag_options X contient les caracteres d'options se trouvant en tete de la hierarchie de balise de l'option X tags X du module.

type="attribute"
    Signifie que la chaine trouvee correspond a la valeur d'un attribut a traduire. L'entree X attribute X 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 X beginning X puis par X end X). 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 X < X.

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

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 X breaking X 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 utiliser pour deriver 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>.

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

  RECUPERER DU TEXTE DU DOCUMENT D'ENTREE

get_string_until($%)
    Cette fonction renvoie un tableau des lignes (et leur 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, active.

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

Le support des entites et des fichiers inclus est dans la liste des choses a faire.

L'ecriture de modules derives est plutot limitee.

LISTE DES CHOSES A FAIRE
DOCTYPE (ENTITES)

La traduction des entites est a peine supportee. Les entites sont traduites telle quelle, et les balises qu'elle contiennent ne sont pas prises en compte. Les entitees sur plusieur lignes ne sont pas supportees. De plus, les entites sont remises en forme pendant la traduction.

INCLUSIONS DE FICHIERS

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

Les balise de cesure a l'interieur d'autres balises n'etant pas de cesure (est-ce possible?) provoquent d'horribles commentaires

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

AUTEURS
 Jordi Vilalta <jvprat@gmail.com>

TRADUCTION
 Martin Quinson (mquinson#debian.org)

COPYRIGHT ET LICENCE
Copyright (c) 2004 par Jordi Vilalta <jvprat@gmail.com>

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