Locale::Po4a::Po - Modulo per la manipolazione di file PO
use Locale::Po4a::Po;
my $pofile=Locale::Po4a::Po->new();
# Leggi il file PO
$pofile->read('file.po');
# Aggiungi una voce
$pofile->push('msgid' => 'Hello', 'msgstr' => 'bonjour',
'flags' => "wrap", 'reference'=>'file.c:46');
# Estrai una traduzione
$pofile->gettext("Hello"); # restituisce 'Ciao'
# Restituisce scrivendo in un file
$pofile->write('otherfile.po');
Locale::Po4a::Po è un modulo che permette di elaborare
cataloghi di messaggi. Si può caricare e scrivere da/verso un file
(la cui estensione è spesso po), si possono creare nuove voci
al volo o a richiesta per la traduzione di una stringa.
Per una descrizione più approfondita dei cataloghi di
messaggi in formato PO e sul loro uso, fare riferimento alla documentazione
info del programma gettext (nodo "`PO Files"').
Questo modulo fa parte del progetto po4a, il cui obiettivo
è di usare file PO (progettati originariamente per semplificare la
traduzione dei messaggi dei programmi) per tradurre qualunque cosa, inclusa
la documentazione (pagine man, manuali info), descrizione pacchetti, modelli
debconf, e tutto ciò che potrebbe trarne giovamento.
- --porefs
tipo
- Specifica il formato di riferimento. L'argomento type può
essere un valore qualsiasi tra: never per non produrre nessun
riferimento, file per specificare solo il file senza il numero di
riga, counter per rimpiazzare il numero di riga con un contatore
incrementale, e full per includere il riferimento completo (valore
predefinito: full).
- --wrap-po
no|newlines|numero (predefinito: 76)
- Specifica come il file po deve essere mandato a capo. Consente di
scegliere tra file con righe mandate capo ben formattate e quindi ben
leggibili ma che potrebbero portare a conflitti in git o file che sono
più facili da gestire automaticamente, ma più difficili da
leggere per le persone.
Storicamente, la suite gettext riformattava i file po alla 77a
colonna per questioni estetiche. Questa opzione specifica il
comportamento di po4a. Se impostato su un valore numerico, po4a
manderà a capo il file po a questo numero di colonna e dopo i
caratteri di a capo nel testo. Se impostato su newlines, po4a
dividerà msgstr e msgstr solo dopo i caratteri di a capo nel
testo. Se impostato su no, po4a non metterà a capo nel
testo del file po. L'andare a capo nei commenti di riferimento è
controllato dagli strumenti gettext che vengono usati internamente.
Si noti che questa opzione non ha alcun impatto sul modo in
cui msgstr e msgstr vanno a capo, ovvero su come i caratteri di a capo
vengono aggiunti al contenuto di queste stringhe.
- --msgid-bugs-address
indirizzo@email
- Imposta l'indirizzo a cui inviare i rapporti di errore per i msgid. Come
impostazione predefinita, i file POT creati non hanno campi
Report-Msgid-Bugs-To.
- --copyright-holder
stringa
- Imposta l'intestatario del copyright nell'intestazione del POT. Il valore
predefinito è "Free Software Foundation, Inc."
- --package-name
stringa
- Imposta il nome del pacchetto nell'intestazione del POT. Il valore
predefinito è "PACKAGE".
- --package-version
stringa
- Imposta la versione del pacchetto nell'intestazione del POT. Il valore
predefinito è "VERSION".
- new()
- Crea un nuovo catalogo di messaggi. Se viene fornito un argomento,
è il nome del file PO che bisognerebbe caricare.
- read($)
- Legge un file PO (il cui nome viene dato come argomento). Voci
preesistenti in esso non vengono rimosse, le nuove vengono aggiunte alla
fine del catalogo.
- write($)
- Scrive il catalogo corrente nel file dato.
- write_if_needed($$)
- Come write, ma se il file PO o POT esiste già, l'oggetto
verrà scritto in un file temporaneo che verrà confrontato
con il file esistente per controllare se l'aggiornamento è
necessario (ciò evita di cambiare un file POT solo per aggiornare
una riga di riferimento o il campo POT-Creation-Date).
- filter($)
- Questa funzione estrae un catalogo da uno esistente. Solo le voci con
riferimento nel file dato verranno inserite nel catalogo risultante.
Questa funzione analizza il suo argomento, lo converte in una
definizione di funzione Perl, valuta questa definizione e filtra i campi
per i quali questa funzione restituisce vero.
Amo Perl alle volte ;)
- to_utf8()
- Ricodifica in UTF-8 le msgstrs del PO. Non fa nulla se il set di caratteri
non è specificato nel file PO (il valore di "CHARSET"), o
se è già UTF-8 o ASCII.
- gettext($%)
- Richiede la traduzione della stringa data come argomento, nel catalogo
corrente. La funzione restituisce la stringa originale (non tradotta) se
la stringa non viene trovata.
Dopo la stringa da tradurre, si può passare un hash di
argomenti extra. Ecco le voci accettate:
- wrap
- booleano indicante se si può considerare gli spazi bianchi nella
stringha come non importanti. Se si, la funzione canonizza la stringa
prima di cercare una traduzione, e formatta il risultato.
- wrapcol
- la colonna a cui andare a capo (valore predefinito: 76).
- stats_get()
- Restituisce le statistiche sulla percentuale di successo di gettext
dall'ultima volta che è stato chiamato stats_clear(). Si
noti che non sono le stesse statistiche di quelle stampate da msgfmt
--statistic. Qui, sono le statistiche sull'utilizzo recente del file PO,
mentre msgfmt riporta lo stato del file. Esempio d'uso:
[alcuni usi del file PO per tradurre cose]
($percent,$hit,$queries) = $pofile->stats_get();
print "Si qui, sono state trovate traduzioni per il $percent\% ($hit di $queries) delle stringhe.\n";
- stats_clear()
- Cancella le statistiche generate da gettext.
- push(%)
- Aggiunge una nuova voce alla fine del catalogo corrente. Gli argomenti
dovrebbero formare una tabella hash. Le chiavi valide sono:
- msgid
- la stringa nella lingua originale.
- msgstr
- la traduzione.
- reference
- un'indicazione di dove è stata trovata questa stringa. Esempio:
file.c:46 (che significa in 'file.c' alla riga 46). Può essere un
elenco separato da spazi in caso di più occorrenze.
- un commento aggiunto manualmente (dal traduttore). Il formato è
libero.
- automatic
- un commento che è stato aggiunto automaticamente dal programma di
estrazione delle stringhe. Vedere l'opzione --add-comments del
programma xgettext per maggiori informazioni.
- flags
- elenco separato da spazi di tutte le flag definite per questa voce.
Flag validi sono: c-text, python-text,
lisp-text, elisp-text, librep-text,
smalltalk-text, java-text, awk-text,
object-pascal-text, ycp-text, tcl-text,
wrap, no-wrap e fuzzy.
Consultare la documentazione di gettext per conoscerne il
significato.
- type
- questo è principalmente un argomento interno: viene utilizzato
durante la gettext-izzazione di documenti. Il concetto è,
analizzare sia l'originale che la traduzione in un oggetto PO e poi
unirli, usando il msgid di uno come msgid e il msgid dell'altro come
msgstr. Per assicurarsi che le cose vadano bene, a ogni msgstr negli
oggetti PO viene assegnato un tipo, in base alla loro struttura (come
"chapt", "sect1", "p" e così via in
DocBook). Se i tipi di stringhe non sono gli stessi, significa che
entrambi i file non condividono la stessa struttura e il processo segnala
un errore.
Questa informazione viene scritta come commento automatico nel
file PO poiché ciò fornisce ai traduttori un contesto
sulle stringhe da tradurre.
- wrap
- booleano che indica se gli spazi bianchi possono essere alterati nelle
riformattazioni cosmetiche. Se vero, la stringa viene canonizzata prima
dell'uso.
Questa informazione viene scritta nel file PO usando i flag
wrap o no-wrap.
- wrapcol
- la colonna a cui andare a capo (valore predefinito: 76).
Questa informazione non viene scritta nel file PO.
- count_entries()
- Restituisce il numero delle voci nel catalogo (senza l'intestazione).
- count_entries_doc()
- Restituisce il numero delle voci nel documento. Se una stringa compare
più volte nel documento, verrà contata più
volte.
- msgid($)
- Restituisce il msgid del numero dato.
- msgid_doc($)
- Restituisce il msgid con la data posizione nel documento.
- type_doc($)
- Restituisce il tipo di msgid con la posizione specificata nel documento.
Probabilmente utile solo per ottenere la gettext-izzazione, ed è
memorizzato separatamente da {$msgid}{'type'} perché la posizione
successiva potrebbe essere sovrascritta da un altro tipo quando
$msgid viene duplicato nel documento master.
- get_charset()
- Rstituisce il set di carattere specificato nell'intestazione del file PO.
Se non è stato impostato, restituirà "UTF-8".
- set_charset($)
- Questo imposta il set di caratteri dell'intestazione PO al valore
specificato nel suo primo argomento. Se non si chiama mai questa funzione
(e quindi non viene letto alcun file con uno specifico set di caratteri),
il valore predefinito viene lasciato a "UTF-8". Questo valore
non cambia il comportamento di questo modulo: viene usato solo per
riempire quel campo nell'intestazione e per restituirlo in
get_charset().
Denis Barbier <barbier@linuxfr.org>
Martin Quinson (mquinson#debian.org)
Danilo Piazzalunga <danilopiazza@libero.it>
Marco Ciampa <ciampix@posteo.net>