". 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--; ) { # Not the first time we see
. # Reput the current line in input, # and put the built paragraph to output $self->unshiftline($line,$lref); # Now that the document is formed, translate it: # - Remove the leading tag $paragraph =~ s/^
//s; # - push to output the leading tag (untranslated) and the # rest of the paragraph (translated) $self->pushline( "
"
. $self->translate($paragraph,$pararef)
);
next PARAGRAPH;
} else {
# Append to the paragraph
$paragraph .= $line;
$pararef = $lref unless(length($pararef));
}
# Reinit the loop
($line,$lref)=$self->shiftline();
}
# Did not get a defined line? End of input file.
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}}".
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).
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.
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.
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:
[normal use of the po4a document...]
($percent,$hit,$queries) = $document->stats();
print "We found translations for $percent\% ($hit from $queries) of strings.\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 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.
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