Provided by: po4a_0.73-2ubuntu1_all bug

NOME

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

SINTASSI

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

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

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

           # Estrae una traduzione
           $pofile->gettext("Hello"); # restituisce 'Ciao'

           # Restituisce scrivendo in un file
           $pofile->write('otherfile.po');

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

OPZIONI ACCETTATE DA QUESTO MODULO

       --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, cioè 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".

Funzioni concernenti interi cataloghi di messaggi

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

Funzioni che usano un catalogo messaggi per le traduzioni

       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.

Funzioni per creare un catalogo messaggi

       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.

           comment
               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
               ignorata; parola chiave mantenuta per compatibilità all'indietro.

Funzioni varie

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

AUTORI

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

TRADUZIONE

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