Provided by: po4a_0.41-1_all bug

NOM

       Locale::Po4a::Po - modul per a la manipulacio de fitxers PO

SINOPSI

           use Locale::Po4a::Po;
           my $fitxerpo=Locale::Po4a::Po->new();

           # Llegim el fitxer PO
           $fitxerpo->load('fitxer.po');

           # Afegim una entrada
           $pofile->push('msgid' => 'Hello', 'msgstr' => 'Hola',
                           'flags' => "wrap", 'reference'=>'fitxer.c:46');

           # Extraiem una traduccio
           $fitxerpo->gettext("Hello"); # retorna 'Hola'

           # Escrivim el nou fitxer po
           $fitxerpo->write('unaltrefitxer.po');

DESCRIPCI'O

       Locale::Po4a::Po es un modul que permet manipular catalegs de
       missatges. Podeu carregar i escriure des de/a un fitxer (l'extensio del
       qual es habitualment po, podeu crear noves entrades sobre la marxa i
       demanar la traduccio de cadenes.

       Per una descripcio mes completa dels catalegs de missatges en el format
       PO i el seu us, consulteu la documentacio del programa gettext.

       Aquest modul es part del projecte PO4A, que te per objectiu utilitzar
       fitxers PO (dissenyats originalment per facilitar la traduccio de
       missatges de programa) per traduir de tot, incloent documentacio
       (pagines de manual, manuals d'info), descripcions de paquets,
       plantilles de debconf, i qualsevol altra cosa que se'n pugui
       beneficiar.

OPCIONS QUE ACCEPTA AQUEST M`ODUL

       porefs
           This specifies the reference format. It can be one of none to not
           produce any reference, noline to not specify the line number, and
           full to include complete references.

Funcions sobre el cat`aleg de missatges sencer

       new()
           Crea un nou cataleg de missatges. Si se li passa un parametre, sera
           el nom del fitxer PO que ha de carregar.

       read($)
           Llegeix un fitxer PO (el nom del qual es passa com a parametre).
           Les entrades que ja existien al cataleg actual no s'eliminen, les
           noves s'afegeixen al final del cataleg.

       write($)
           Escriu el cataleg actual al fitxer donat.

       write_if_needed($$)
           Like write, but if the PO or POT file already exists, the object
           will be written in a temporary file which will be compared with the
           existing file to check that the update is needed (this avoids to
           change a POT just to update a line reference or the POT-Creation-
           Date field).

       gettextize($$)
           Aquesta funcio produeix un cataleg de missatges traduit a partir de
           dos catalegs, l'original i la traduccio. Aquest proces es descriu a
           la seccio Gettextitzaci'o: com funciona? de po4a(7).

       filter($)
           Aquesta funcio extreu un cataleg a partir de l'actual. Nomes desara
           al cataleg resultant les entrades que tinguin una referencia al
           fitxer donat.

           Aquesta funcio analitza els seu parametre, el converteix a una
           definicio de funcio de Perl, avalua aquesta definicio i filtra els
           camps pels que aquesta funcio retorna cert.

           M'encanta Perl a vegades ;)

       to_utf8()
           Recodifica a UTF-8 els msgstrs del PO. No fa res si el joc de
           caracters no esta especificat en el fitxer PO (el valor "CHARSET"),
           o si ja esta en UTF-8 o ASCII.

Funcions per utilitzar el cat`aleg de missatges per les traduccions

       gettext($%)
           Retorna la traduccio de la cadena donada com a parametre al cataleg
           actual.  La funcio retorna l'original (sense traduir) si no troba
           la cadena.

           Despres de la cadena a traduir, podeu passar un hash de parametres
           extra. Aquestes son les entrades valides:

           wrap
               boolea que indica si podem considerar que els espais de la
               cadena no son importants. En cas afirmatiu, la funcio canonitza
               la cadena abans de buscar-ne la traduccio, i justifica el
               resultat.

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

       stats_get()
           Retorna les estadistiques sobre la quantitat d'encerts de gettext
           des de la darrera vegada que s'ha cridat stats_clear(). Tingueu en
           compte que no son les mateixes estadistiques que mostra msgfmt
           --statistic. Aquestes son sobre l'us recent del fitxer PO, mentre
           que msgfmt informa sobre l'estat del fitxer.  Exemple d'us:

               [us del fitxer PO per traduir coses]

               ($percentatge,$encerts,$peticions) = $fitxerpo->stats_get();
               print "Fins ara, s'han trobat traduccions per al $percentatge\%  ($encerts de $peticions) de les cadenes.\n";

       stats_clear()
           Neteja les estadistiques sobre els encerts de gettext.

Funcions per construir un cat`aleg de missatges

       push(%)
           Insereix una nova entrada al final del cataleg actual. Els
           parametres han de formar una taula de hash. Les claus valides son :

           msgid
               la cadena en l'idioma original.

           msgstr
               la traduccio.

           reference
               una indicacio d'on s'ha trobat la cadena. Exemple: fitxer.c:46
               (significa a la linia 46 del 'fitxer.c'). Pot ser una llista
               separada per espais en cas de multiples ocurrencies.

           comment
               un comentari afegir manualment (pels traductors). El format es
               lliure.

           automatic
               un comentari que ha afegit automaticament el programa
               d'extraccio de cadenes. Vegeu l'opcio --add-comments del
               programa xgettext per a mes informacio.

           flags
               llista separada per espais dels flags definits per aquesta
               entrada.

               Els flags valids son: c-text, python-text, lisp-text, elisp-
               text, librep-text, smalltalk-text, java-text, awk-text, object-
               pascal-text, ycp-text, tcl-text, wrap, no-wrap i fuzzy.

               Vegeu la documentacio de gettext pels seus significats.

           type
               Aquest es mes aviat un parametre intern: s'utilitza a l'hora de
               gettextitzar documents. La idea es analitzar el document
               original i la traduccio a objectes PO, i ajuntar-los,
               utilitzant els msgid d'un com a msgid, i els msgid de l'altre
               com a msgstr. Per assegurar que les coses van be, es dona un
               tipus a cada msgid dels objectes po, segons la seva estructura
               (com ara "chapt", "sect1", "p" i aixi a DocBook). Si els tipus
               de les cadenes no coincideixen, significa que ambdos documents
               no comparteixen la mateixa estructura, i el proces acaba amb un
               error.

               Aquesta informacio s'escriu com a comentari automatic al fitxer
               PO ja que dona informacio de context sobre les cadenes a
               traduir als traductors.

           wrap
               boolea que indica si els espais en blanc es poden tractar en
               reformatejats cosmetics. En cas afirmatiu, abans d'utilitzar la
               cadena, aquesta es canonitzada.

               Aquesta informacio s'escriu al fitxer PO utilitzant el flag
               wrap o no-wrap.

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

               Aquesta informacio no s'escriu al fitxer PO.

Funcions diverses

       count_entries()
           Retorna el nombre d'entrades del cataleg (sense la capcalera).

       count_entries_doc()
           Returns the number of entries in document. If a string appears
           multiple times in the document, it will be counted multiple times

       msgid($)
           Retorna el msgid del nombre donat.

       msgid_doc($)
           Returns the msgid with the given position in the document.

       get_charset()
           Retorna el joc de caracters especificat a la capcalera PO. Si
           encara no s'ha ajustat, retornara "CHARSET".

       set_charset($)
           Defineix el joc de caracters de la capcalera PO al valor
           especificat com a primer parametre. Si no crideu mai aquesta funcio
           (i no es llegeix cap fitxer amb un joc de caracters especificat),
           el valor per defecte es deixa a "CHARSET". Aquest valor no canvia
           el comportament d'aquest modul, nomes s'utilitza per omplir el camp
           de la capcalera, i es retorna a get_charset().

AUTORS

        Denis Barbier <barbier@linuxfr.org>
        Martin Quinson (mquinson#debian.org)