
        *****************************************************
        *           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::TransTractor - Traduction et extraction générique.

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

Cette classe est l’ancêtre de tous les analyseurs po4a utilisés pour lire un
document, y chercher les chaînes traduisibles, les extraire dans un fichier
PO, et les remplacer par leur traduction dans le document généré.

Plus formellement, elle prend les paramètres d’entrée suivants :

=over 2

=item -

un document à traduire ;

=item -

un fichier PO contenant les traductions à utiliser.

=back

En sortie, elle S<produit :>

=over 2

=item -

un autre fichier PO, résultat de l’extraction des chaînes traduisibles du
document en entrée ;

=item -

un document traduit, partageant la même structure que celui en entrée, mais
dont toutes les chaînes traduisibles ont été remplacées par les traductions
trouvées dans le fichier PO fourni en entrée.

=back

Voici une représentation graphique de tout cela :

   Input document --\                             /---> Output document
                     \                           /       (translated)
                      +-> parse() function -----+
                     /                           \
   Input PO --------/                             \---> Output PO
                                                         (extracted)

=head1 FONCTIONS QUE VOTRE ANALYSEUR DOIT SURCHARGER

=over 4

=item parse()

Il s’agit de la fonction principale où tout le travail a S<lieu :> la
lecture des documents en entrée, la génération des documents en sortie et
l’extraction des chaînes traduisibles. Tout ceci est assez simple avec les
fonctions fournies et présentées dans la section B<FONCTIONS INTERNES>
ci-dessous. Référez-vous à la section B<SYNOPSIS>, qui présente un exemple.

Cette fonction est appelée par la fonction process() ci-dessous, mais si
vous choisissez d’utiliser la fonction new(), et d’ajouter le contenu
manuellement, vous devrez appeler cette fonction vous-même.

=item docheader()

Cette fonction renvoie l’en-tête que nous devons ajouter au document
produit, formaté comme il faut pour qu’il soit un commentaire pour le
langage cible. Référez-vous à la section B<Éduquer les développeurs au
problème des traductions>, dans L<po4a(7)|po4a.7>.

=back

=head1 SYNOPSIS

L’exemple suivant analyse une liste de paragraphes commençant par
« <p> ». Pour simplifier, nous supposons que le document est bien formaté,
c’est-à-dire que la balise <p> est la seule présente et que cette balise se
trouve au début de chaque paragraphe.

 sub parse {
   my $self = shift;

   PARAGRAPH: while (1) {
       my ($paragraph,$pararef)=("","");
       my $first=1;
       my ($line,$lref)=$self->shiftline();
       while (defined($line)) {
           if ($line =~ m/<p>/ && !$first--; ) {
               # Not the first time we see <p>.
               # Reput the current line in input,
               #  and put the built paragraph to output
               $self->unshiftline($line,$lref);

               # Now that the document is formed, translate it:
               #   - Remove the leading tag
               $paragraph =~ s/^<p>//s;

               #   - push to output the leading tag (untranslated) and the
               #     rest of the paragraph (translated)
               $self->pushline(  "<p>"
                               . $self->translate($paragraph,$pararef)
                               );

               next PARAGRAPH;
           } else {
               # Append to the paragraph
               $paragraph .= $line;
               $pararef = $lref unless(length($pararef));
           }

           # Reinit the loop
           ($line,$lref)=$self->shiftline();
       }
       # Did not get a defined line? End of input file.
       return;
   }
 }

Une fois que vous avez implémenté la fonction parse, vous pouvez utiliser
cette nouvelle classe en utilisant l’interface publique présentée dans la
section suivante.

=head1 INTERFACE PUBLIQUE pour les scripts utilisant votre analyseur

=head2 Constructeur

=over 4

=item process(%)

Cette fonction peut faire tout ce dont vous avez besoin avec un document
po4a en une seule invocation. Ses paramètres doivent être fournis sous forme
de table de hachage. Voici les différentes actions possibles :

=over 3

=item a.

Lit tous les fichiers PO spécifiés dans po_in_name

=item b.

Lit tous les documents originaux spécifiés dans file_in_name

=item c.

Analyse le document

=item d.

Lit et applique tous les addendas spécifiés

=item e.

Écrit le document traduit dans file_out_name (si spécifié)

=item f.

Écrit le fichier PO extrait dans po_out_name (si spécifié)

=back

PARAMÈTRES, en plus de ceux acceptés par new(), ainsi que leur type :

=over 4

=item file_in_name (@)

Liste de noms de fichiers d’où lire les documents en entrée.

=item file_in_charset ($)

Le jeu de caractères du document d'entrée (s’il n’est pas spécifié, UTF-8
sera utilisé).

=item file_out_name ($)

Nom de fichier où écrire le document en sortie.

=item file_out_charset ($)

Le jeu de caractères du document de sortie (s’il n’est pas spécifié, UTF-8
sera utilisé).

=item po_in_name (@)

Liste de noms de fichiers d’où lire les fichiers PO d’entrée (ceux contenant
les traductions à utiliser pour la traduction du document).

=item po_out_name ($)

Nom de fichier où écrire le fichier PO de sortie (celui contenant les
chaînes extraites du document d’entrée).

=item addendum (@)

Liste de noms de fichiers d’où lire les addendas à appliquer.

=item addendum-charset ($)

Jeu de caractères des addendas.

=back

=item new(%)

Créer un nouveau document po4a. Options acceptées (dans le hachage passé en
tant que paramètre) :

=over 4

=item verbose ($)

Règle le niveau de bavardage.

=item debug ($)

Règle le niveau de débogage.

=item wrapcol ($)

La colonne à laquelle le texte doit être tronqué dans le document généré (76
par défaut).

Une valeur négative signifie de ne pas du tout tronquer les lignes.

=back

Le logiciel accepte également les options suivantes pour les fichiers Po
sous-jacents : B<porefs>, B<copyright-holder>, B<msgid-bugs-address>,
B<package-name>, B<package-version>, B<wrap-po>.

=back

=head2 Manipuler les documents

=over 4

=item read($$$)

Add another input document data at the end of the existing array C<<
@{$self->{TT}{doc_in}} >>.

This function takes two mandatory arguments and an optional one.
 * The filename to read on disk;
 * The name to use as filename when building the reference in the PO file;
 * The charset to use to read that file (UTF-8 by default)

This array C<< @{$self->{TT}{doc_in}} >> holds this input document data as an
array of strings with alternating meanings.
 * The string C<$textline> holding each line of the input text data.
 * The string C<< $filename:$linenum >> holding its location and called as
   "reference" (C<linenum> starts with 1).

Notez que cette fonction n’analyse pas le fichier donné. Il faut utiliser
parse() pour cela une fois que vous avez ajouté au document tous les
fichiers que vous souhaitez analyser.

=item write($)

Écrire le document traduit dans le fichier dont le nom est passé en
paramètre.

This translated document data are provided by:
 * C<< $self->docheader() >> holding the header text for the plugin, and
 * C<< @{$self->{TT}{doc_out}} >> holding each line of the main translated text in the array.

=back

=head2 Manipuler les fichiers PO

=over 4

=item readpo($)

Ajouter le contenu du fichier dont le nom est passé en paramètre au PO
d’entrée. Notez que l’ancien contenu du PO d’entrée n’est pas effacé.

=item writepo($)

Écrire le PO extrait dans le fichier dont le nom est passé en paramètre.

=item stats()

Renvoie des statistiques à propos de la traduction. Notez que ce ne sont pas
les statistiques affichées par msgfmt --statistic. Dans ce cas, il s’agit
des statistiques concernant l’utilisation récente du fichier PO, tandis que
msgfmt renseigne sur le statut du fichier PO. Il s’agit d’une encapsulation
autour de la fonction Locale::Po4a::Po::stats_get en utilisant le fichier PO
en entrée. Voici un exemple d’utilisation :

    [normal use of the po4a document...]

    ($percent,$hit,$queries) = $document->stats();
    print "We found translations for $percent\%  ($hit from $queries) of strings.\n";

=back

=head2 Manipuler les addenda

=over 4

=item addendum($)

Référez-vous à L<po4a(7)|po4a.7> pour en savoir plus sur ce que sont les
addendas et comment les équipes de traduction doivent les écrire. Pour
appliquer un addendum au document traduit, il suffit de fournir le nom du
fichier à cette fonction, et c’est S<fini  ;-)>

Cette fonction renvoie un entier non nul en cas d’erreur.

=back

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

=head2 Récupération de l’entrée, génération de la sortie

Quatre fonctions sont prévues pour obtenir l'entrée et retourner la
sortie. Elles sont très similaires aux fonctions shift/unshift et push/pop
de Perl.

 * Perl shift returns the first array item and drop it from the array.
 * Perl unshift prepends an item to the array as the first array item.
 * Perl pop returns the last array item and drop it from the array.
 * Perl push appends an item to the array as the last array item.

La première paire concerne l’entrée, et la seconde la sortie. Moyen
S<mnémotechnique :> en entrée, on veut récupérer la première ligne, ce que
shift S<permet ;> en sortie on veut ajouter le résultat à la fin, ce que
fait push.

=over 4

=item shiftline()

Cette fonction renvoie la première ligne à analyser et sa référence
correspondante (présentée sous forme de tableau) à partir du tableau
C<<@{$self->{TT}{doc_in}}>> et supprime ces 2 premiers éléments du
tableau. Ici, la référence est fournie par une chaîne
C<<$filename:$linenum>>.

=item unshiftline($$)

Remets la dernière ligne récupérée avec shiftline() au début du tableau C<<
{$self->{TT}{doc_in}} >>.

=item pushline($)

Ajoute une nouvelle ligne à la fin de C<< {$self->{TT}{doc_out}} >>.

=item popline()

Récupère (pop) la dernière ligne poussée à la fin de C<<
{$self->{TT}{doc_out}} >>.

=back

=head2 Marquage des chaînes à traduire

Une fonction est fournie pour gérer le texte qui doit être traduit.

=over 4

=item translate($$$)

Paramètres obligatoires :

=over 2

=item -

Une chaîne à traduire

=item -

La référence de cette chaîne (c.-à-d., sa position dans le fichier d’entrée)

=item -

le type de la chaîne (c.-à-d., la description textuelle de son rôle
S<structurel ;> utilisé dans S<Locale::Po4a::Po::gettextization() ;>
consultez également L<po4a(7)|po4a.7>, section B<Gettextisation : Comment ça
marche ?>).

=back

Cette fonction peut également prendre des paramètres supplémentaires. Ils
doivent être organisés sous forme de table de hachage. Par exemple :

  $self->translate("string","ref","type",
                   'wrap' => 1);

=over

=item B<wrap>

booléen indiquant si on peut considérer que les espaces des chaînes ne sont
pas importants. Dans ce cas, la fonction crée une forme canonique de la
chaîne avant de rechercher une traduction ou de l’extraire et ajoute des
retours à la ligne à la traduction.

=item B<wrapcol>

la colonne à laquelle nous devrions tronquer (par défaut : la valeur de B
<wrapcol> renseignée lors de la création du TransTractor ou 76).

La valeur négative sera soustraite de la valeur par défaut.

=item B<comment>

un commentaire additionnel à ajouter à l’entrée du PO.

=back

Actions :

=over 2

=item -

Pousse la chaîne, la référence et le type dans le PO de sortie.

=item -

Renvoie la traduction de la chaîne (trouvée dans po_in) de façon à ce que
l’analyseur (parser) puisse construire doc_out.

=item -

gère les jeux de caractères pour recoder les chaînes avant de les envoyer à
po_out et avant de renvoyer la traduction.

=back

=back

=head2 Fonctions diverses

=over 4

=item verbose()

Indique si le mode bavard a été activé lors de la création du Transtractor.

=item debug()

Indique si l’option de débogage a été fournie lors de la création du
Transtractor.

=item get_in_charset()

Cette fonction renvoie le jeu de caractères qui était fourni en tant que jeu
de caractères d'origine

=item get_out_charset()

Cette fonction renverra le jeu de caractères qui doit être utilisé dans le
document de sortie (souvent utile pour substituer le jeu de caractères qui a
été détecté dans le document d’entrée).

Il utilisera le jeu de caractères spécifié sur la ligne de commande. S’il
n’a pas été spécifié, il utilisera le jeu de caractère du fichier PO
d’entrée, et si ce fichier PO utilise la valeur par défaut S<« CHARSET »>,
et aucun encodage n’est réalisé.

=back

=head1 DIRECTIONS FUTURES

Une des imperfections du TransTractor actuel est qu’il ne peut pas gérer de
documents traduits contenant toutes les langues, comme les modèles debconf
ou les fichiers .desktop.

Pour répondre à ce problème, les seules modifications d’interface
nécessaires sont :

=over 2

=item -

utiliser une table de hachage pour po_in_name (une liste par langue)

=item -

ajouter un paramètre à traduire pour indiquer la langue cible

=item -

créer une fonction pushline_all, qui utiliserait pushline pour le contenu de
toutes ses langues, en utilisant map :

    $self->pushline_all({ "Description[".$langcode."]=".
                          $self->translate($line,$ref,$langcode)
                        });

=back

Nous verrons si c’est S<suffisant ;)>

=head1 AUTEURS

 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)
 Jordi Vilalta <jvprat@gmail.com>

=head1 TRADUCTION

 Martin Quinson (mquinson#debian.org)

