Provided by: po4a_0.41-1ubuntu1_all bug

NOM

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

DESCRIPCI'O

       L'objectiu del projecte po4a (PO per a tot) es facilitar la traduccio
       (i sobretot el manteniment de les traduccions) utilitzant les eines de
       gettext en arees on no eren d'esperar, com ara en la documentacio.

       Aquesta classe es l'antecessor de tots els analitzadors de po4a,
       utilitzats per analitzar documents buscant-ne les cadenes traduibles,
       extraient-les cap a un fitxer PO, i reemplacant-les per la seva
       traduccio en el document de sortida

       Mes formalment, agafa els seguents parametres com a entrada:

       - un document a traduir ;

       - un fitxer PO que conte les traduccions a utilitzar.

       Com a sortida, genera:

       - un altre fitxer PO, resultat de l'extraccio de les cadenes traduibles
         del document d'entrada ;

       - un document traduit, amb la mateixa estructura que el de l'entrada,
         pero amb totes les cadenes traduibles substituides per les
         traduccions del fitxer PO passat a l'entrada.

       Aqui hi ha una representacio grafica:

          Document d'entrada -\                          /---> Document de sortida
                                \                        /          (traduit)
                                 +--> funcio parse() --+
                                /                        \
          PO d'entrada --------/                          \---> PO de sortida
                                                                   (extret)

FUNCIONS QUE EL VOSTRE ANALITZADOR HA D'IMPLEMENTAR

       parse()
           Aqui es on es fa tota la feina: s'analitzen els documents
           d'entrada, es genera la sortida, i s'extreuen les cadenes
           traduibles. Es molt simple donades les funcions presentades a la
           seccio FUNCIONS INTERNES de mes avall. Consulteu tambe la SINOPSI,
           que en mostra un exemple.

           Aquesta funcio es crida des de la funcio process() de mes avall,
           pero si escolliu d'utilitzar la funcio new(), i afegir els
           continguts manualment al vostre document, haureu de cridar aquesta
           funcio manualment.

       docheader()
           Aquesta funcio retorna la capcalera que hauriem d'afegir als
           documents traduits, tractada adequadament perque sigui un comentari
           en el format desti.  Vegeu la seccio Educant els desenvolupadors
           sobre les traduccions, a po4a(7), per veure perque serveix.

SINOPSI

       The following example parses a list of paragraphs beginning with "<p>".
       For the sake of simplicity, we assume that the document is well
       formatted, i.e. that '<p>' tags are the only tags present, and that
       this tag is at the very beginning of each paragraph.

        sub parse {
          my $self = shift;

          PARAGRAF: while (1) {
              $my ($paragraf,$pararef)=("","","","");
              $my $primera=1;
              my ($linia,$lref)=$self->shiftline();
              while (defined($linia)) {
                  if ($linia =~ m/<p>/ && !$primera--; ) {
                      # No es la primera vegada que veiem <p>.
                      # Tornem a posar la linia actual a l'entrada,
                      #  i posem el paragraf construit a la sortida
                      $document->unshiftline($linia,$lref);

                      # Ara que el document esta construit, el traduim:
                      #   - Eliminem el tag del principi
                      $paragraf =~ s/^<p>//s;

                      #   - posem a la sortida el tag inicial (sense traduir) i la resta
                      #     del paragraf (traduida)
                      $document->pushline(  "<p>"
                                          . $document->translate($paragraf,$pararef)
                                          );

                      next PARAGRAF;
                  } else {
                      # L'afegim al paragraf
                      $paragraf .= $linia;
                      $pararef = $lref unless(length($pararef));
                  }

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

       Un cop hagueu implementat la vostra funcio parse, ja podeu utilitzar la
       vostra classe de documents, a traves de la interficie publica
       presentada a la seguent seccio.

INTERF'ICIE P'UBLICA per guions que utilitzin el vostre analitzador

   Constructor
       process(%)
           Aquesta funcio pot fer tot el que necessiteu fer amb un document
           po4a en una unica invocacio. Els seus parametres han d'estar
           empaquetats com a un hash. ACCIONS:

           a. Llegeix tots els fitxers PO especificats a po_in_name

           b. Llegeix tots els documents originals especificats a file_in_name

           c. Analitza el document

           d. Llegeix i aplica els annexes especificats

           e. Escriu el document traduit a file_out_name (si es dona)

           f. Escriu el fitxer PO extret a po_out_name (si es dona)

           PARAMETRES, a part dels acceptats per new() (amb el tipus esperat):

           file_in_name (@)
               Llista dels noms dels fitxers dels que s'ha de llegir el
               document d'entrada.

           file_in_charset ($)
               Joc de caracters utilitzat en el document d'entrada (si no
               s'especifica, s'intentara detectar del document d'entrada).

           file_out_name ($)
               Nom del fitxer on s'ha d'escriure el document de sortida.

           file_out_charset ($)
               Joc de caracters utilitzat en el document de sortida (si no
               s'especifica, s'utilitzara el joc de caracters del fitxer PO).

           po_in_name (@)
               Llistat dels noms dels fitxers dels que llegirem els PO
               d'entrada, que contindran la traduccio que s'utilitzara per
               traduir el document.

           po_out_name ($)
               Nom del fitxer on s'escriura el fitxer PO de sortida, que
               contindra les cadenes extretes del document d'entrada.

           addendum (@)
               List of filenames where we should read the addenda from.

           addendum_charset ($)
               Joc de caracters dels annexes.

       new(%)
           Crea un nou document de po4a. Accepta les seguents opcions
           (empaquetades en un hash):

           verbose ($)
               Ajusta el nivell d'informacio extra.

           debug ($)
               Activa la depuracio.

   Manipulant fitxers de documentaci'o
       read($)
           Afegeix un altre document d'entrada al final de l'actual. El
           parametre es el nom del fitxer a llegir.

           Tingueu en compte que aixo no analitza res. Haureu de cridar la
           funcio parse() quan hagueu acabat d'empaquetar els fitxers
           d'entrada en el document.

       write($)
           Escriu el document traduit al fitxer amb el nom donat.

   Manupulant fitxers PO
       readpo($)
           Afegeix el contingut d'un fitxer (el nom del qual s'ha de passar
           com a parametre) al PO d'entrada actual. No es descarta el
           contingut anterior.

       writepo($)
           Escriu el fitxer PO extret al fitxer amb el nom donat.

       stats()
           Retorna algunes estadistiques de la traduccio feta fins al moment.
           Tingueu en compte que no son les mateixes estadistiques que mostra
           msgfmt --statistic. Aquestes son estadistiques sobre l'us recent
           del fitxer PO, mentre que msgfmt mostra l'estat del fitxer.
           Simplement crida la funcio Locale::Po4a::Po::stats_get sobre el
           fitxer PO d'entrada. Exemple d'us:

               [us normal del document po4a...]

               ($percentatge,$encerts,$peticions) = $document->stats();
               print "S'han trobat traduccions per al $percentatge\%  ($encerts de $peticions) de cadenes.\n";

   Manipulant annexes
       addendum($)
           Consulteu po4a(7) per mes informacio sobre que son els annexes, i
           com els han d'escriure els traductors. Per tal d'aplicar un annex
           al document traduit, simplement passeu el nom del fitxer a aquesta
           funcio i ja esta ;)

           Aquesta funcio retorna un enter no nul en cas d'error.

FUNCIONS INTERNES utilitzades per escriure analitzadors derivats

   Obtenint entrada, proporcionant sortida
       Es proporcionen quatre funcions per obtenir l'entrada i retornar la
       sortida. Son molt similars a shift/unshift i push/pop. El primer parell
       es sobre l'entrada, mentre que el segon es sobre la sortida.
       Comparacio: a l'entrada, estem interessats en la primera linia, el que
       dona shift, mentre que a la sortida volem afegir el resultat al final,
       tal com fa push.

       shiftline()
           Aquesta funcio retorna la propera linia a analitzar de doc_in i la
           seva referencia (empaquetat com a vector).

       unshiftline($$)
           Torna una linia i la seva referencia al document d'entrada.

       pushline($)
           Injecta una nova linia a doc_out.

       popline()
           Extreu la darrera linia injectada a doc_out.

   Marcant cadenes com a tradu"ibles
       Es proporciona una funcio per tractar el text que s'ha de traduir.

       translate($$$)
           Parametres obligatoris:

           - La cadena a traduir

           - La cadena de referencia (es a dir, la posicio al fitxer
             d'entrada)

           - El tipus de la cadena (es a dir, la descripcio textual del seu
             significat estructural ; s'utilitza a
             Locale::Po4a::Po::gettextization() ; consulteu tambe la seccio
             Gettextitzaci'o: com funciona? de po4a(7))

           Aquesta funcio tambe pot rebre alguns parametres extra. Aquests han
           d'estar agrupats en un hash. Per exemple:

             $self->translate("cadena","ref","tipus",
                              'wrap' => 1);

           wrap
               boolea que indica si podem considerar que els espais de la
               cadena no son importants. Si te valor cert, la funcio
               canonitzara la cadena abans de buscar-ne la traduccio o
               d'extreure-la, i en justificara la traduccio.

           wrapcol
               La columna a la que s'ha de justificar (per defecte: 76).

           comment
               Un comentari extra per afegir a l'entrada.

           Accions:

           - Insereix la cadena, la referencia i el tipus a po_out.

           - Retorna la traduccio de la cadena (trobada a po_in) per tal que
             l'analitzador pugui construir el doc_out.

           - Tracta els jocs de caracters per recodificar les cadenes abans
             d'enviar-les a po_out i abans de retornar les traduccions.

   Funcions diverses
       verbose()
           Retorna el nivell d'informacio extra que es va passar durant la
           creacio del TransTractor.

       debug()
           Retorna si s'ha passat l'opcio de depuracio durant la creacio del
           TransTractor.

       detected_charset($)
           Aixo informa al TransTractor que s'ha detectat un nou joc de
           caracters (el primer parametre) del document d'entrada.
           Habitualment es pot trobar a la capcalera dels documents. Tan sols
           es mantindra el primer joc de caracters trobat, ja sigui un
           parametre de process() o be sigui detectat del document.

       get_out_charset()
           Aquesta funcio retorna el joc de caracters que s'ha d'utilitzar en
           el document de sortida (habitualment es util per substituir el joc
           de caracters del document d'entrada en el lloc on s'ha trobat).

           Utilitzara el joc de caracters especificat a la linia de comandes.
           Si no s'ha especificat, utilitzara el joc de caracters del PO
           d'entrada, i si el PO d'entrada conte el valor per defecte
           "CHARSET", retornara el joc de caracters del document d'entrada, de
           forma que no es realitzi recodificacio.

       recode_skipped_text($)
           Aquesta funcio retorna el text passat com a parametre recodificat,
           des del joc de caracters del document d'entrada cap al del document
           de sortida. Aixo no es necessari quan es tradueix una cadena (la
           funcio translate() ja recodifica les traduccions), pero es
           important quan se salta una cadena del document d'entrada i es vol
           conservar la consistencia en la codificacio global del document de
           sortida.

DIRECCIONS FUTURES

       Una deficiencia del TransTractor actual es que no pot tractar documents
       traduits que continguin tots els idiomes, com ara les plantilles de
       debconf, o els fitxers .desktop.

       Per resoldre aquest problema, els unics canvis necessaris a la
       interficie son:

       - take a hash as po_in_name (a list per language)

       - afegir un parametre a translate per indicar l'idioma desti

       - fer una funcio pushline_all, que podria fer un pushline del seu
         contingut per tots els idiomes, utilitzant una sintaxi semblant a la
         de map:

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

       Ja veurem si es suficient ;)

AUTORS

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