
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 NOM

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

=head1 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.

=head1 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
B<ÉCRITURE DE MODULES DÉRIVÉS> plus bas, pour un descriptif de la procédure.

=head1 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 :

=over 4

=item B<nostrip>

Évite que les espaces autour de la chaîne extraite ne soient éliminées.

=item B<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 B<translated> qui suit.

=item B<unwrap_attributes>

Les attributs sont mis en forme par défaut. Cette option désactive la mise
en forme.

=item B<caseinsensitive>

Rend la recherche des balises et attributs insensibles à la casse. Si elle
n’est pas définie, E<lt>BooKE<gt>laNG et E<lt>BOOKE<gt>Lang seront traités
comme E<lt>bookE<gt>lang.

=item B<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

=item B<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.

=item B<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 :

=over

=item I<fail>

Il s’agit de la valeur par défaut. Le module échouera avec un message
d’erreur.

=item I<warn>

Le module continuera, mais affichera un avertissement.

=item I<silent>

Le module continuera, sans afficher de message d’avertissement.

=back

Faites attention avec cette option. Il est généralement recommandé de
corriger le fichier d’entrée.

=item B<tagsonly>

Note : Cette option est obsolète.

N’extrait que les balises spécifiées par l’option B<tags>. Sinon, toutes
seront extraites, sauf celles spécifiées.

=item B<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.

=item B<addlang>

Chaîne indiquant le chemin (par exemple, E<lt>bbbE<gt>E<lt>aaaE<gt>) 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.

=item B<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 B<ontagerror>.

=item B<tags>

Note : Cette option est obsolète. Vous devriez utiliser les options
B<translated> et B<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 S<« tagsonly »>, les balises spécifiées seront les seules
à être inclues. Les balises doivent être de la forme E<lt>aaaE<gt>, mais
vous pouvez en joindre (E<lt>bbbE<gt>E<lt>aaaE<gt>) pour indiquer que le
contenu de la balise E<lt>aaaE<gt> ne sera traduit que lorsqu’elle est
comprise dans une balise E<lt>bbbE<gt>.

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 I<w> (renvoyer à la ligne) ou I<W> (ne pas renvoyer à la
ligne) pour remplacer le comportement par défaut spécifié par l’option
globale B<wrap>.

Par S<exemple :> WE<lt>chapitreE<gt>E<lt>titreE<gt>

=item B<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 :E<lt>bbbE<gt>E<lt>aaaE<gt>lang indique que l’attribut « lang » ne
sera traduit que s’il se trouve dans une balise E<lt>aaaE<gt>, se trouvant
elle-même dans une balise E<lt>bbbE<gt>.

=item B<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.

=item B<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.

=item B<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 B<break>, B<inline>, B<placeholder>, ou B<customtag>.

=item B<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>).

=item B<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>).

=item B<break-pi>

Par défaut, les instructions de traitement (c'est-à-dire les balises
C<E<lt>? ... ?E<gt>>) 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.

=item B<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 B<nodefault>.

=item B<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).

=item B<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 B<wrap> et B<defaulttranslateoption>.

=over

=item I<w>

Les balises doivent être traduites et leur contenu peut être remis en forme.

=item I<W>

Les balises doivent être traduites et leur contenu ne doit pas être remis en
forme.

=item I<i>

Les balises doivent être traduites en ligne.

=item I<p>

Les balises doivent être traduites comme moyen de conserver un emplacement.

=back

En interne, l'analyseur XML ne se soucie que de ces quatre options : I<w>
I<W> I<i> I<p>.

* Les balises répertoriées dans B<break> sont définies à I<w> ou I<W> selon
l'option B<wrap>.

* Les balises répertoriées dans B<inline> sont définies à I<i>.

* Les étiquettes énumérées dans B<placeholder> sont définies à I<p>.

* Les balises répertoriées dans B<untranslated> sont sans aucune de ces
options définies.

Vous pouvez vérifier le comportement réel des paramètres internes en lançant
B<po4a> avec l'option B<--debug>.

Par S<exemple :> WE<lt>chapitreE<gt>E<lt>titreE<gt>

Veuillez noter qu'une balise doit être listée dans l’option B<translated> ou
B<untranslated>.

=item B<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<i> est supprimé et I<w> ou I<W> est défini selon l'option B<wrap>.

=item B<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 B<translated> et ce
paramètre n'est valable que pour les balises traduisibles.

=back

=head1 ÉCRITURE DE MODULES DÉRIVÉS

=head2 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 B<_default_inline>, B<_default_break>,
B<_default_placeholder>, B<_default_translated>, B<_default_untranslated> et
B<_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.

=head2 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 L<Locale::Po4a::Docbook(3pm)|Locale::Po4a::Docbook>,

=head2 SURCHARGE DE LA FONCTION found_string

Une autre étape simple consiste à surcharger la fonction S<« 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) :

=over

=item type="tag"

La chaîne trouvée est le contenu d’une balise à traduire. L’entrée S<«
tag_options »> contient les caractères d’options se trouvant en tête de la
hiérarchie de balise de l’option S<« tags »> du module.

=item type="attribute"

Signifie que la chaîne trouvée correspond à la valeur d’un attribut à
traduire. L’entrée S<« attribute »> contient le nom de l’attribut.

=back

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.

=head2 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 :

=over 4

=item B<beginning>

Spécifie le début de la balise, suivi de S<« E<lt> »>.

=item B<end>

Spécifie la fin de la balise, précédé de S<« E<gt> »>.

=item B<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.

=item B<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 B<breaking> ne l’est
pas.

=item B<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.

=item B<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.

=back

=head1 FONCTIONS INTERNES utilisées pour écrire un analyseur (parser) dérivé

=head2 TRAITEMENT DES BALISES

=over 4

=item get_path()

Cette fonction renvoie le chemin vers la balise actuelle à partir de la
racine du document, sous la forme E<lt>htmlE<gt>E<lt>bodyE<gt>E<lt>pE<gt>.

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.

=item 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 E<lt> et se terminant par
E<gt> et elle peut contenir plusieurs lignes.

Cela fonctionne avec le tableau C<< @{$self->{TT}{doc_in}} >> en conservant
les données et les références des documents d'entrée indirectement via C<<
$self->shiftline() >> et C<< $self->unshiftline($$) >>.

=item 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 S<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 C<< @{$self->{TT}{doc_in}} >> en conservant
les données et les références des documents d'entrée indirectement via C<<
$self->shiftline() >> et C<< $self->unshiftline($$) >>.

=item 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.

=item 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é.

=item 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 C<< @{$self->{TT}{doc_in}} >> en conservant
les données et les références des documents d'entrée indirectement via C<<
$self->shiftline() >> et C<< $self->unshiftline($$) >>.

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

=back

=head2 TRAITEMENT DES ATTRIBUTS

=over 4

=item 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 B<attributes> du
module). Elle renvoie une chaîne brute avec les balises traduites.

=back

=head2 TRAITEMENT DES CONTENUS BALISÉS

=over 4

=item 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 C<< @{$self->{TT}{doc_in}} >> en conservant
les données et les références des documents d'entrée indirectement via C<<
$self->shiftline() >> et C<< $self->unshiftline($$) >>.

=back

=head2 TRAITEMENT DES OPTIONS DU MODULE

=over 4

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

=back

=head2 RÉCUPÉRER DU TEXTE DU DOCUMENT D’ENTRÉE

=over

=item 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 :

=over 4

=item B<include>

Fait en sorte que le tableau renvoyé contient le texte recherché

=item B<remove>

Retire de l’entrée le flux renvoyé

=item B<unquoted>

Permet de s’assurer que le texte recherché ne se trouve pas entre guillemets

=item B<regex>

Cela indique que le premier argument est une expression régulière plutôt
qu'une simple chaîne de caractères

=back

=item 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.

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

=back

=head1 ÉTAT DE CE MODULE

Ce module peut traduire les balises et les attributs.

=head1 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 S<$self ?>)

=head1 VOIR AUSSI

L<Locale::Po4a::TransTractor(3pm)|Locale::Po4a::TransTractor>,
L<po4a(7)|po4a.7>

=head1 AUTEURS

 Jordi Vilalta <jvprat@gmail.com>
 Nicolas François <nicolas.francois@centraliens.net>


=head1 TRADUCTION

 Martin Quinson (mquinson#debian.org)

=head1 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 S<libre ;> vous pouvez le copier et / ou le
modifier sous les termes de la GPL v2.0 ou suivante (voir le fichier
COPYING).
