Provided by:
po4a_0.33.3-1_all 
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
This option defines the behavior of the module when it encounter a
invalid Xml syntax (a closing tag which does not match the last
opening tag, or a tag’s attribute without value). It can take the
following values:
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: This option is deprecated.
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, le document
sera considéré comme étant du mauvais type.
tags
Liste de balises (séparées par des espaces) que vous voulez
traduire ou sauter. Par défaut, les balises spécifiées seront
exclues, mais si vous utilisez l’option « tagsonly », les balises
spécifiées seront les seules à être inclues. Les balises doivent
être 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 é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: This option is deprecated. You should use the translated and
untranslate options instead.
attributes
Liste d’attributs de balises (séparés par des espaces) que vous
voulez traduire. Vous pouvez spécifier les attributs par leur nom
(par exemple, « lang »), mais vous pouvez aussi les faire
précéder d’une hiérarchie de balises pour indiquer que cet
attribut ne sera traduit que quand il sera placé à l’intérieur
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-même dans une 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. La même syntaxe que celle de l’option tags est
utilisée.
nodefault
Liste de balises (séparées par des espaces) que le module ne doit
pas placer, par défaut, dans les catégories « tags » ou
« inline ».
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 =item 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 itâ<bbb> tag.
You can also specify some tag options putting some characters in
front of the tag hierarchy. For example, you can put âto overide
the default behavior specified by the global "wrap" option.
Par exemple : W<chapitre><titre>
ÃCRITURE DE MODULES DÃRIVÃS
RADUIRE
DÃFINITION DES BALISES ET ATTRIBUTS Ã.PP 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}{'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 é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.
AIRE)
MODIFIER LE TYPE DES BALISES (Ã.PP 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>.
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 Dâ€â€™ENTRÃ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.
Le support des entités et des fichiers inclus est dans la liste des
choses à faire.
L’écriture de modules dérivés est plutôt limitée.
AIRE
AIRE"
LISTE DES CHOSES Ã.IX Header "LISTE DES CHOSES Ã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.
INCLUSIONS DE FICHIERS
MODIFIER LES BALISES DEPUIS LES MODULES DÃRIVÃS (déplacer la structure
tag_types à l’intérieur de la table de hachage $self ?)
Les balises de césure à l’intérieur d’autres balises n’étant pas de
césure (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).