blib::man::TransTractor(3pm)

NOM
Po4a TransTractor - Trans(lator ex)tractor generic (traductor extractor).

DESCRIPCIO
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 traduiebles, extraient-les cap a un fitxer po, i reemplacant-les per la seva traduccio en el document de sortida

Mes formalment, agafa els segueents 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 traduiebles del document d'entrada ;

-   un document traduiet, amb la mateixa estructura que el de l'entrada, pero amb totes les cadenes traduiebles substituiedes per les traduccions del fitxer po passat a l'entrada.

Aqui hi ha una representacio grafica:

   Document d'entrada -\                          /---> Document de sortida
                         \                        /          (traduiet)
                          +--> 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 traduiebles. 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 traduiets, 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 construiet a la sortida
               $document->unshiftline($linia,$lref);

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

               #   - posem a la sortida el tag inicial (sense traduir) i la resta
               #     del paragraf (traduieda)
               $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 segueent seccio.

INTERFICIE PUBLICA 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 traduiet 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 segueents opcions (empaquetades en un hash):

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

    debug ($)
        Activa la depuracio.

  Manipulant fitxers de documentacio

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 traduiet 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 traduiet, 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 traduiebles
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 Gettextitzacio: 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",
            \t   '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 traduiets 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."]=".
            \t        $self->translate($linia,$ref,$codiidioma)
            \t        });

Ja veurem si es suficient ;)

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

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

POD ERRORS
Hey! The above document had some coding errors, which are explained below:

Around line 15:
    Non-ASCII character seen before =encoding in 'generic'. Assuming ISO8859-1