Provided by: po4a_0.55-1_all bug

NOM

       Locale::Po4a::TransTractor - Traducteur et extracteur générique.

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 :

       - un document à traduire ;

       - un fichier PO contenant les traductions à utiliser.

       En sortie, elle produit :

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

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

       Voici une représentation graphique de tout cela :

          document entrée --\                             /---> document sortie
                            \                           /       (traduit)
                             +-> parse() function -----+
                            /                           \
         PO entrée --------/                             \---> PO sortie
                                                                (extrait)

FONCTIONS QUE VOTRE ANALYSEUR DOIT SURCHARGER

       parse()
           Il s’agit de la fonction principale où tout le travail a 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 FONCTIONS INTERNES ci-dessous. Veuillez aussi vous reporter à la
           section 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.

       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. Reportez-vous à la
           section Éduquer les développeurs au problème des traductions, dans po4a(7).

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;

          PARAGRAPHE: while (1) {
              my ($paragraphe,$pararef)=("","");
              my $premier=1;
              ($ligne,$lref)=$self->shiftline();
              while (defined($ligne)) {
                  if ($ligne =~ m/<p>/ && !$premier--; ) {
                      # Ce n’est pas la première balise <p>.
                      # Remet la ligne actuelle dans le document d’entrée,
                      #  et met le paragraphe dans la sortie
                      $self->unshiftline($line,$lref);

                      # Maintenant que le document est formé, il faut le traduire :
                      #   - Retirons les balises de tête
                      $paragraphe =~ s/^<p>//s;

                      #   - Poussons la balise de tête (à ne pas traduire) et le
                      #     reste du paragraphe (à traduire) dans le document de
                      #     sortie
                      $self->pushline(  "<p>"
                                      . $document->translate($paragraphe,$pararef)
                                      );

                      next PARAGRAPHE;
                  } else {
                      # Ajout à la fin du paragraphe
                      $paragraphe .= $ligne;
                      $pararef = $lref unless(length($pararef));
                  }

                  # Re-initialise la boucle
                  ($ligne,$lref)=$self->shiftline();
              }
              # Aucune nouvelle ligne ? C’est la fin du fichier d’entrée.
              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.

INTERFACE PUBLIQUE pour les scripts utilisant votre analyseur

   Constructeur
       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 :

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

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

           c. Analyse le document

           d. Lit et applique tous les addenda spécifiés

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

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

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

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

           file_in_charset ($)
               Le jeu de caractères du document d’entrée (s’il n’est pas spécifié, il essayera de
               le détecter à partir du document).

           file_out_name ($)
               Nom de fichier où écrire le document en sortie.

           file_out_charset ($)
               Le jeu de caractères du document de sortie (s’il n’est pas spécifié, le jeu de
               caractères du fichier PO sera utilisé).

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

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

           addendum (@)
               Liste de noms de fichiers d’où lire les addenda à appliquer.

           addendum-charset ($)
               Jeu de caractères des addenda.

       new(%)
           Créer un nouveau document po4a. Options acceptées (sous forme de hachage) :

           verbose ($)
               Règle le niveau de bavardage.

           debug ($)
               Règle le niveau de débogage.

   Manipuler les documents
       read($)
           Add another input document data at the end of the existing array
           "@{$self->{TT}{doc_in}}". The argument is the filename to read.

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

           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.

           Please note $linenum starts with 1.

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

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

   Manipuler les fichiers PO
       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é.

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

       stats()
           Renvoie des statistiques à propos de la traduction. Veuillez noter 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 :

               [utilisation normal d’un document po4a...]

               ($pourcent,$traduit,$total) = $document->stats();
               print "Des traductions ont été trouvées pour $pourcent\%  ($traduit sur $total) des chaînes.\n";

       is_po_uptodate()
           Retours ($uptodate, $diagnostic) où $uptodate est si le po d’entrée et celui de sortie
           correspondent (sinon, cela signifie que le po d’entrée devrait être mis à jour) et
           $diagnostic est une chaîne expliquant pourquoi le fichier po n’est pas à jour, le cas
           échéant.

   Manipuler les addenda
       addendum($)
           Veuillez vous reporter à po4a(7)  pour plus d’informations sur ce que sont les addenda
           et comment les traducteurs doivent les écrire. Pour appliquer un addendum au document
           traduit, vous n’avez qu’à fournir le nom du fichier à cette fonction, et c’est fini ;)

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

INTERNAL FUNCTIONS used to write derivative parsers

   Récupération de l’entrée, génération de la sortie
       Four functions are provided to get input and return output. They are very similar to
       shift/unshift and push/pop of 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.

       The first pair is about input, while the second is about output. Mnemonic: in input, you
       are interested in the first line, what shift gives, and in output you want to add your
       result at the end, like push does.

       shiftline()
           This function returns the first line to be parsed and its corresponding reference
           (packed as an array) from the array "@{$self->{TT}{doc_in}}" and drop these first 2
           array items. Here, the reference is provided by a string "$filename:$linenum".

       unshiftline($$)
           Unshifts the last shifted line of the input document and its corresponding reference
           back to the head of "{$self->{TT}{doc_in}}".

       pushline($)
           Push a new line to the end of "{$self->{TT}{doc_out}}".

       popline()
           Pop the last pushed line from the end of "{$self->{TT}{doc_out}}".

   Marquage des chaînes à traduire
       Une fonction est fournie pour gérer le texte qui doit être traduit.

       translate($$$)
           Paramètres obligatoires :

           - Une chaîne à traduire

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

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

           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("chaîne","référence","type",
                              'wrap' => 1);

           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.

           wrapcol
               la colonne à laquelle les retours à la ligne doivent avoir lieu (76 par défaut).

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

           Actions :

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

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

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

   Fonctions diverses
       verbose()
           Indique si le mode bavard a été activé lors de la création du Transtractor.

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

       detected_charset($)
           Indique à TransTractor qu’un nouveau jeu de caractères (premier paramètre) a été
           détecté dans le document d’entrée. Il est en règle général lu dans l’en-tête du
           document. Seul le premier jeu de caractères restera, qu’il soit fourni par les
           paramètres de process() ou détecté dans le document.

       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 « CHARSET », et aucun encodage n’est réalisé.

       recode_skipped_text($)
           Cette fonction réencode le texte donné en paramètre, du jeu de caractères du document
           d’entrée vers le jeu de caractères du document de sortie. Ce n’est pas nécessaire
           quand les chaînes sont traduites (translate() réencode tout d’elle-même), mais ça
           l’est lorsque vous sautez des chaînes du document d’entrée et que vous voulez que le
           document de sortie utilise un encodage uniforme.

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 :

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

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

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

             $self->pushline_all({ "Description[".$code_langue."]=".
                                   $self->translate($ligne,$réf,$code_langue)
                                 });

       Nous verrons si c’est suffisant ;)

AUTEURS

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

TRADUCTION

        Martin Quinson (mquinson#debian.org)