Linux Certif

Toute la documentation sur la certification Linux LPI

Locale::Po4a::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.

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.

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 X tags X. Sinon, toutes seront extraites, sauf celles specifiees.

Note: This option is deprecated.

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>

Note: This option is deprecated. You should use the translated and untranslated options instead.

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.

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

Space-separated list of the tags you want to translate. The tags must be in the form <aaa>, but you can join some (<bbb><aaa>) to indicate that the content of the tag <aaa> will only be translated when it's into a <bbb> tag.

You can also specify some tag options putting some characters in front of the tag hierarchy. For example, you can put 'w' (wrap) or 'W' (don't wrap) to overide the default behavior specified by the global ``wrap'' option.

Par exemple : W<chapitre><titre>

untranslated

Space-separated list of the tags you do not want to translate or not. It uses the same format as the translated option.

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

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

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 balises 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>
  Nicolas Francois <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 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).