Linux Certif

Toute la documentation sur la certification Linux LPI

Locale::Po4a::Xml.3pm

NOM

Locale::Po4a::Xml - Convertit les documents XML (ou dA~XrivA~Xs) depuis/vers des fichiers PO

DESCRIPTION

L'objectif du projet po4a [po for anything --- po pour tout] est de simplifier la traduction (et de faA~Xon plus intA~Xressante, la maintenance des traductions) en utilisant les outils gettext dans des domaines pour lesquels ils n'A~Xtaient pas destinA~Xs, 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 crA~Xer d'autres modules pour des documents basA~Xs sur le format XML.

TRADUCTION AVEC PO4A::XML

Ce module peut A~Xtre utilisA~X directement pour traiter des documents dans un format gA~XnA~Xrique XML. Le contenu des balises sera extrait, mais pas celui des attributs, parce que c'est ainsi que sont A~Xcrits la plupart des documents basA~Xs sur XML.

Il y a quelques options (dA~Xcrites dans la section suivante) qui peuvent permettre de paramA~Xtrer ce comportement. Si A~Xa ne correspond pas au format de votre document, vous A~Xtes encouragA~X A~  A~Xcrire votre propre module dA~XrivA~X de celui-ci, pour dA~Xcrire en dA~Xtails votre format. Consultez la section AX Writing derivate modules AX plus bas, pour un descriptif de la procA~Xdure.

OPTIONS ACCEPTA~XES PAR CE MODULE

L'option globale de dA~Xbogage permet d'indiquer A~  ce module d'afficher les chaA~Xnes exclues, de faA~Xon A~  voir s'il saute quelque chose d'important.

Voici les options particuliA~Xres A~  ce module :

nostrip

A~Xvite que les espaces autour de la chaA~Xne extraite ne soient A~XliminA~Xes.

wrap

CrA~Xe une forme canonique de la chaA~Xne A~  traduire, en considA~Xrant que les espaces ne sont pas importants, et remet en forme le document traduit. Cette option peut A~Xtre surchargA~Xe par l'option de personnalisation des balises. Veuillez voir l'option AX tags AX qui suit.

caseinsensitive

Rend la recherche des balises et attributs insensibles A~  la casse. Si elle n'est pas dA~Xfinie, <BooK>laNG et <BOOK>Lang seront traitA~Xs comme <book>lang.

includeexternal

Lorsque cette option est dA~Xfinie, les entitA~Xs externes sont incluses dans le document gA~XnA~XrA~X (la traduction) et pour l'extraction des chaA~Xnes. Sinon, vous devrez traduire ces entitA~Xs externes sA~XparA~Xment, comme des documents indA~Xpendants.

ontagerror

Cette option permet de changer le comportement du module lorsqu'il rencontre une construction Xml non valable (une balise est fermA~Xe ne correspondant pas A~  la derniA~Xre balise ouverte, ou un attribut d'une balise sans valeur). Elle peut prendre les valeurs suivantes :

fail

Il s'agit de la valeur par dA~Xfaut. Le module A~Xchouera 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 gA~XnA~Xralement recommandA~X de corriger le fichier d'entrA~Xe.

tagsonly

N'extrait que les balises spA~XcifiA~Xes par l'option AX tags AX. Sinon, toutes seront extraites, sauf celles spA~XcifiA~Xes.

Note: This option is deprecated.

doctype

ChaA~Xne qui sera comparA~Xe A~  la premiA~Xre ligne du doctype du document (s'il est dA~Xfini). Si elle ne correspond pas, le document sera considA~XrA~X comme A~Xtant du mauvais type.

tags

Liste de balises (sA~XparA~Xes par des espaces) que vous voulez traduire ou sauter. Par dA~Xfaut, les balises spA~XcifiA~Xes seront exclues, mais si vous utilisez l'option AX tagsonly AX, les balises spA~XcifiA~Xes seront les seules A~  A~Xtre inclues. Les balises doivent A~Xtre 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 A~Xgalement spA~Xcifier des options aux balises en prA~XcA~Xdant les hiA~Xrarchies de balises par des caractA~Xres. Par exemple, vous pouvez ajouter un AX w AX (wrap - remise en forme) ou AX W AX (pas de remise en forme) pour changer le comportement par dA~Xfaut fourni par l'option AX wrap AX globale.

Par exemple : W<chapitre><titre>

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

attributes

Liste d'attributs de balises (sA~XparA~Xs par des espaces) que vous voulez traduire. Vous pouvez spA~Xcifier les attributs par leur nom (par exemple, AX lang AX), mais vous pouvez aussi les faire prA~XcA~Xder d'une hiA~Xrarchie de balises pour indiquer que cet attribut ne sera traduit que quand il sera placA~X A~  l'intA~Xrieur 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-mA~Xme dans une balise <bbb>.

inline

Liste de balises (sA~XparA~Xes par des espaces) que vous voulez voir traitA~Xes en ligne. Par dA~Xfaut, toutes les balises introduisent une cA~Xsure. La mA~Xme syntaxe que celle de l'option tags est utilisA~Xe.

nodefault

Liste de balises (sA~XparA~Xes par des espaces) que le module ne doit pas placer, par dA~Xfaut, dans les catA~Xgories AX tags AX ou AX inline AX.

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

unstranslated

Space-separated list of the tags you want to translate or not. 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 itaXXs 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 aXXwaXX (wrap) or aXXWaXX (donaXXt wrap) to overide the default behavior specified by the global ``wrap'' option.

Par exemple : W<chapitre><titre>

A~XCRITURE DE MODULES DA~XRIVA~XS

DA~XFINITION DES BALISES ET ATTRIBUTS A~X TRADUIRE

La configuration la plus simple consiste A~  dA~Xfinir quelles balises et attributs vous voulez que l'analyseur traduise. Elle doit A~Xtre 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 dA~Xfinir 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 A~Xtape simple consiste A~  surcharger la fonction AX found_string AX, qui prend les chaA~Xnes extraites par l'analyseur en paramA~Xtre, pour les traduire. Elle vous permet de contrA~Xler quelles chaA~Xnes vous voulez traduire, et d'effectuer des transformations avant ou aprA~Xs la traduction en elle-mA~Xme.

Elle reA~Xoit le texte extrait, la rA~XfA~Xrence oA~X elle se trouve, et une table de hachage qui contient des informations additionnelles permettant de contrA~Xler quelles sont les chaA~Xnes A~  traduire, comment les traduire et de gA~XnA~Xrer le commentaire.

Le contenu de ces options dA~Xpend du type de la chaA~Xne (spA~XcifiA~X dans une entrA~Xe de la table de hachage) :

type="tag"

La chaA~Xne trouvA~Xe est le contenu d'une balise A~  traduire. L'entrA~Xe AX tag_options AX contient les caractA~Xres d'options se trouvant en tA~Xte de la hiA~Xrarchie de balise de l'option AX tags AX du module.

type="attribute"

Signifie que la chaA~Xne trouvA~Xe correspond A~  la valeur d'un attribut A~  traduire. L'entrA~Xe AX attribute AX contient le nom de l'attribut.

Elle doit renvoyer le texte qui remplacera l'original dans le document traduit. Voici un exemple simple d'implA~Xmentation 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 A~Xgalement un exemple simple dans le module Dia, qui ne filtre que quelques chaA~Xnes.

MODIFIER LE TYPE DES BALISES (A~X FAIRE)

Ceci est plus complexe, mais permet un contrA~Xle (presque) total du paramA~Xtrage. C'est basA~X sur une liste de tables de hachage, chacune dA~Xfinissant le comportement d'un type de balise. La liste doit A~Xtre triA~Xe de faA~Xon A~  ce que les balises les plus gA~XnA~Xrales se trouvent aprA~Xs les plus concrA~Xtes (triA~X dans un premier temps par la clA~X AX beginning AX puis par AX end AX). Pour dA~Xfinir un type de balise, vous n'aurez qu'A~  crA~Xer une table de hachage avec les clA~Xs suivantes :

beginning

SpA~Xcifie le dA~Xbut de la balise, suivi de AX < AX.

end

SpA~Xcifie la fin de la balise, prA~XcA~XdA~X de AX > AX.

breaking

Indique s'il s'agit d'une balise de cA~Xsure. Une balise n'A~Xtant pas de cA~Xsure (en ligne) peut A~Xtre incluse dans le contenu d'une autre. L'option peut prendre les valeurs fausse (0), vraie (1) ou non dA~Xfinie. Si vous la laissez non dA~Xfinie, vous devrez dA~Xfinir la fonction f_breaking qui indique si une balise d'une classe donnA~Xe est une balise de cA~Xsure ou pas.

f_breaking

C'est une fonction qui indique si la balise suivante est une balise de cA~Xsure ou pas. Elle devrait A~Xtre dA~Xfinie si l'option AX breaking AX ne l'est pas.

f_extract

Si vous ne dA~Xfinissez pas cette clA~X, la fonction gA~XnA~Xrique d'extraction devra extraire la balise elle-mA~Xme. Elle est utile pour les balises qui peuvent contenir d'autres balises ou structures particuliA~Xres, de faA~Xon A~  ce que l'analyseur ne devienne pas fou. Cette fonction prend en paramA~Xtre un boolA~Xen qui indique si la balise doit A~Xtre retirA~Xe du flux d'entrA~Xe ou non.

f_translate

Cette fonction prend en paramA~Xtre une balise (dans le format de get_string_until()) et renvoie la balise traduite (avec les attributs traduits ou n'importe quelle transformation nA~Xcessaire) en une seule chaA~Xne.

FONCTIONS INTERNES utiliser pour dA~Xriver 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'entrA~Xe ou -1 s'il s'agit de la fin du fichier d'entrA~Xe.

extract_tag($$)

Cette fonction renvoie la balise suivante du flux d'entrA~Xe sans son dA~Xbut ou sa fin, sous la forme d'un tableau, pour maintenir les rA~XfA~Xrences du fichier d'entrA~Xe. Elle prend deux paramA~Xtres : le type de la balise (tel qu'il est renvoyA~X par tag_type) et un boolA~Xen indiquant s'il doit A~Xtre retirA~X du flux d'entrA~Xe.

get_tag_name(@)

Cette fonction renvoie le nom de la balise passA~Xe en paramA~Xtre, dans la mA~Xme forme que le tableau renvoyA~X par extract_tag.

breaking_tag()

Cette fonction renvoie un boolA~Xen qui indique si la prochaine balise est une balise de cA~Xsure ou pas (balise en ligne). Le flux d'entrA~Xe n'est pas touchA~X.

treat_tag()

Cette fonction traduit la balise suivante du flux d'entrA~Xe, en utilisant les fonctions de traduction personnalisA~Xes pour chaque balise.

tag_in_list($@)

Cette fonction renvoie une chaA~Xne qui indique si son premier paramA~Xtre (une hiA~Xrarchie de balise) correspond A~  une des balises du second paramA~Xtre (une liste de balises ou une hiA~Xrarchie de balises). Si elle ne correspond pas, la valeur 0 est renvoyA~Xe. Sinon, elle renvoie les options de la balise qui correspond (les caractA~Xres qui la prA~XcA~Xdent) 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 reA~Xoit les balises sans les marquer de dA~Xbut ou de fin, puis trouve les attributs, et traduit ceux qui doivent l'A~Xtre (spA~XcifiA~Xs par l'option AX attributes AX du module). Elle renvoie une chaA~Xne 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 donnA~Xes A~  mettre en ligne en fonction des options du module (spA~XcifiA~Xes par la ligne de commande ou dans la fonction initialize).

RA~XCUPA~XRER DU TEXTE DU DOCUMENT D'ENTRA~XE

get_string_until($%)

Cette fonction renvoie un tableau des lignes (et leurs rA~XfA~Xrences) du document d'entrA~Xe de son dA~Xbut jusqu'A~  ce que soit trouvA~X son premier paramA~Xtre. Le second paramA~Xtre est une table de hachage d'options. La valeur 0 signifie que l'option est dA~XsactivA~Xe (par dA~Xfaut) et 1, activA~Xe.

Les options valables sont :

include

Fait en sorte que le tableau renvoyA~X contient le texte recherchA~X

remove

Retire de l'entrA~Xe le flux renvoyA~X

unquoted

Permet de s'assurer que le texte recherchA~X ne se trouve pas entre guillemets

skip_spaces(\@)

Cette fonction reA~Xoit en paramA~Xtre la rA~XfA~Xrence A~  un paragraphe (dans le format renvoyA~X par get_string_until), retire les espaces de tA~Xte et les renvoie comme une simple chaA~Xne.

join_lines(@)

Cette fonction renvoie une simple chaA~Xne A~  partir du texte fourni en paramA~Xtre sous la forme d'un tableau (en ignorant la rA~XfA~Xrence).

A~XTAT DE CE MODULE

Ce module peut traduire les balises et les attributs.

Le support des entitA~Xs et des fichiers inclus est dans la liste des choses A~  faire.

L'A~Xcriture de modules dA~XrivA~Xs est plutA~Xt limitA~Xe.

LISTE DES CHOSES A~X FAIRE

DOCTYPE (ENTITA~XS)

La traduction des entitA~Xs est A~  peine supportA~Xe. Les entitA~Xs sont traduites telles quelles, et les balises qu'elles contiennent ne sont pas prises en compte. Les entitA~Xs sur plusieurs lignes ne sont pas supportA~Xes. De plus, les entitA~Xs sont remises en forme pendant la traduction.

INCLUSIONS DE FICHIERS

MODIFIER LES BALISES DEPUIS LES MODULES DA~XRIVA~XS (dA~Xplacer la structure tag_types A~  l'intA~Xrieur de la table de hachage $self ?)

Les balises de cA~Xsure A~  l'intA~Xrieur d'autres balises n'A~Xtant pas de cA~Xsure (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).