
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 NOME

Locale::Po4a::Po - Modulo per la manipolazione di file PO

=head1 SINTASSI

    use Locale::Po4a::Po;
    my $pofile=Locale::Po4a::Po->new();

    # Lettura file PO 
    $pofile->read('file.po');

    # Aggiunta di una voce
    $pofile->push('msgid' => 'Hello', 'msgstr' => 'bonjour',
                  'flags' => "wrap", 'reference'=>'file.c:46');

    # Estrazione traduzione
    $pofile->gettext("Hello"); # returns 'bonjour'

    # Scrittura di nuovo in un file
    $pofile->write('otherfile.po');

=head1 DESCRIZIONE

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 I<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.

=head1 OPZIONI ACCETTATE DA QUESTO MODULO

=over 4

=item B<--porefs> I<tipo>

Specifica il formato di riferimento. L'argomento I<type> può essere un
valore qualsiasi tra: B<never> per non produrre nessun riferimento, B<file>
per specificare solo il file senza il numero di riga, B<counter> per
rimpiazzare il numero di riga con un contatore incrementale, e B<full> per
includere il riferimento completo (valore predefinito: full).

=item B<--wrap-po> B<no>|B<newlines>|I<number> (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
B<newlines>, po4a dividerà msgstr e msgstr solo dopo i caratteri di a capo
nel testo. Se impostato su B<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, cioè su come i caratteri di a capo vengono aggiunti al
contenuto di queste stringhe.

=item B<--msgid-bugs-address> I<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.

=item B<--copyright-holder> I<stringa>

Imposta l'intestatario del copyright nell'intestazione del POT. Il valore
predefinito è "Free Software Foundation, Inc."

=item B<--package-name> I<stringa>

Imposta il nome del pacchetto nell'intestazione del POT. Il valore
predefinito è "PACKAGE".

=item B<--package-version> I<stringa>

Imposta la versione del pacchetto nell'intestazione del POT. Il valore
predefinito è "VERSION".

=back

=head1 Funzioni concernenti interi cataloghi di messaggi

=over 4

=item new()

Crea un nuovo catalogo di messaggi. Se viene fornito un argomento, è il nome
del file PO che bisognerebbe caricare.

=item 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.

=item write($)

Scrive il catalogo corrente nel file dato.

=item 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).

=item 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 ;)

=back

=head1 Funzioni che usano un catalogo messaggi per le traduzioni

=over 4

=item 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:

=over

=item B<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.

=item B<wrapcol>

la colonna a cui andare a capo (valore predefinito: 76).

=back

=item 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:

    [some use of the PO file to translate stuff]

    ($percent,$hit,$queries) = $pofile->stats_get();
    print "So far, we found translations for $percent\%  ($hit of $queries) of strings.\n";

=item stats_clear()

Cancella le statistiche generate da gettext.

=back

=head1 Funzioni per creare un catalogo messaggi

=over 4

=item push(%)

Aggiunge una nuova voce alla fine del catalogo corrente. Gli argomenti
dovrebbero formare una tabella hash. Le chiavi valide sono:

=over 4

=item B<msgid>

la stringa nella lingua originale.

=item B<msgstr>

la traduzione.

=item B<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.

=item B<comment>

un commento aggiunto manualmente (dal traduttore). Il formato è libero.

=item B<automatic>

un commento che è stato aggiunto automaticamente dal programma di estrazione
delle stringhe. Vedere l'opzione B<--add-comments> del programma B<xgettext>
per maggiori informazioni.

=item B<flags>

elenco separato da spazi di tutte le flag definite per questa voce.

Flag validi sono: B<c-text>, B<python-text>, B<lisp-text>, B<elisp-text>,
B<librep-text>, B<smalltalk-text>, B<java-text>, B<awk-text>,
B<object-pascal-text>, B<ycp-text>, B<tcl-text>, B<wrap>, B<no-wrap> e
B<fuzzy>.

Consultare la documentazione di gettext per conoscerne il significato.

=item B<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.

=item B<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 B<wrap> o
B<no-wrap>.

=item B<wrapcol>

ignorata; parola chiave mantenuta per compatibilità all'indietro.

=back

=back

=head1 Funzioni varie

=over 4

=item count_entries()

Restituisce il numero delle voci nel catalogo (senza l'intestazione).

=item count_entries_doc()

Restituisce il numero delle voci nel documento. Se una stringa compare più
volte nel documento, verrà contata più volte.

=item msgid($)

Restituisce il msgid del numero dato.

=item msgid_doc($)

Restituisce il msgid con la data posizione nel documento.

=item 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.

=item get_charset()

Rstituisce il set di carattere specificato nell'intestazione del file PO. Se
non è stato impostato, restituirà "UTF-8".

=back

=head1 AUTORI

 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)

=head1 TRADUZIONE

 Danilo Piazzalunga <danilopiazza@libero.it>
 Marco Ciampa <ciampix@posteo.net>

