". For the sake of simplicity, we assume that the document is well formatted, i.e. that '
' 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/
/ && !$primera--; ) { # No es la primera vegada que veiem
. # 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/^
//s; # - push to output the leading tag (untranslated) and the # rest of the paragraph (translated) $self->pushline( "
"
. $self->translate($paragraph,$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.
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 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 ($)
Charset used in the input document (if it isn't specified, use
UTF-8).
file_out_name ($)
Nom del fitxer on s'ha d'escriure el document de sortida.
file_out_charset ($)
Charset used in the output document (if it isn't specified, use
UTF-8).
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(%)
Create a new po4a document. Accepted options (in the hash passed as
a parameter):
verbose ($)
Ajusta el nivell d'informacio extra.
debug ($)
Activa la depuracio.
wrapcol ($)
The column at which we should wrap text in output document
(default: 76).
The negative value means not to wrap lines at all.
Also it accepts next options for underlying Po-files: porefs,
copyright-holder, msgid-bugs-address, package-name, package-
version, wrap-po.
Manipulant fitxers de documentacio
read($$$)
Add another input document data at the end of the existing array
"@{$self->{TT}{doc_in}}".
This function takes two mandatory arguments and an optional one.
* The filename to read on disk;
* The name to use as filename when building the reference in the
PO file;
* The charset to use to read that file (UTF-8 by default)
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 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.
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.
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.
INTERNAL FUNCTIONS used to write derivative parsers
Obtenint entrada, proporcionant sortida
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}}".
Marcant cadenes com a traduibles
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",
'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
the column at which we should wrap (default: the value of
wrapcol specified during creation of the TransTractor or 76).
The negative value will be substracted from the default.
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.
get_in_charset()
This function return the charset that was provided as master
charset
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.
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
- 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 es suficient ;)
AUTORS
Denis Barbier