'; $self->{options}{'attributes'}.=' lang id'; $self->{options}{'_default_inline'}.=' '; $self->treat_options; Vous devriez utiliser les options _default_inline, _default_break, _default_placeholder, _default_translated, _default_untranslated et _default_attributes dans les modules derives. Ceci permet de surcharger en ligne de commande le comportement par defaut defini par votre module. REMPLACER LE COMPORTEMENT PAR DEFAUT AVEC LES OPTIONS EN LIGNE DE COMMANDE Si vous n'aimez pas le comportement par defaut de ce module xml et de ses modules derives, 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 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 utilisees pour ecrire un analyseur (parser) derive 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>. 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. Ici, la balise a une structure commencant par < et se terminant par > et elle peut contenir plusieurs lignes. Cela fonctionne avec le tableau "@{$self->{TT}{doc_in}}" en conservant les donnees et les references des documents d'entree indirectement via "$self->shiftline()" et "$self->unshiftline($$)". 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. Cela fonctionne avec le tableau "@{$self->{TT}{doc_in}}" en conservant les donnees et les references des documents d'entree indirectement via "$self->shiftline()" et "$self->unshiftline($$)". 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. Cela fonctionne avec le tableau "@{$self->{TT}{doc_in}}" en conservant les donnees et les references des documents d'entree indirectement via "$self->shiftline()" et "$self->unshiftline($$)". 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 gere la traduction des attributs de balises. Elle recoit les balises sans les marqueurs 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 CONTENUS BALISES treat_content() Cette fonction recupere le texte jusqu'a la prochaine balise fermante (qui n'est pas en ligne) du flux d'entree. Traduisez-le en utilisant les fonctions de traduction personnalisees pour chaque balise. Cela fonctionne avec le tableau "@{$self->{TT}{doc_in}}" en conservant les donnees et les references des documents d'entree 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 donnees a mettre en ligne en fonction des options du module (specifiees par la ligne de commande ou dans la fonction initialize). RECUPERER DU TEXTE DU DOCUMENT D'ENTREE 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 regex Cela indique que le premier argument est une expression reguliere plutot qu'une simple chaine de caracteres 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 Locale::Po4a::TransTractor(3pm), po4a(7) AUTEURS Jordi Vilalta <jvprat@gmail.com> Nicolas Francois <nicolas.francois@centraliens.net> TRADUCTION Martin Quinson (mquinson#debian.org) COPYRIGHT ET LICENCE Copyright (C) 2004 Jordi Vilalta <jvprat@gmail.com> Copyright (C) 2008-2009 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 v2.0 ou suivante (voir le fichier COPYING). perl v5.38.2 2024-06-26 LOCALE::PO4A::XML.3PM(1)

LOCALE::PO4A::XML.3PM(1) User Contributed Perl Documentation 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 cela ne correspond pas au format de votre document, je vous encourage a ecrire votre propre module derive de celui-ci, pour decrire en details votre format. Consultez la section ECRITURE DE MODULES DERIVES plus bas, pour un descriptif de la procedure. OPTIONS ACCEPTEES 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. Referez-vous a l'option translated qui suit. unwrap_attributes Les attributs sont mis en forme par defaut. Cette option desactive la mise en forme. caseinsensitive Rend la recherche des balises et attributs insensibles a la casse. Si elle n'est pas definie, laNG et Lang seront traites comme lang. escapequotes Guillemets d'echappement dans les chaines de sortie. Necessaires, par exemple, pour creer des ressources de chaine pour etre utilisees par les outils de construction d'Android. Voir egalement : https://developer.android.com/guide/topics/resources/string-resource.html 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 syntaxe XML invalide (une balise est fermee ne correspondant pas a la derniere balise ouverte. 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 Note : Cette option est obsolete. N'extrait que les balises specifiees par l'option tags. Sinon, toutes seront extraites, sauf celles specifiees. 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, ) 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. optionalclosingtag Booleen indiquant si les balises de fermeture sont facultatives (comme en HTML). Par defaut, l'absence de balises fermantes provoque une erreur traitee selon la methode ontagerror. tags Note : Cette option est obsolete. Vous devriez utiliser les options translated et untranslated a la place. 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 , mais vous pouvez en joindre () pour indiquer que le contenu de la balise ne sera traduit que lorsqu'elle est comprise dans une balise . Vous pouvez egalement specifier certaines options de balise en placant certains caracteres devant la hierarchie des balises. Par exemple, vous pouvez placer w (renvoyer a la ligne) ou W (ne pas renvoyer a la ligne) pour remplacer le comportement par defaut specifie par l'option globale wrap. Par exemple : W 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 :lang indique que l'attribut << lang >> ne sera traduit que s'il se trouve dans une balise , se trouvant elle-meme dans une balise . foldattributes Ne pas traduire les attributs des balises << inline >>. A la place, remplacer tous les attributs de la balise par po4a-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 , mais vous pouvez en joindre () si une balise () ne doit etre prise en compte que si elle se trouve dans une autre balise (). Veuillez noter qu'une balise ne peut figurer que dans une seule des chaines de parametrage break, inline, placeholder, ou customtag. 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 , mais vous pouvez en joindre () si une balise () ne doit etre prise en compte que si elle se trouve dans une autre balise (). 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 : Les balises doivent etre de la forme , mais vous pouvez en joindre () si une balise () ne doit etre prise en compte que si elle se trouve dans une autre balise (). break-pi Par defaut, les instructions de traitement (c'est-a-dire les balises "") sont traitees comme des balises en ligne. Passez cette option si vous souhaitez que les instructions de traitement soient traitees comme une balise de rupture. Notez que les balises PHP non traitees sont gerees par l'analyseur comme des instructions de traitement. nodefault Liste de balises (separees par des espaces) que le module doit placer par defaut dans aucune categorie. Si vous avez une balise dont le parametre par defaut est defini par la sous-classe de ce module mais que vous souhaitez definir un autre parametre, vous devez l'inscrire dans la chaine de parametres nodefault. 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 , mais vous pouvez en joindre () si une balise () ne doit etre prise en compte que si elle se trouve dans une autre balise (). Vous pouvez egalement specifier des options aux balises en precedant les hierarchies de balises par des caracteres. Ceci ecrase le comportement par defaut renseigne par les options wrap et defaulttranslateoption. 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. En interne, l'analyseur XML ne se soucie que de ces quatre options : w W i p. * Les balises repertoriees dans break sont definies a w ou W selon l'option wrap. * Les balises repertoriees dans inline sont definies a i. * Les etiquettes enumerees dans placeholder sont definies a p. * Les balises repertoriees dans untranslated sont sans aucune de ces options definies. Vous pouvez verifier le comportement reel des parametres internes en lancant po4a avec l'option --debug. Par exemple : W Veuillez noter qu'une balise doit etre listee dans l'option translated ou untranslated. untranslated Liste de balises, separees par des espaces, que vous ne souhaitez pas traduire. Les balises doivent etre de la forme , mais vous pouvez en joindre () si une balise () ne doit etre prise en compte que si elle se trouve dans une autre balise (). Veuillez noter qu'une balise en ligne traduisible dans une balise non traduite est traitee comme une balise de rupture traduisible, le parametre i est supprime et w ou W est defini selon l'option wrap. 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 tel que defini dans translated et ce parametre n'est valable que pour les balises traduisibles. ECRITURE DE MODULES DERIVES DEFINITION 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'}.='