Locale::Po4a::Xml - convertit les documents XML (ou dérivés) depuis/vers des fichiers PO

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.

Veuillez noter que ce module est encore en développement, et toujours pas distribué dans la livraison officielle de po4a parce que nous ne pensons pas qu'il soit suffisamment mature. Si vous insistez pour l'essayer, veuillez récupérer la version du CVS.

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.

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.

tagsonly

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, 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>

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 ».

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;

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) : 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. 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.

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.

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).

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.

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).

get_string_until($%)

Cette fonction renvoie un tableau des lignes (et leur 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é. 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 sue 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).

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.

DOCTYPE (ENTITÉS)

La traduction des entités est à peine supportée. Les entités sont traduites telle quelle, et les balises qu'elle contiennent ne sont pas prises en compte. Les entitées sur plusieur 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 balise de césure à l'intérieur d'autres balises n'étant pas de césure (est-ce possible?) provoquent d'horribles commentaires

po4a(7), Locale::Po4a::TransTractor(3pm).

 Jordi Vilalta <jvprat@gmail.com>

 Martin Quinson (mquinson#debian.org)

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).