Locale::Po4a::TransTractor - generic trans(lator ex)tractor.
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)
- 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.
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;
# - push to output the leading tag (untranslated) and the
# rest of the paragraph (translated)
$self->pushline( "<p>"
. $self->translate($paragraph,$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ó.
- 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(%)
- Create a new po4a document. Accepted options (in the hash
passed as a parameter):
- verbose ($)
- Ajusta el nivell d'informació extra.
- debug ($)
- Activa la depuració.
- read($$)
- Add another input document data at the end of the existing
array "@{$self->{TT}{doc_in}}". The argument is the filename
to read. If a second argument is provided, it is the filename to use in
the references.
This array "@{$self->{TT}{doc_in}}" holds this input document
data as an array of strings with alternating meanings.
* The string $textline holding each line of the input text data.
* The string "$filename:$linenum" holding its location and called
as
"reference" ("linenum" starts with 1).
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.
This translated document data are provided by:
* "$self->docheader()" holding the header text for the plugin,
and
* "@{$self->{TT}{doc_out}}" holding each line of the main
translated text in the array.
- 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";
- 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.
Four functions are provided to get input and return output. They are very
similar to shift/unshift and push/pop of Perl.
* Perl shift returns the first array item and drop it from the array.
* Perl unshift prepends an item to the array as the first array item.
* Perl pop returns the last array item and drop it from the array.
* Perl push appends an item to the array as the last array item.
The first pair is about input, while the second is about output. Mnemonic: in
input, you are interested in the first line, what shift gives, and in output
you want to add your result at the end, like push does.
- shiftline()
- This function returns the first line to be parsed and its
corresponding reference (packed as an array) from the array
"@{$self->{TT}{doc_in}}" and drop these first 2 array items.
Here, the reference is provided by a string
"$filename:$linenum".
- unshiftline($$)
- Unshifts the last shifted line of the input document and
its corresponding reference back to the head of
"{$self->{TT}{doc_in}}".
- pushline($)
- Push a new line to the end of
"{$self->{TT}{doc_out}}".
- popline()
- Pop the last pushed line from the end of
"{$self->{TT}{doc_out}}".
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.
- 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.
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í
- -
- make a pushline_all function, which would make pushline of
its content for all languages, using a map-like syntax:
$self->pushline_all({ "Description[".$codiidioma."]=".
$self->translate($linia,$ref,$codiidioma)
});
Ja veurem si és suficient ;)
Denis Barbier <[email protected]>
Martin Quinson (mquinson#debian.org)
Jordi Vilalta <[email protected]>
Carme Cirera <[email protected]>
Jordi Vilalta <[email protected]>