Provided by:
po4a_0.41-1_all 
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).