Provided by: po4a_0.32-1_all bug

NOM

       Po4a TransTractor - Trans(lator ex)tractor genèric (traductor
       extractor).

DESCRIPCIÓ

       L’objectiu del projecte po4a (po per a tot) és facilitar la traducció
       (i sobretot el manteniment de les traduccions) utilitzant les eines de
       gettext en àrees on no eren d’esperar, com ara en la documentació.

       Aquesta classe és l’antecessor de tots els analitzadors de po4a,
       utilitzats per analitzar documents buscant-ne les cadenes traduïbles,
       extraient-les cap a un fitxer po, i reemplaçant-les per la seva
       traducció en el document de sortida

       Més formalment, agafa els següents paràmetres com a entrada:

       - un document a traduir ;

       - un fitxer po que conté les traduccions a utilitzar.

       Com a sortida, genera:

       - un altre fitxer po, resultat de l’extracció de les cadenes traduïbles
         del document d’entrada ;

       - un document traduït, amb la mateixa estructura que el de l’entrada,
         però amb totes les cadenes traduïbles substituïdes per les
         traduccions del fitxer po passat a l’entrada.

       Aquí hi ha una representació gràfica:

          Document d’entrada -\                          /---> Document de sortida
                                \                        /          (traduït)
                                 +--> funció parse() --+
                                /                        \
          po d’entrada --------/                          \---> po de sortida
                                                                   (extret)

FUNCIONS QUE EL VOSTRE ANALITZADOR HA DIMPLEMENTAR
       parse()
           Aquí és on es fa tota la feina: s’analitzen els documents
           d’entrada, es genera la sortida, i s’extreuen les cadenes
           traduïbles. És molt simple donades les funcions presentades a la
           secció "FUNCIONS INTERNES" de més avall. Consulteu també la
           sinopsi, que en mostra un exemple.

           Aquesta funció es crida des de la funció process() de més avall,
           però si escolliu d’utilitzar la funció new(), i afegir els
           continguts manualment al vostre document, haureu de cridar aquesta
           funció manualment.

       docheader()
           Aquesta funció retorna la capçalera que hauriem d’afegir als
           documents traduïts, tractada adequadament perquè sigui un comentari
           en el format destí.  Vegeu la secció "Educant els desenvolupadors
           sobre les traduccions", a po4a(7), per veure perquè 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 és la primera vegada que veiem <p>.
                      # Tornem a posar la línia actual a l’entrada,
                      #  i posem el paràgraf construït a la sortida
                      $document->unshiftline($linia,$lref);

                      # Ara que el document està construït, el traduïm:
                      #   - Eliminem el tag del principi
                      $paragraf =~ s/^<p>//s;

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

                      next PARAGRAF;
                  } else {
                      # L’afegim al paràgraf
                      $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 funció parse, ja podeu utilitzar la
       vostra classe de documents, a través de la interfície pública
       presentada a la següent secció.

INTERFÍCIE PÚBLICA per guions que utilitzin el vostre analitzador

       Constructor

       process(%)
           Aquesta funció pot fer tot el que necessiteu fer amb un document
           po4a en una única invocació. Els seus paràmetres 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 traduït a file_out_name (si es dóna)

           f. Escriu el fitxer po extret a po_out_name (si es dóna)

           PARÀMETRES, 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 caràcters utilitzat en el document d’entrada (si no
               s’especifica, s’intentarà 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 caràcters utilitzat en el document de sortida (si no
               s’especifica, s’utilitzarà el joc de caràcters del fitxer po).

           po_in_name (@)
               Llistat dels noms dels fitxers dels que llegirem els po
               d’entrada, que contindran la traducció que s’utilitzarà per
               traduir el document.

           po_out_name ($)
               Nom del fitxer on s’escriurà el fitxer po de sortida, que
               contindrà les cadenes extretes del document d’entrada.

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

           addendum_charset ($)
               Joc de caràcters dels annexes.

       new(%)
           Crea un nou document de Po4a. Accepta les següents opcions
           (empaquetades en un hash):

           verbose ($)
               Ajusta el nivell d’informació extra.

           debug ($)
               Activa la depuració.

       Manipulant fitxers de documentació

       read($)
           Afegeix un altre document d’entrada al final de l’actual. El
           paràmetre és el nom del fitxer a llegir.

           Tingueu en compte que això no analitza res. Haureu de cridar la
           funció parse() quan hagueu acabat d’empaquetar els fitxers
           d’entrada en el document.

       write($)
           Escriu el document traduït 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 paràmetre) 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 estadístiques de la traducció feta fins al moment.
           Tingueu en compte que no són les mateixes estadístiques que mostra
           msgfmt --statistic. Aquestes són estadístiques sobre l’ús recent
           del fitxer po, mentre que msgfmt mostra l’estat del fitxer.
           Simplement crida la funció Locale::Po4a::Po::stats_get sobre el
           fitxer po d’entrada. Exemple d’ús:

               [ús 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 més informació sobre què són els annexes, i
           com els han d’escriure els traductors. Per tal d’aplicar un annex
           al document traduït, simplement passeu el nom del fitxer a aquesta
           funció i ja està ;)

           Aquesta funció 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. Són molt similars a shift/unshift i push/pop. El primer parell
       és sobre l’entrada, mentre que el segon és sobre la sortida.
       Comparació: a l’entrada, estem interessats en la primera línia, el què
       dóna shift, mentre que a la sortida volem afegir el resultat al final,
       tal com fa push.

       shiftline()
           Aquesta funció retorna la propera línia a analitzar de doc_in i la
           seva referència (empaquetat com a vector).

       unshiftline($$)
           Torna una línia i la seva referència al document d’entrada.

       pushline($)
           Injecta una nova línia a doc_out.

       popline()
           Extreu la darrera línia injectada a doc_out.

       Marcant cadenes com a traduïbles

       Es proporciona una funció per tractar el text que s’ha de traduir.

       translate($$$)
           Paràmetres obligatoris:

           - La cadena a traduir

           - La cadena de referència (és a dir, la posició al fitxer
             d’entrada)

           - El tipus de la cadena (és a dir, la descripció textual del seu
             significat estructural ; s’utilitza a
             Locale::Po4a::Po::gettextization() ; consulteu també la secció
             Gettextitzaci: com funciona? de po4a(7))

           Aquesta funció també pot rebre alguns paràmetres extra. Aquests han
           d’estar agrupats en un hash. Per exemple:

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

           wrap
               booleà que indica si podem considerar que els espais de la
               cadena no són importants. Si té valor cert, la funció
               canonitzarà la cadena abans de buscar-ne la traducció o
               d’extreure-la, i en justificarà la traducció.

           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 referència i el tipus a po_out.

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

           - Tracta els jocs de caràcters per recodificar les cadenes abans
             d’enviar-les a po_out i abans de retornar les traduccions.

       Funcions diverses

       verbose()
           Retorna el nivell d’informació extra que es va passar durant la
           creació del TransTractor.

       debug()
           Retorna si s’ha passat l’opció de depuració durant la creació del
           TransTractor.

       detected_charset($)
           Això informa al TransTractor que s’ha detectat un nou joc de
           caracters (el primer paràmetre) del document d’entrada.
           Habitualment es pot trobar a la capçalera dels documents. Tan sols
           es mantindrà el primer joc de caracters trobat, ja sigui un
           paràmetre de process() o bé sigui detectat del document.

       get_out_charset()
           Aquesta funció retorna el joc de caràcters que s’ha d’utilitzar en
           el document de sortida (habitualment és útil per substituir el joc
           de caràcters del document d’entrada en el lloc on s’ha trobat).

           Utilitzarà el joc de caràcters especificat a la línia de comandes.
           Si no s’ha especificat, utilitzarà el joc de caràcters del po
           d’entrada, i si el po d’entrada conté el valor per defecte
           "CHARSET", retornarà el joc de caràcters del document d’entrada, de
           forma que no es realitzi recodificació.

       recode_skipped_text($)
           Aquesta funció retorna el text passat com a paràmetre recodificat,
           des del joc de caràcters del document d’entrada cap al del document
           de sortida. Això no és necessari quan es tradueix una cadena (la
           funció translate() ja recodifica les traduccions), però és
           important quan se salta una cadena del document d’entrada i es vol
           conservar la consistència en la codificació global del document de
           sortida.

DIRECCIONS FUTURES

       Una deficiència del TransTractor actual és que no pot tractar documents
       traduïts que continguin tots els idiomes, com ara les plantilles de
       debconf, o els fitxers .desktop.

       Per resoldre aquest problema, els únics canvis necessaris a la
       interfície són:

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

       - afegir un paràmetre a translate per indicar l’idioma destí

       - fer una funció 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 és suficient ;)

AUTORS

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

TRADUCCIÓ

        Carme Cirera <menxu@hotmail.com>
        Jordi Vilalta <jvprat@gmail.com>