Provided by: po4a_0.73-2ubuntu1_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 usato nel documento in ingresso (se non specificato, usa UTF-8).
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, usa UTF-8).
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.
wrapcol ($)
Colonna alla quale mandare a capo il testo in uscita (predefinita: 76).
Il valore negativo significa che le righe non vanno a capo.
Inoltre accetta le opzioni successive per i file Po sottostanti: porefs, copyright-holder, msgid-
bugs-address, package-name, package-version, wrap-po.
Gestione file dei documenti
read($$$)
Aggiunge i dati di un altro documento in ingresso alla fine della schiera esistente
"@{$self->{TT}{doc_in}}".
Questa funzione accetta due argomenti obbligatori e uno facoltativo. * Il nome del file da leggere
su disco; * Il nome da usare come nome file quando si crea il riferimento nel file PO; * Il set di
caratteri da usare per leggere quel file (UTF-8 per impostazione predefinita)
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 alla quale si dovrebbe andare a capo (predefinita: il valore di wrapcol specificato
durante la creazione del TransTractor o 76).
Il valore negativo verrà sottratto dal valore predefinito.
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.
get_in_charset()
Questa funzione restituisce il set di caratteri che è stato fornito come master
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.
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>