NOM
Locale::Po4a::Xml - convertit les documents XML (ou dérivés) 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 façon plus intéressante, la maintenance
des traductions) en utilisant les outils gettext(1) 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 ECRITURE DE MODULES DERIVES plus bas, pour un
descriptif de la procédure.
OPTIONS ACCEPTEES 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 spécifiques à ce module :
nostrip
Evite que les espaces autour de la chaîne extraite ne soient
éliminés.
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
Cette option permet de changer le comportement du module lorsqu'il
rencontre une construction XML non valable (une balise est fermée ne
correspondant
pas à la dernière balise ouverte, ou un attribut d'une balise sans
valeur). Elle peut prendre les valeurs suivantes :
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 : cette option est obsolète.
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, un avertissement
indiquera que le document n'est peut-être pas du bon type.
addlang
Chaîne indiquant le chemin (par exemple, <bbb><aaa>) d'une balise
pour laquelle un attribut lang="..." doit être ajouté. La langue sera
définie comme étant le nom du fichier PO sans l'extension .po.
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 : cette option est obsolète. Vous devriez utiliser les options
translated et untranslated à la place.
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>.
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 être traduits,
puisque cela simplifie les chaînes pour les traducteurs et évite les
fautes de typographie.
customtag
Liste de balises (séparées par des espaces) qui ne doivent pas être
traitées comme des balises. Ces balises sont prise en charge comme
des balises en ligne, et n'ont pas besoin d'être fermées.
break
Liste de balises (séparées par des espaces) qui doivent interrompre
les séquences. Par défaut, toutes les balises introduisent une césure.
Les balises doivent être de la forme <aaa>, mais vous pouvez en
joindre (<bbb><aaa>) si une balise (<aaa>) ne doit être prise en
compte que si elle se trouve dans une autre 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.
Les balises doivent être de la forme <aaa>, mais vous pouvez en
joindre (<bbb><aaa>) si une balise (<aaa>) ne doit être prise en
compte que si elle se trouve dans une autre balise (<bbb>).
placeholder
Liste de balises (séparées par des espaces) qui servent à conserver un
emplacement. Ces balises n'introduisent pas de césure, mais leur
contenu est traduit séparément.
L'emplacement d'un placeholder dans son bloc sera marqué à l'aide
d'une chaîne similaire :
<placeholder type=\"footnote\" id=\"0\"/>
Les balises doivent être de la forme <aaa>, mais vous pouvez en
joindre (<bbb><aaa>) si une balise (<aaa>) ne doit être prise en
compte que si elle se trouve dans une autre balise (<bbb>).
nodefault
Liste de balises (séparées par des espaces) que le module doit placer
par défaut dans aucune catégorie.
cpp Prise en charge des directives du préprocesseur C. Quand cette
option est active, po4a considèrera les directives du préprocesseur
comme des césures de paragraphe. C'est important si le préprocesseur
est utilisé pour le fichier XML car sinon, les directives pourraient
être insérées au milieu de lignes si po4a considère qu'elles
appartiennent au paragraphe en cours, et elles ne seraient plus
reconnues par le préprocesseur. Note : les directives du préprocesseur
ne doivent apparaître qu'entre des balises (elles ne doivent pas
introduire de césure).
translated
Liste de balises, séparées par des espaces, que vous souhaitez
traduire.
Les balises doivent être de la forme <aaa>, mais vous pouvez en
joindre (<bbb><aaa>) si une balise (<aaa>) ne doit être prise en
compte que si elle se trouve dans une autre 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>
untranslated
Liste de balises, séparées par des espaces, que vous ne souhaitez pas
traduire.
Les balises doivent être de la forme <aaa>, mais vous pouvez en
joindre (<bbb><aaa>) si une balise (<aaa>) ne doit être prise en
compte que si elle se trouve dans une autre balise (<bbb>).
defaulttranslateoption
Les catégories par défaut pour les balises qui ne sont dans aucune
des catégories translated, untranslated, break, inline ou
placeholder.
Il s'agit d'un ensemble de lettres :
w Les balises doivent être traduites et leur contenu peut être
remis en forme.
W Les balises doivent être traduites et leur contenu ne doit pas
être remis en forme.
i Les balises doivent être traduites en ligne.
p Les balise doivent être traduites comme moyen de conserver un
emplacement.
ECRITURE DE MODULES DERIVES
Définition des balises et attributs à traduire
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}{'_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 dérivés. Ceci permet aux
utilisateurs de surcharger en ligne de commande le comportement par
défaut défini par votre module.
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'implmentation 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.
Modifier le type des balises (à faire)
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 UTILISEES POUR DERIVER 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>.
Un tableau supplémentaire de balises (sans chevrons) peut être fourni
en paramètre. Ces éléments du chemin sont ajoutés à la fin du chemin en
cours.
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,
active.
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).
ETAT DE CE MODULE
Ce module peut traduire les balises et les attributs.
LISTE DES CHOSES A FAIRE
DOCTYPE (ENTITES)
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.
MODIFIER LES BALISES DEPUIS LES MODULES DERIVES (déplacer la structure
tag_types à l'intérieur de la table de hachage $self?)
VOIR AUSSI
po4a(7), Locale::Po4a::TransTractor(3pm)
AUTEURS
Jordi Vilalta <jvprat@gmail.com>
Nicolas François <nicolas.francois@centraliens.net>
COPYRIGHT ET LICENCE
Copyright (c) 2004 by Jordi Vilalta <jvprat@gmail.com>
Copyright (c) 2008-2009 by Nicolas François <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).