Provided by: po4a_0.41-1_all bug

NOM

       Locale::Po4a::TransTractor - Traducteur et extracteur generique

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.

       Cette classe est l'ancetre de tous les analyseurs po4a utilises pour
       lire un document, y chercher les chaines traduisibles, les extraire
       dans un fichier PO, et les remplacer par leur traduction dans le
       document genere.

       Plus formellement, elle prend les parametres d'entree suivants:

       - un document a traduire;

       - un fichier PO contenant les traductions a utiliser.

       En sortie, elle produit:

       - un autre fichier PO, resultat de l'extraction des chaines
         traduisibles du document en entree;

       - un document traduit, partageant la meme structure que celui en
         entree, mais dont toutes les chaines traduisibles ont ete remplacees
         par les traductions trouvees dans le fichier PO fourni en entree.

       Voici une representation graphique de tout cela:

         document entree --\                             /---> document sortie
                            \                           /       (traduit)
                             +-> parse() function -----+
                            /                           \
         PO entree --------/                             \---> PO sortie
                                                                (extrait)

FONCTIONS QUE VOTRE ANALYSEUR DOIT SURCHARGER

       parse()
           Il s'agit de la fonction principale ou tout le travail a lieu: la
           lecture des documents en entree, la generation des documents en
           sortie et l'extraction des chaines traduisibles. Tout ceci est
           assez simple avec les fonctions fournies et presentees dans la
           section FONCTIONS INTERNES ci-dessous. Veuillez aussi vous reporter
           a la section SYNOPSIS, qui presente un exemple.

           Cette fonction est appelee 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-meme.

       docheader()
           Cette fonction renvoie l'en-tete que nous devons ajouter au
           document produit, formate comme il faut pour qu'il soit un
           commentaire pour le langage cible. Reportez-vous a la section
           'Eduquer les d'eveloppeurs au probl`eme des traductions, dans po4a(7).

SYNOPSIS

       L'exemple suivant analyse une liste de paragraphes commencant par <<<p
       >>.> Pour simplifier, nous supposons que le document est bien formate,
       c'est-a-dire que la balise <p> est la seule presente et que cette
       balise se trouve au debut 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 premiere balise <p>.
                      # Remet la ligne actuelle dans le document d'entree,
                      #  et met le paragraphe dans la sortie
                      $self->unshiftline($line,$lref);

                      # Maintenant que le document est forme, il faut le traduire :
                      #   - Retirons les balises de tete
                      $paragraphe =~ s/^<p>//s;

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

                      next PARAGRAPHE;
                  } else {
                      # Ajout a 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'entree.
              return;
          }
        }

       Une fois que vous avez implemente la fonction parse, vous pouvez
       utiliser cette nouvelle classe en utilisant l'interface publique
       presentee 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 parametres doivent etre
           fournis sous forme de table de hachage. Voici les differentes
           actions possibles:

           a. lit tous les fichiers PO specifies dans po_in_name;

           b. lit tous les documents originaux specifies dans file_in_name;

           c. analyse le document;

           d. lit et applique tous les addenda specifies;

           e. ecrit le document traduit dans file_out_name (si specifie);

           f. ecrit le fichier PO extrait dans po_out_name (si specifie).

           PARAMETRES, en plus de ceux acceptes par new(), ainsi que leur
           type:

           file_in_name (@)
               Liste de noms de fichiers d'ou lire les documents en entree.

           file_in_charset ($)
               Le jeu de caracteres du document d'entree (s'il n'est pas
               specifie, il essayera de le detecter a partir du document).

           file_out_name ($)
               Nom de fichier ou ecrire le document en sortie.

           file_out_charset ($)
               Le jeu de caracteres du document de sortie (s'il n'est pas
               specifie, le jeu de caracteres du fichier PO sera utilise).

           po_in_name (@)
               Liste de noms de fichiers d'ou lire les fichiers PO d'entree
               (ceux contenant les traductions a utiliser pour la traduction
               du document).

           po_out_name ($)
               Nom de fichier ou ecrire le fichier PO de sortie (celui
               contenant les chaines extraites du document d'entree).

           addendum (@)
               Liste de noms de fichiers d'ou lire les addenda a appliquer.

           addendum-charset ($)
               Jeu de caracteres des addenda.

       new(%)
           Creer un nouveau document po4a. Options acceptees (sous forme de
           hachage):

           verbose ($)
               Regle le niveau de bavardage.

           debug ($)
               Regle le niveau de debogage.

   Manipuler les documents
       read($)
           Ajouter un nouveau document d'entree apres ceux deja ajoutes. Le
           parametre est le nom du fichier a lire.

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

       write($)
           Ecrire le document traduit dans le fichier dont le nom est passe en
           parametre.

   Manipuler les fichiers PO
       readpo($)
           Ajouter le contenu du fichier dont le nom est passe en parametre au
           PO d'entree. Notez que l'ancien contenu du PO d'entree n'est pas
           efface.

       writepo($)
           Ecrire le PO extrait dans le fichier dont le nom est passe en
           parametre.

       stats()
           Renvoie des statistiques a propos de la traduction. Veuillez noter
           que ce ne sont pas les statistiques affichees par msgfmt
           --statistic. Dans ce cas, il s'agit des statistiques concernant
           l'utilisation recente 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 entree. Voici un exemple d'utilisation:

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

               ($pourcent,$traduit,$total) = $document->stats();
               print "Des traductions ont ete trouvees pour $pourcent\%  ($traduit sur $total) des chaines.\n";

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

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

FONCTIONS INTERNES utilis'ees pour d'eriver un analyseur (parser)

   R'ecup'eration de l'entr'ee, g'en'eration de la sortie
       Quatre fonctions sont fournies pour recuperer l'entree et renvoyer la
       sortie. Elles sont tres similaires aux couples shift/unshift et
       push/pop. La premiere paire concerne l'entree, et la seconde la sortie.
       Moyen mnemotechnique: en entree, on veut recuperer la premiere ligne,
       ce que shift permet; en sortie on veut ajouter le resultat a la fin, ce
       que fait push.

       shiftline()
           Cette fonction renvoie le ligne suivante du document d'entree qui
           est analyse, ainsi que sa reference (les deux etant placees dans un
           tableau).

       unshiftline($$)
           Recupere une ligne du document d'entree, ainsi que sa reference.

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

       popline()
           Recupere (pop) la derniere ligne poussee dans le document de
           sortie.

   Marquage des cha^ines `a traduire
       Une fonction est fournie pour gerer le texte qui doit etre traduit.

       translate($$$)
           Parametres obligatoires:

           - la chaine a traduire;

           - la reference de cette chaine (c.-a-d., sa position dans le
             fichier d'entree);

           - le type de la chaine (c.-a-d., la description textuelle de son
             role structurel; utilise dans Locale::Po4a::Po::gettextization();
             consultez egalement po4a(7), section Gettextization: Comment ,ca
             marche?).

           Cette fonction peut egalement prendre des parametres
           supplementaires. Ils doivent etre organises sous forme de table de
           hachage. Par exemple:

             $self->translate("chaine","reference","type",
                              'wrap' => 1);

           wrap
               booleen indiquant si on peut considerer que les espaces des
               chaines ne sont pas importants. Dans ce cas, la fonction cree
               une forme canonique de la chaine avant de rechercher une
               traduction ou de l'extraire et ajoute des retours a la ligne a
               la traduction.

           wrapcol
               la colonne a laquelle les retours a la ligne doivent avoir lieu
               (76 par defaut).

           comment
               un commentaire additionnel a ajouter a l'entree du PO.

           Action:

           - pousse la chaine, la reference et le type dans le PO de sortie;

           - renvoie la traduction de la chaine (trouvee dans po_in) de facon
             a ce que l'analyseur (parser) puisse construire doc_out;

           - gere les jeux de caracteres pour recoder les chaines avant de les
             envoyer a po_out et avant de renvoyer la traduction.

   Fonctions diverses
       verbose()
           Indique si le mode bavard a ete active lors de la creation du
           Transtractor.

       debug()
           Indique si l'option de debogage a ete fournie lors de la creation
           du Transtractor.

       detected_charset($)
           Indique a TransTractor qu'un nouveau jeu de caracteres (premier
           parametre) a ete detecte dans le document d'entree. Il est en regle
           general lu dans l'en-tete du document. Seul le premier jeu de
           caracteres restera, qu'il soit fourni par les parametres de
           process() ou detecte dans le document.

       get_out_charset()
           Cette fonction renverra le jeu de caracteres qui doit etre utilise
           dans le document de sortie (souvent utile pour substituer le jeu de
           caracteres qui a ete detecte dans le document d'entree).

           Il utilisera le jeu de caracteres specifie sur la ligne de
           commande. S'il n'a pas ete specifie, il utilisera le jeu de
           caractere du fichier PO d'entree, et si ce fichier PO utilise la
           valeur par defaut <<CHARSET>>, et aucun encodage n'est realise.

       recode_skipped_text($)
           Cette fonction reencode le texte donne en parametre, du jeu de
           caracteres du document d'entree vers le jeu de caracteres du
           document de sortie. Ce n'est pas necessaire quand les chaines sont
           traduites (translate() reencode tout d'elle-meme), mais ca l'est
           lorsque vous sautez des chaines du document d'entree 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
       gerer de documents traduits contenant toutes les langues, comme les
       modeles debconf ou les fichiers .desktop.

       Pour repondre a ce probleme, les seules modifications d'interface
       necessaires sont:

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

       - ajouter un parametre a traduire pour indiquer la langue cible;

       - creer 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,$ref,$code_langue)
                                 });

       Nous verrons si c'est suffisant;)

AUTEURS

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