Provided by:
po4a_0.41-1_all 
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>