Provided by: po4a_0.73-2ubuntu1_all 
NOM
Locale::Po4a::Xml - Convertir 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 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 cela ne correspond pas au format de votre document, je vous encourage à écrire votre
propre module dérivé de celui-ci, pour décrire en détails votre format. Consultez la section ÉCRITURE DE
MODULES DÉRIVÉS 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. Référez-vous à l’option translated qui suit.
unwrap_attributes
Les attributs sont mis en forme par défaut. Cette option désactive la mise en forme.
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.
escapequotes
Guillemets d’échappement dans les chaînes de sortie. Nécessaires, par exemple, pour créer des
ressources de chaîne pour être utilisées par les outils de construction d’Android.
Voir également : https://developer.android.com/guide/topics/resources/string-resource.html
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 syntaxe XML invalide
(une balise est fermée ne correspondant pas à la dernière balise ouverte. 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
Note : Cette option est obsolète.
N’extrait que les balises spécifiées par l’option tags. Sinon, toutes seront extraites, sauf celles
spécifiées.
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.
optionalclosingtag
Booléen indiquant si les balises de fermeture sont facultatives (comme en HTML). Par défaut,
l'absence de balises fermantes provoque une erreur traitée selon la méthode ontagerror.
tags
Note : Cette option est obsolète. Vous devriez utiliser les options translated et untranslated à la
place.
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 certaines options de balise en plaçant certains caractères devant la
hiérarchie des balises. Par exemple, vous pouvez placer w (renvoyer à la ligne) ou W (ne pas renvoyer
à la ligne) pour remplacer le comportement par défaut spécifié par l’option globale wrap.
Par exemple : W<chapitre><titre>
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 ». À 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 prisent 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>).
Veuillez noter qu'une balise ne peut figurer que dans une seule des chaînes de paramétrage break,
inline, placeholder, ou customtag.
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’un 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>).
break-pi
Par défaut, les instructions de traitement (c'est-à-dire les balises "<? ... ?>") sont traitées comme
des balises en ligne. Passez cette option si vous souhaitez que les instructions de traitement soient
traitées comme une balise de rupture. Notez que les balises PHP non traitées sont gérées par
l'analyseur comme des instructions de traitement.
nodefault
Liste de balises (séparées par des espaces) que le module doit placer par défaut dans aucune
catégorie.
Si vous avez une balise dont le paramètre par défaut est défini par la sous-classe de ce module mais
que vous souhaitez définir un autre paramètre, vous devez l'inscrire dans la chaîne de paramètres
nodefault.
cpp Prise en charge des directives du préprocesseur C. Quand cette option est activée, 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 directive 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. Ceci écrase le comportement par défaut renseigné par les options wrap et
defaulttranslateoption.
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 balises doivent être traduites comme moyen de conserver un emplacement.
En interne, l'analyseur XML ne se soucie que de ces quatre options : w W i p.
* Les balises répertoriées dans break sont définies à w ou W selon l'option wrap.
* Les balises répertoriées dans inline sont définies à i.
* Les étiquettes énumérées dans placeholder sont définies à p.
* Les balises répertoriées dans untranslated sont sans aucune de ces options définies.
Vous pouvez vérifier le comportement réel des paramètres internes en lançant po4a avec l'option
--debug.
Par exemple : W<chapitre><titre>
Veuillez noter qu'une balise doit être listée dans l’option translated ou untranslated.
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>).
Veuillez noter qu'une balise en ligne traduisible dans une balise non traduite est traitée comme une
balise de rupture traduisible, le paramètre i est supprimé et w ou W est défini selon l'option wrap.
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 tel que défini dans translated et ce paramètre n'est valable que
pour les balises traduisibles.
ÉCRITURE DE MODULES DÉRIVÉS
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_untranslated et _default_attributes dans les modules dérivés. Ceci permet
de surcharger en ligne de commande le comportement par défaut défini par votre module.
REMPLACER LE COMPORTEMENT PAR DÉFAUT AVEC LES OPTIONS EN LIGNE DE COMMANDE
Si vous n'aimez pas le comportement par défaut de ce module xml et de ses modules dérivés, vous pouvez
fournir des options en ligne de commande pour modifier leur comportement.
Lisez Locale::Po4a::Docbook(3pm),
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.
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 utilisées pour écrire un analyseur (parser) dérivé
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.
Ici, la balise a une structure commençant par < et se terminant par > et elle peut contenir plusieurs
lignes.
Cela fonctionne avec le tableau "@{$self->{TT}{doc_in}}" en conservant les données et les références
des documents d'entrée indirectement via "$self->shiftline()" et "$self->unshiftline($$)".
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.
Cela fonctionne avec le tableau "@{$self->{TT}{doc_in}}" en conservant les données et les références
des documents d'entrée indirectement via "$self->shiftline()" et "$self->unshiftline($$)".
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.
Cela fonctionne avec le tableau "@{$self->{TT}{doc_in}}" en conservant les données et les références
des documents d'entrée indirectement via "$self->shiftline()" et "$self->unshiftline($$)".
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 gère la traduction des attributs de balises. Elle reçoit les balises sans les
marqueurs 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 CONTENUS BALISÉS
treat_content()
Cette fonction récupère le texte jusqu’à la prochaine balise fermante (qui n'est pas en ligne) du
flux d’entrée. Traduisez-le en utilisant les fonctions de traduction personnalisées pour chaque
balise.
Cela fonctionne avec le tableau "@{$self->{TT}{doc_in}}" en conservant les données et les références
des documents d'entrée indirectement via "$self->shiftline()" et "$self->unshiftline($$)".
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
regex
Cela indique que le premier argument est une expression régulière plutôt qu'une simple chaîne de
caractères
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.
LISTE DES CHOSES À FAIRE
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.
MODIFIER LES BALISES DEPUIS LES MODULES DÉRIVÉS (déplacer la structure tag_types à l’intérieur de la
table de hachage $self ?)
VOIR AUSSI
Locale::Po4a::TransTractor(3pm), po4a(7)
AUTEURS
Jordi Vilalta <jvprat@gmail.com>
Nicolas François <nicolas.francois@centraliens.net>
TRADUCTION
Martin Quinson (mquinson#debian.org)
COPYRIGHT ET LICENCE
Copyright © 2004 Jordi Vilalta <jvprat@gmail.com>
Copyright © 2008-2009 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
v2.0 ou suivante (voir le fichier COPYING).
perl v5.38.2 2024-08-28 LOCALE::PO4A::XML.3PM(1)