". Per semplicita, assumiamo che il documento sia ben formattato, ovvero che i tag '
' 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/
/ && !$first--; ) { # Non la prima volta che si vede
. # Rimette la riga corrente in ingresso, # e mette il paragrafo costruito in uscita $self->unshiftline($line,$lref); # Ora che il documento e formato, lo traduce: # - Rimuove il tag d'inzio $paragraph =~ s/^
//s; # - inserisce in uscita il tag iniziale (non tradotto) e # il resto del paragrafo (tradotto) $self->pushline( "
"
. $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 puo 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 puo 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 dovra 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 verra usata per tradurre il
documento.
po_out_name ($)
Nome file dove si dovra scrivere il file PO in uscita,
contenente le stringhe estratte dal documento in ingresso.
addendum (@)
Elenco di nomi di file da cui si dovra 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. E 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 e 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 e interessati alla prima riga,
cosa da 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 e 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 (cioe la posizione nel file di
ingresso)
- Il tipo di questa stringa (cioe 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 puo 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 verra 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 e stata passata durante la
creazione di TransTractor.
debug()
Restituisce se l'opzione di debug e stata passata durante la
creazione di TransTractor.
get_in_charset()
Questa funzione restituisce il set di caratteri che e stato fornito
come master
get_out_charset()
Questa funzione restituira 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 e stato trovato).
Usera il set di caratteri in uscita specificato nella riga di
comando. Se non e stato specificato, usera il set di caratteri del
PO in ingresso e se il PO in ingresso ha il "CHARSET" predefinito,
restituira il set di caratteri del documento in ingresso, in modo
che non venga eseguita alcuna codifica.
DIREZIONI FUTURE
Un difetto dell'attuale TransTractor e che non puo 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 e abbastanza ;)
AUTORI
Denis Barbier