Provided by: po4a_0.33.3-1_all bug

NOM

       Locale::Po4a::TransTractor - Generic trans(lator ex)tractor.

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($)
           Ajouter un nouveau document d’entrée après ceux déjà ajoutés. Le
           paramètre est le nom du fichier à lire.

           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.

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

       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";

       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 retourne un entier non nul en cas d’erreur.

FONCTIONS INTERNES utiliser pour dériver un analyseur (parser)

       Récupération de lentrée, génération de la sortie

       Quatre fonctions sont fournies pour récupérer l’entrée et renvoyer la
       sortie. Elles sont très similaires aux couples shift/unshift et
       push/pop. La première paire concerne l’entrée, et la seconde la sortie.
       Moyen mnémotechnique : en entrée, on veut récupérer la première ligne,
       ce que shift permet ; en sortie on veut ajouter le résultat à la fin,
       ce que fait push.

       shiftline()
           Cette fonction renvoie le ligne suivante du document d’entrée qui
           est analysé, ainsi que sa référence (les deux étant placées dans un
           tableau).

       unshiftline($$)
           Récupère une ligne du document d’entrée, ainsi que sa référence.

       pushline($)
           Ajoute une nouvelle ligne dans le document de sortie.

       popline()
           Récupère (pop) la dernière ligne poussée dans le document de
           sortie.

       Marquage des chaînes à traduire

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

       translate($$$)
           Paramètres obligatoires :

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

           Action :

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