Provided by: po4a_0.73-2ubuntu1_all 
NOM
Locale::Po4a::TransTractor - generic trans(lator ex)tractor.
DESCRIPCIÓ
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)
FUNCIONS QUE EL VOSTRE ANALITZADOR HA D'IMPLEMENTAR
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.
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 é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ó.
INTERFÍCIE PÚBLICA per guions que utilitzin el vostre analitzador
Constructor
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 ($)
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 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ó.
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 documentació
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 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.
Manupulant fitxers PO
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";
Manipulant annexes
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.
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 traduïbles
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
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 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.
Funcions diverses
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.
get_in_charset()
This function return the charset that was provided as master charset
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ó.
DIRECCIONS FUTURES
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 ;)
AUTORS
Denis Barbier <barbier@linuxfr.org>
Martin Quinson (mquinson#debian.org)
Jordi Vilalta <jvprat@gmail.com>
TRADUCCIÓ
Carme Cirera <menxu@hotmail.com>
Jordi Vilalta <jvprat@gmail.com>
perl v5.38.2 2024-08-28 LOCALE::PO4A::TRANSTRACTOR.3PM(1)