Provided by: po4a_0.69-1_all 
NOME
Locale::Po4a::TransTractor - Modulo generico di traduzione ed estrazione del testo
DESCRIZIONE
L'obiettivo del progetto po4a (PO per tutto) è di facilitare le traduzioni (e cosa più
interessante, la manutenzione delle traduzioni) usando gli strumenti associati a gettext
in aree inaspettate come la documentazione.
Questa classe è l'antenato di ogni parser po4a usato per analizzare un documento, per
cercare stringhe traducibili, per estrarle in un file PO e per sostituirle con la loro
traduzione nel documento in uscita.
Più formalmente, prende i seguenti argomenti in ingresso:
- un documento da tradurre;
- un file PO contenente le traduzioni da usare.
In uscita, produce:
- un altro file PC, risultante dall'estrazione delle stringe traducibili dal documento in
ingresso;
- un documento tradotto, con la stessa struttura di quello in ingresso, ma con tutte le
stringhe traducibili sostituite con le traduzioni trovate nel file PO fornito in
ingresso.
Ecco una rappresentazione grafica di ciò:
Documento in ingresso -\ /--> Documento in uscita
\ / (tradotto)
+-> funzione parse() --+
/ \
PO in ingresso -------/ \--> PO in uscita
(estratto)
FUNZIONI CHE IL PROPRIO PARSER DOVREBBE RIDEFINIRE
parse()
È qui che si svolge tutto il lavoro: l'analisi dei documenti di ingresso, la
generazione del risultato in uscita e l'estrazione delle stringhe traducibili. Tutto
ciò è abbastanza semplice facendo uso delle funzioni presentate nella sezione FUNZIONI
INTERNE di seguito. Vedere anche SINTASSI, che presenta un esempio.
Questa funzione viene chiamata dalla funzione process() di seguito, ma se si sceglie
di usare la funzione new() e di aggiungere contenuto manualmente al documento, si
dovrà chiamare questa funzione.
docheader()
Questa funzione restituisce l'intestazione che dovremmo aggiungere al documento
prodotto, quotata opportunamente tanto da essere considerata un commento nella lingua
di destinazione. Vedere la sezione Educare gli sviluppatori sulle traduzioni, da
po4a(7), per sapere a cosa serve.
SINTASSI
L'esempio seguente analizza un elenco di paragrafi che iniziano con "<p>". Per semplicità,
assumiamo che il documento sia ben formattato, ovvero che i tag '<p>' siano gli unici tag
presenti e che questo tag sia all'inizio di ogni paragrafo.
sub parse {
my $self = shift;
PARAGRAPH: while (1) {
my ($paragraph,$pararef)=("","");
my $first=1;
my ($line,$lref)=$self->shiftline();
while (defined($line)) {
if ($line =~ m/<p>/ && !$first--; ) {
# Non la prima volta che si vede <p>.
# Rimette la riga corrente in ingresso,
# e mette il paragrafo costruito in uscita
$self->unshiftline($line,$lref);
# Ora che il documento è formato, lo traduce:
# - Rimuove il tag d'inzio
$paragraph =~ s/^<p>//s;
# - inserisce in uscita il tag iniziale (non tradotto) e
# il resto del paragrafo (tradotto)
$self->pushline( "<p>"
. $self->translate($paragraph,$pararef)
);
next PARAGRAPH;
} else {
# Accoda al paragrafo
$paragraph .= $line;
$pararef = $lref unless(length($pararef));
}
# Reinizializza il ciclo
($line,$lref)=$self->shiftline();
}
# Nessuna una riga definita? Fine file in ingresso.
return;
}
}
Una volta implementata la funzione di analisi, si può usare la propria classe documento,
usando l'interfaccia pubblica presentata nella sezione successiva.
INTERFACCIA PUBBLICA per gli script che usano il proprio parser
Costruttore
processo(%)
Questa funzione può fare tutto quello che si deve fare con un documento po4a in una
sola chiamata. I suoi argomenti devono essere impacchettati come un hash. AZIONI:
a. Legge tutti i file PO specificati in po_in_name
b. Legge tutti i documenti originali specificati in file_in_name
c. Analizza il documento
d. Legge e applica tutte le addenda specificate
e. Scrive il documento tradotto in file_out_name (se fornito)
f. Scrive il file PO estratto in po_out_name (se fornito)
ARGOMENTI, oltre a quelli accettati da new() (di tipo atteso):
file_in_name (@)
Elenco di nomi di file in cui si dovrebbe leggere il documento di ingresso.
file_in_charset ($)
Set di caratteri utilizzato nel documento di ingresso (se non è specificato,
proverà a rilevarlo dal documento di ingresso).
file_out_name ($)
Nome file dove si dovrà scrivere il documento di uscita.
file_out_charset ($)
Set di caratteri usato nel documento in uscita (se non è specificato, userà il set
di caratteri del file PO).
po_in_name (@)
Elenco di nomi di file da cui leggere i file PO in ingresso, contenente la
traduzione che verrà usata per tradurre il documento.
po_out_name ($)
Nome file dove si dovrà scrivere il file PO in uscita, contenente le stringhe
estratte dal documento in ingresso.
addendum (@)
Elenco di nomi di file da cui si dovrà leggere le addenda.
addendum_charset ($)
Set di caratteri delle addenda.
new(%)
Crea un nuovo documento po4a. Opzioni accettate (nell'hash passato come parametro):
verbose ($)
Imposta il livello di messaggi diagnostici.
debug ($)
Imposta il debug.
Gestione file dei documenti
read($$)
Aggiunge un altro dato del documento di input alla fine dell'array esistente
"@{$self->{TT}{doc_in}}". L'argomento è il nome del file da leggere. Se viene fornito
un secondo argomento, è il nome del file da utilizzare nei riferimenti.
Questo array "@{$self->{TT}{doc_in}}" contiene i dati di questo documento di ingresso
come array di stringhe con significati alternati.
* La stringa $textline contenente ogni riga dei dati di testo di ingresso.
* La stringa "$filename:$linenum" contenente la sua posizione viene
chiamata come "riferimento" ("linenum" inizia con 1).
Si noti che non analizza nulla. Si dovrebbe usare la funzione parse() quando si ha
finito di impacchettare i file in ingresso nel documento.
write($)
Scrive il documento tradotto con il nome file specificato.
I dati di questo documento tradotto sono forniti da:
* "$self->docheader()" che contiene il testo dell'intestazione per il plugin, e
* "@{$self->{TT}{doc_out}}" che contiene ogni riga del testo tradotto principale
nell'array.
Gestione file PO
readpo($)
Aggiunge il contenuto di un file (il cui nome viene passato come argomento) al PO di
ingresso esistente. Il vecchio contenuto non viene scartato.
writepo($)
Scrive il file PO estratto nel nome file dato.
stats()
Restituisce alcune statistiche sulla traduzione eseguita fino a quel momento. Si noti
che non sono le stesse statistiche di quelle prodotte dal comando da msgfmt
--statistic. Qui, sono le statistiche sull'utilizzo recente del file PO, mentre msgfmt
riporta lo stato del file. È un wrapper per la funzione Locale::Po4a::Po::stats_get
applicata al file PO di ingresso. Esempio d'uso:
[uso normale del documento po4a...]
($percent,$hit,$queries) = $document->stats();
print "Trovate traduzioni for $percent\% ($hit da $queries) di stringhe.\n";
Gestione addenda
addendum($)
Fare riferimento a po4a(7) per maggiori informazioni su cosa sono gli addenda e su
come i traduttori dovrebbero scriverli. Per applicare un addendum al documento
tradotto, passare semplicemente il suo nome file a questa funzione ed il gioco è fatto
;)
Questa funzione restituisce un intero non nullo in caso di errore.
FUNZIONI INTERNE usate per scrivere parser derivati
Ottenere l'ingresso, fornire l'uscita
Vengono fornite quattro funzioni per catturare l'ingresso e restituire l'uscita. Sono
molto simili a shift/unshift e push/pop di Perl.
* Perl shift restituisce il primo elemento dell'array e lo toglie dall'array.
* Perl unshift antepone un elemento all'array come primo elemento dell'array.
* Perl pop restituisce l'ultimo elemento dell'array e lo toglie dall'array.
* Perl push aggiunge un elemento all'array come ultimo elemento dell'array.
La prima coppia riguarda l'ingresso, mentre la seconda riguarda l'uscita. Mnemonico: in
ingresso, si è interessati alla prima riga, cosa dà shift, e in uscita si desidera
aggiungere il risultato alla fine, come fa push.
shiftline()
Questa funzione restituisce la prima riga da analizzare e il suo riferimento
corrispondente (compresso come un array) dall'array "@{$self->{TT}{doc_in}}" e
rilascia questi primi 2 elementi dell'array. Qui, il riferimento è fornito da una
stringa "$filename:$linenum".
unshiftline($$)
Annulla lo spostamento dell'ultima riga spostata del documento in ingresso e il
relativo riferimento corrispondente all'inizio di "{$self->{TT}{doc_in}}".
pushline($)
Inserisce una nuova riga alla fine di "{$self->{TT}{doc_out}}".
popline()
Estrae l'ultima riga inserita dalla fine di "{$self->{TT}{doc_out}}".
Marcatura stringhe come traducibili
Viene fornita una funzione per gestire il testo da tradurre.
translate($$$)
Argomenti obbligatori:
- Una stringa da tradurre
- Il riferimento di questa stringa (cioè la posizione nel file di ingresso)
- Il tipo di questa stringa (cioè la descrizione testuale del suo ruolo strutturale;
usata in Locale::Po4a::Po::gettextization(); vedere anche po4a(7), sezione Gettext-
izzazione: come funziona?)
Anche questa funzione usa alcuni argomenti extra. Questi devono essere organizzati
come hash. Esempio:
$self->translate("string","ref","type",
'wrap' => 1);
wrap
booleano indicande se si può considerare gli spazi bianchi nella stringa come non
importanti. Se si, la funzione canonizza la stringa prima di cercare una
traduzione o estrarla, e formatta la traduzione.
wrapcol
la colonna a cui andare a capo (valore predefinito: 76).
comment
un commento extra da aggiungere alla voce.
Azioni:
- Infila stringa, riferimento e tipo in po_out.
- Restituisce la traduzione della stringa (come trovata in po_in) in modo che
l'analizzatore possa creare doc_out.
- Gestisce i set di caratteri per ricodificare le stringhe prima di inviarle a po_out
e prima di restituire le traduzioni.
Funzioni varie
verbose()
Restituisce se l'opzione verbose è stata passata durante la creazione di TransTractor.
debug()
Restituisce se l'opzione di debug è stata passata durante la creazione di
TransTractor.
detected_charset($)
Questo dice a TransTractor che un nuovo set di caratteri (il primo argomento) è stato
rilevato dal documento in ingresso. Di solito può essere letto dall'intestazione del
documento. Rimarrà solo il primo set di caratteri, proveniente dagli argomenti
process() o rilevato dal documento.
get_out_charset()
Questa funzione restituirà il set di caratteri che dovrebbe essere utilizzato nel
documento in uscita (solitamente utile per sostituire il set di caratteri rilevato del
documento in ingresso dove è stato trovato).
Userà il set di caratteri in uscita specificato nella riga di comando. Se non è stato
specificato, userà il set di caratteri del PO in ingresso e se il PO in ingresso ha il
"CHARSET" predefinito, restituirà il set di caratteri del documento in ingresso, in
modo che non venga eseguita alcuna codifica.
recode_skipped_text($)
Questa funzione restituisce il testo ricodificato passato come argomento, dal set di
caratteri del documento in ingresso a quello del documento in uscita. Non è
indispensabile quando si traduce una stringa (dato che translate() ricodifica tutto da
solo), ma è necessario quando si salta una stringa dal documento in ingresso e si
desidera che il documento in uscita sia coerente con la codifica globale.
DIREZIONI FUTURE
Un difetto dell'attuale TransTractor è che non può gestire documenti tradotti contenenti
tutte le lingue, come modelli debconf o file .desktop.
Per risolvere questo problema, le uniche modifiche all'interfaccia necessarie sono:
- prendere un hash come po_in_name (un elenco per lingua)
- aggiungere un argomento da tradurre per indicare la lingua di destinazione
- crea una funzione pushline_all, fa in modo di eseguire una pushline del suo contenuto
per tutte le lingue, utilizzando una sintassi simile a una mappa:
$self->pushline_all({ "Description[".$langcode."]=".
$self->translate($line,$ref,$langcode)
});
Vedremo se è abbastanza ;)
AUTORI
Denis Barbier <barbier@linuxfr.org>
Martin Quinson (mquinson#debian.org)
Jordi Vilalta <jvprat@gmail.com>
TRADUZIONE
Danilo Piazzalunga <danilopiazza@libero.it>
Marco Ciampa <ciampix@posteo.net>