NOM¶
Locale::Po4a::Po - mòdul per a la manipulació 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 traducció
$fitxerpo->gettext("Hello"); # retorna 'Hola'
# Escrivim el nou fitxer po
$fitxerpo->write('unaltrefitxer.po');
DESCRIPCIÓ¶
Locale::Po4a::Po és un mòdul que permet manipular catàlegs de
missatges. Podeu carregar i escriure des de/a un fitxer (l'extensió del
qual és habitualment
po, podeu crear noves entrades sobre la marxa
i demanar la traducció de cadenes.
Per una descripció més completa dels catàlegs de missatges en el
format PO i el seu ús, consulteu la documentació del programa
gettext.
Aquest mòdul és part del projecte po4a, que té per objectiu
utilitzar fitxers PO (dissenyats originalment per facilitar la traducció
de missatges de programa) per traduir de tot, incloent documentació
(pàgines 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ÒDUL¶
- 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àleg de missatges sencer¶
- new()
- Crea un nou catàleg de missatges. Si se li passa un
paràmetre, serà el nom del fitxer PO que ha de carregar.
- read($)
- Llegeix un fitxer PO (el nom del qual es passa com a
paràmetre). Les entrades que ja existien al catàleg actual no
s'eliminen, les noves s'afegeixen al final del catàleg.
- write($)
- Escriu el catàleg 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 if the update is needed (this avoids to change a
POT just to update a line reference or the POT-Creation-Date field).
- gettextize($$)
- Aquesta funció produeix un catàleg de missatges
traduït a partir de dos catàlegs, l'original i la
traducció. Aquest procés es descriu a la secció
Gettextització: com funciona? de po4a(7).
- filter($)
- Aquesta funció extreu un catàleg a partir de
l'actual. Només desarà al catàleg resultant les entrades
que tinguin una referència al fitxer donat.
Aquesta funció analitza els seu paràmetre, el converteix a una
definició de funció de Perl, avalua aquesta definició i
filtra els camps pels que aquesta funció 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 està especificat en el fitxer PO (el valor
"CHARSET"), o si ja està en UTF-8 o ASCII.
Funcions per utilitzar el catàleg de missatges per les
traduccions¶
- gettext($%)
- Retorna la traducció de la cadena donada com a
paràmetre al catàleg actual. La funció retorna l'original
(sense traduir) si no troba la cadena.
Després de la cadena a traduir, podeu passar un hash de paràmetres
extra. Aquestes són les entrades vàlides:
- wrap
- booleà que indica si podem considerar que els espais
de la cadena no són importants. En cas afirmatiu, la funció
canonitza la cadena abans de buscar-ne la traducció, i justifica el
resultat.
- wrapcol
- La columna a la que s'ha de justificar (per defecte:
76).
- stats_get()
- Retorna les estadístiques sobre la quantitat d'encerts
de gettext des de la darrera vegada que s'ha cridat stats_clear().
Tingueu en compte que no són les mateixes estadístiques que
mostra msgfmt --statistic. Aquestes són sobre l'ús recent del
fitxer PO, mentre que msgfmt informa sobre l'estat del fitxer. Exemple
d'ús:
[ús 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 estadístiques sobre els encerts de
gettext.
Funcions per construir un catàleg de missatges¶
- push(%)
- Insereix una nova entrada al final del catàleg actual.
Els paràmetres han de formar una taula de hash. Les claus
vàlides són :
- msgid
- la cadena en l'idioma original.
- msgstr
- la traducció.
- reference
- una indicació d'on s'ha trobat la cadena. Exemple:
fitxer.c:46 (significa a la línia 46 del 'fitxer.c'). Pot ser una
llista separada per espais en cas de múltiples ocurrències.
- comment
- un comentari afegir manualment (pels traductors). El format
és lliure.
- automatic
- un comentari que ha afegit automàticament el programa
d'extracció de cadenes. Vegeu l'opció --add-comments del
programa xgettext per a més informació.
- flags
- llista separada per espais dels flags definits per aquesta
entrada.
Els flags vàlids són: 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 documentació de gettext pels seus significats.
- type
- Aquest és més aviat un paràmetre intern:
s'utilitza a l'hora de gettextitzar documents. La idea és analitzar
el document original i la traducció 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 bé, es dóna un tipus a
cada msgid dels objectes po, segons la seva estructura (com ara
"chapt", "sect1", "p" i així a
DocBook). Si els tipus de les cadenes no coincideixen, significa que
ambdós documents no comparteixen la mateixa estructura, i el
procés acaba amb un error.
Aquesta informació s'escriu com a comentari automàtic al fitxer PO
ja que dóna informació de context sobre les cadenes a traduir
als traductors.
- wrap
- booleà que indica si els espais en blanc es poden
tractar en reformatejats cosmètics. En cas afirmatiu, abans
d'utilitzar la cadena, aquesta és canonitzada.
Aquesta informació 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 informació no s'escriu al fitxer PO.
Funcions diverses¶
- count_entries()
- Retorna el nombre d'entrades del catàleg (sense la
capçalera).
- 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 caràcters especificat a la
capçalera PO. Si encara no s'ha ajustat, retornarà
"CHARSET".
- set_charset($)
- Defineix el joc de caràcters de la capçalera PO
al valor especificat com a primer paràmetre. Si no crideu mai aquesta
funció (i no es llegeix cap fitxer amb un joc de caràcters
especificat), el valor per defecte es deixa a "CHARSET". Aquest
valor no canvia el comportament d'aquest mòdul, només s'utilitza
per omplir el camp de la capçalera, i es retorna a
get_charset().
AUTORS¶
Denis Barbier <barbier@linuxfr.org>
Martin Quinson (mquinson#debian.org)