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

po4a - framework per la traduzione di documentazione e altro materiale

=head1 Introduzione

po4a (PO per tutto) facilita la manutenzione della traduzione della
documentazione utilizzando i classici strumenti gettext. La caratteristica
principale di po4a è che separa la traduzione dei contenuti dalla struttura
del documento stesso.

Questo documento serve da introduzione al progetto po4a, concentrandosi sui
potenziali utenti di questo strumento e sui curiosi che vogliono capire come
funziona ed il suo scopo.

=head1 Perché po4a?

La filosofia del software libero è di rendere la tecnologia veramente
accessibile a tutti. Ma le licenze non sono l'unico problema: programmi
liberi ma non tradotti sono inutili a chi non parla inglese. Pertanto c'è
ancora del lavoro da fare per rendere il software accessibile a tutti.

Questa situazione è ben compresa dalla maggior parte dei progetti e tutti
sono ormai convinti della necessità di tradurre tutto. Eppure, le traduzioni
attuali rappresentano un enorme sforzo per molti individui, paralizzate da
piccole difficoltà tecniche.

Fortunatamente, il software open source attualmente gode di un buon livello
di traduzione, grazie alla splendida suite gettext. Gli strumenti di questa
suite vengono usati per estrarre le stringhe da tradurre dai programmi e
presentarle ai traduttori un formato standard (chiamato file PO, o catalogo
di traduzioni). Da ciò è nato un intero ecosistema di strumenti di aiuto ai
traduttori per la traduzione di questi file PO. Il risultato viene poi usato
durante l'esecuzione da gettext per mostrare i messaggi tradotti all'utente
finale.

Per quanto riguarda la documentazione, invece, la situazione è ancora
alquanto deludente. All'inizio tradurre la documentazione può sembrare più
facile che tradurre un programma in quanto sembrerebbe che si deve solo
copiare il file sorgente della documentazione e iniziare a tradurre il
contenuto. Tuttavia, quando la documentazione originale viene modificata,
tenere traccia delle modifiche si trasforma rapidamente in un incubo per i
traduttori. Se eseguita manualmente, questa attività non è gratificante e
facilmente soggetta a errori.

Le traduzioni obsolete sono spesso peggio di nessuna traduzione. Gli utenti
finali possono essere ingannati dalla documentazione che descrive un vecchio
comportamento del programma. Inoltre, non possono interagire direttamente
con i manutentori poiché non parlano inglese. Inoltre, il manutentore non
può risolvere il problema poiché non conosce tutte le lingue in cui è
tradotta la documentazione. Queste difficoltà, spesso causate da una
strumentazione scarsa, possono minare la motivazione dei traduttori
volontari, aggravando ulteriormente il problema.

B<L'obiettivo del progetto po4a è facilitare il lavoro dei traduttori di
documentazione>. In particolare, rende le traduzioni della documentazione
I<manutenibili>.

L'idea è di riutilizzare e adattare l'approccio gettext a questo campo. Come
con gettext, i testi vengono estratti dalle loro posizioni originali e
presentati ai traduttori come cataloghi di traduzione PO. I traduttori
possono sfruttare i classici strumenti gettext per monitorare il lavoro da
fare, collaborare e organizzarsi come squadra di traduzione. po4a quindi
inserisce le traduzioni direttamente nella struttura della documentazione
per produrre file sorgente tradotti che possono essere elaborati e
distribuiti proprio come i file inglesi. Qualsiasi paragrafo non tradotto
viene lasciato in inglese nel documento risultante, assicurando che gli
utenti finali non vedano mai una traduzione obsoleta nella documentazione.

Ciò automatizza la maggior parte del lavoro oneroso della manutenzione della
traduzione. La scoperta dei paragrafi che necessitano di un aggiornamento
diventa molto semplice e il processo è completamente automatizzato quando
gli elementi vengono riordinati senza ulteriori modifiche. È inoltre
possibile utilizzare una verifica specifica per ridurre la possibilità di
errori di formattazione che potrebbero causare il rovinarsi del documento.

Consultare la B<FAQ> più avanti in questo documento per avere un elenco
completo di vantaggi e svantaggi di questo approccio.

=head2 Formati supportati

Attualmente, questo approccio è stato realizzato con successo per diversi
formati di documenti di testo:

=over

=item man (analizzatore collaudato)

Il buon vecchio formato delle pagine man, usato da così tanti programmi in
circolazione. Il supporto di po4a è sicuramente benvenuto, dal momento che
questo formato è alquanto difficile da usare direttamente e non è
esattamente amichevole per i principianti.

Il modulo L<Locale::Po4a::Man(3pm)|Man> supporta anche il formato mdoc,
usato dalle pagine man BSD (sono anche abbastanza comuni su Linux).

=item AsciiDoc (analizzatore collaudato)

Questo formato è un formato di markup leggero inteso a facilitare la
creazione della documentazione. Ad esempio, viene utilizzato per documentare
il sistema git. Tali pagine man sono tradotte usando po4a.

Consultare L<Locale::Po4a::AsciiDoc> per i dettagli.

=item pod (analizzatore collaudato)

Questo è il formato della documentazione online di Perl. Il linguaggio e le
sue estensioni sono documentate in questo modo, così come molti degli script
Perl esistenti. Inglobando entrambi nello stesso file è più facile mantenere
la documentazione, essendo vicina al codice corrispondente. Rende la vita
più semplice al programmatore, ma sfortunatamente non al traduttore, finché
non si usa po4a.

Consultare L<Locale::Po4a::Pod> per i dettagli.

=item sgml (analizzatore collaudato)

Anche se oggigiorno è stato in qualche modo superato da XML, questo formato
è ancora molto spesso usato per documenti più lunghi di qualche
schermata. Può essere usato anche per interi libri. Documenti così lunghi
possono rilevarsi ardui da aggiornare. Strumenti come B<diff> si rivelano
spesso inutili quando il testo originale è stato re-indentato dopo
l'aggiormanento. Fortunatamente, po4a può aiutare dopo questo processo.

Al momento sono supportati solo i DTD DebianDoc e DocBook, ma aggiungere il
supporto a nuovi (DTD) è molto facile. È perfino possibile usare po4a su un
DTD SGML sconosciuto senza modificarne il codice, basta fornire le
informazioni necessarie dalla riga di comando. Consultare
L<Locale::Po4a::Sgml(3pm)> per i dettagli.

=item TeX / LaTeX (analizzatore collaudato)

Il formato LaTeX è un formato di documentazione importante usato dal mondo
del Free Software e da diverse pubblicazioni.

Il modulo L<Locale::Po4a::LaTeX(3pm)|LaTeX> è stato testato con la
documentazione Python, un libro e alcune presentazioni.

=item text (analizzatore collaudato)

Il formato text (testo) è il formato base per molti formati che includono
lunghi blocchi di testo, inclusi Markdown, fortunes, YAML front matter
section, debian/changelog, e debian/control.

Questo supporta il generico formato usato nei generatori di siti statici,
nei file README (LEGGIMI), e altri sistemi di documentazione. Vedere
L<Locale::Po4a::Text(3pm)|Text> per i dettagli.

=item xml e XHMTL (analizzatore abbastanza collaudato)

Il formato XML è un formato base per molti formati di documentazione.

Attualmente, il DTD DocBook (consultare L<Locale::Po4a::Docbook(3pm)> per i
dettagli) e XHTML sono supportati da po4a.

=item BibTex (analizzatore abbastanza collaudato)

Il formato BibTex viene usato assieme a LaTex per la formattazione di
elenchi di riferimenti bibliografici.

Consultare L<Locale::Po4a::BibTex> per i dettagli.

=item Docbook (analizzatore abbastanza collaudato)

Un linguaggio a marcatori basato su XML che usa etichette semantiche per
descrivere i documenti.

Consultare L<Locale::Po4a:Docbook> per ulteriori dettagli.

=item Guide XML (analizzatore abbastanza collaudato)

Un formato di documentazione XML. Questo modulo è stato sviluppato
specificamente per supportare e mantenere le traduzioni della documentazione
di Gentoo Linux almeno fino a marzo 2016 (secondo Wayback Machine). Da
allora Gentoo è passato al formato DevBook XML.

Consultare L<Locale::Po4a:Guide> per maggiori dettagli.

=item Wml (analizzatore abbastanza collaudato)

Il Web Markup Language, da non confondere il WML con la roba WAP usata
(N.d.T. soprattutto in passato) sui telefoni cellulari. Questo modulo si
basa sul modulo Xhtml, che a sua volta si basa sul modulo XmL.

Consultare L<Locale::Po4a::Wml> per maggiori dettagli.

=item Yaml (analizzatore abbastanza collaudato)

Un soprainsieme di JSON, YAML viene spesso usato per progetti sistemistici o
per configurazione. YAML è centrale per il sistema di Red Hat Ansible.

Vedere L<Locale::Po4a::Yaml> per maggiori dettagli.

=item RubyDoc (analizzatore abbastanza collaudato)

Il formato Ruby Document (RD), originariamente il formato di documentazione
predefinito per Ruby e per i progetti Ruby prima di essere convertito in
RDoc nel 2002. Anche se apparentemente la versione giapponese del Ruby
Reference Manual usa ancora RD.

Consultare L<Locale::Po4a::RubyDoc> per maggiori dettagli.

=item Halibut (analizzatore abbastanza sperimentale)

Un sistema di produzione di documentazione, con elementi simili a TeX,
debiandoc-sgml, TeXinfo e altri, sviluppato da Simon Tatham, lo sviluppatore
di PuTTY.

Consultare L<Locale::Po4a:Halibut> per maggiori dettagli.

=item Ini (analizzatore abbastanza sperimentale)

Formato di file di configurazione reso popolare da MS-DOS.

Consultare L<Locale::Po4a::Ini> per maggiori dettagli.

=item texinfo (analizzatore molto sperimentale)

Tutta la documentazione GNU è stata scritta in questo formato (è persino uno
dei requisiti per i progetto ufficiali GNU). Il supporto per
L<Locale::Po4a::Texinfo(3pm)|Texinfo> in po4a è ancora agli inizi. Si prega
di segnalare eventuali difetti e richieste di miglioramenti.

=item gemtext (analizzatore molto sperimentale)

Il formato di testo normale nativo del protocollo Gemini. Solitamente si usa
l'estensione C<.gmi>. Il supporto per questo modulo in po4a è ancora agli
inizi. Se si trova qualche problema, inviare una segnalazione o una
richiesta di nuove funzionalità.

=item org (analizzatore molto sperimentale)

Il formato dei documenti per la modalità org (di Emacs). Il supporto per
questo modulo in po4a è ancora agli inizi. Se si trova qualcosa che non va,
segnalarla come difetto o richiesta di funzionalità.

=item vimhelp (analizzatore molto sperimentale)

Il formato utilizzato per i file di aiuto di Vim (e per la documentazione di
alcuni plugin di terze parti). Il supporto per questo formato in po4a è
ancora agli inizi. Se si trova qualche problema, vi invitiamo a inoltrare un
rapporto difetti o una richiesta di funzionalità.

=item simplepod (very highly experimental parser)

Simile al modulo I<pod> menzionato in precedenza, questo adotta il nuovo
L<Pod::Simple> come analizzatore. Essendo di nuova creazione, ci si può
aspettare qualche difetto. Se si notano comportamenti anomali, vi preghiamo
di segnalarcelo. A breve, questo modulo sostituirà I<pod>.

=item Altri formati supportati

Po4a può anche gestire qualche altro formato raro o di uso specifico, come
la documentazione delle opzioni di compilazione dei kernel
2.4+(L<Locale::Po4a::KernelHelp>), oppure i diagrammi prodotti dal programma
Dia(L<Locale::Po4a::Dia>). Aggiungere un nuovo formato è spesso molto facile
e il grosso del lavoro è produrre un analizzatore per il formato scelto. Per
maggiori informazioni su questo argomento, consultare
L<Locale::Po4a::TransTractor(3pm)>.

=item Formati non supportati

Sfortunatamente, a po4a manca il supporto per diversi formati di
documentazione. Molti di questi non sarebbero facili da supportare. Questi
includono formati non solo di documentazione come le descrizioni dei
pacchetti (deb e rpm), le domande poste dagli script di installazione dei
pacchetti, i changelog dei pacchetti e tutti i formati specializzati usati
da vari programmi, come gli scenari dei giochi o i file delle risorse di
wine.

=back

=head1 Uso di po4a

Il modo più semplice per utilizzare questo strumento nel progetto è scrivere
un file di configurazione per il programma B<po4a> e interagire solo con
questo programma. Fare riferimento alla documentazione in L<po4a(1)>. Il
resto di questa sezione fornisce maggiori dettagli per gli utenti avanzati
di po4a che desiderano approfondire la comprensione di po4a.

=head2 Schema dettagliato del flusso di lavoro di po4a

Assicurati di leggere L<po4a(1)> prima di questa sezione eccessivamente
dettagliata per ottenere una panoramica semplificata del flusso di lavoro
po4a. Tornare qui quando si vuole avere l'impressionante quadro completo,
con quasi tutti i dettagli.

Nel seguente schema, F<master.doc> è un nome di esempio per la
documentazione da tradurre; F<XX.doc> è lo stesso documento tradotto nella
lingua XX mentre F<doc.XX.po> è il catalogo di traduzione per quel documento
nella lingua XX. Gli autori della documentazione si occuperanno
principalmente di F<master.doc> (che può essere una pagina man, un documento
XML, un file AsciiDoc, ecc.); i traduttori si occuperanno principalmente del
file PO, mentre gli utenti finali vedranno solo il file F<XX.doc>.

Le transizioni con parentesi quadre come C<[po4a aggiorna po]> rappresentano
l'esecuzione di uno strumento po4a mentre le transizioni con parentesi
graffe come C<{ aggiorna master.doc }> rappresentano una modifica manuale
dei file del progetto.

                                   master.doc
                                       |
                                       V
     +<-----<----+<-----<-----<--------+------->-------->-------+
     :           |                     |                        :
{translation}    |          {update of master.doc}              :
     :           |                     |                        :
   XX.doc        |                     V                        V
 (optional)      |                 master.doc ->-------->------>+
     :           |                   (new)                      |
     V           V                     |                        |
  [po4a-gettextize]   doc.XX.po -->+   |                        |
          |            (old)       |   |                        |
          |              ^         V   V                        |
          |              |   [po4a updates po]                  |
          V              |           |                          V
   translation.pot       ^           V                          |
          |              |        doc.XX.po                     |
          |              |         (fuzzy)                      |
    {translation}        |           |                          |
          |              ^           V                          V
          |              |     {manual editing}                 |
          |              |           |                          |
          V              |           V                          V
      doc.XX.po --->---->+<---<-- doc.XX.po    addendum     master.doc
      (initial)                 (up-to-date)  (optional)   (up-to-date)
          :                          |            |             |
          :                          V            |             |
          +----->----->----->------> +            |             |
                                     |            |             |
                                     V            V             V
                                     +------>-----+------<------+
                                                  |
                                                  V
                                     [po4a updates translations]
                                                  |
                                                  V
                                                XX.doc
                                             (up-to-date)

Di nuovo, questo schema è eccessivamente complicato. Consultare L<po4a(1)>
per una panoramica semplificata.

La parte sinistra mostra come L<po4a-gettextize(1)> può essere usato per
convertire un progetto di traduzione esistente verso l'infrastruttura
po4a. Questo script prende un documento originale e la sua associata parte
tradotta e cerca di creare il file PO corrispondente. Tale conversione
manuale è piuttosto complicata (vedere la documentazione di
L<po4a-gettextize(1)> per maggiori dettagli), ma è necessaria solo una volta
per convertire le traduzioni esistenti. Se non si ha alcuna traduzione da
convertire, si può dimenticarsene e concentrarsi solo sulla parte destra
dello schema.

In alto a destra, viene illustrata l'azione dell'autore originale che
aggiorna la documentazione. Nel centro della parte destra, sono raffigurate
le azioni automatiche di aggiornamento dei file di traduzione: il nuovo
materiale viene estratto e confrontato con la traduzione esistente. La
traduzione precedente viene usata per le parti che non sono cambiate. Le
parti parzialmente modificate vengono associate alla traduzione precedente,
ma con la marcatura "fuzzy" indicante che la traduzione necessita di
aggiornamento. Il materiale nuovo o completamente modificato viene lasciato
non tradotto.

Quindi, la I<modifica manuale> riportata, descrive l'azione dei traduttori,
che modificano i file PO per fornire traduzioni per ogni stringa e paragrafo
originali. Ciò può essere effettuato utilizzando un editor specifico come lo
B<GNOME Translation Editor>, B<Lokalize> di KDE o B<poedit> o utilizzando
una piattaforma di traduzione sul web come B<weblate> o B<pootle>. Il
risultato della traduzione è un insieme di file PO, uno per lingua. Fare
riferimento alla documentazione di gettext per maggiori dettagli.

La parte inferiore della figura mostra come B<po4a> crea un documento
sorgente tradotto dal documento originale F<master.doc> e il catalogo di
traduzioni F<doc.XX.po> aggiornato dai traduttori. La struttura del
documento viene riutilizzata, mentre il contenuto originale viene sostituito
dalla sua controparte tradotta. Facoltativamente, è possibile utilizzare
un'appendice per aggiungere del testo extra alla traduzione. Viene spesso
utilizzato per aggiungere il nome del traduttore al documento finale. Vedere
sotto per i dettagli.

All'invocazione, B<po4a> aggiorna sia i file delle traduzioni che i
documenti tradotti automaticamente.

=head2 Iniziare un nuovo progetto di traduzione

Se si inizia da zero, bisogna solo scrivere un file di configurazione per
po4a e il gioco è fatto. Modelli adatti vengono creati per i file mancanti,
consentendo ai contributori di tradurre il progetto nella propria
lingua. Fare riferimento a L<po4a(1)> per un tutorial di avvio rapido e per
tutti i dettagli.

Se si dispone di una traduzione esistente, ovvero di un file di
documentazione che è stato tradotto manualmente, si può integrarne il
contenuto nel flusso di lavoro po4a utilizzando B<po4a-gettextize>. Questa
attività è un po' complicata (come descritto nella manpage dello strumento),
ma una volta convertito il progetto nel flusso di lavoro po4a, tutto verrà
aggiornato automaticamente.

=head2 Aggiornare le traduzioni e i documenti

Una volta configurato, è sufficiente invocare B<po4a> per aggiornare sia i
file PO di traduzione che i documenti tradotti. Si può passare
C<--no-translations> a B<po4a> per non aggiornare le traduzioni (aggiornando
quindi solo i file PO) o C<--no-update> per non aggiornare i file PO
(aggiornando quindi solo i file PO) traduzioni). Ciò corrisponde
approssimativamente ai singoli script B<po4a-updatepo> e B<po4a-translate>
che ora sono deprecati (vedere "Perché i singoli script sono deprecati"
nelle FAQ di seguito).

=head2 Uso di addenda per aggiungere testo extra alle traduzioni

L'aggiunta di nuovo testo alla traduzione è probabilmente l'unica cosa che è
più facile fare a lungo termine quando si traducono i file manualmente
:). Si fa quando si vuole aggiungere una sezione extra al documento tradotto
che non corrisponde a nessun contenuto nel documento originale. Il caso
d'uso classico è quello per dare riconoscimento ai traduttori e per indicare
come segnalare problemi specifici riguardanti la traduzione.

Con po4a, bisogna specificare i file B<addendum>, che possono essere visti
concettualmente come patch applicate al documento localizzato dopo
l'elaborazione. Ogni addendum deve essere fornito come file separato, il cui
formato è però molto diverso dalle patch classiche. La prima riga è una
I<riga di intestazione>, che definisce il punto di inserimento dell'addendum
(con una sintassi purtroppo criptica - vedere sotto) mentre il resto del
file viene aggiunto, così com'è, alla posizione determinata.

La riga di intestazione deve iniziare con la stringa B<PO4A-HEADER:>,
seguita da un elenco separato da punti e virgola di campi
I<chiave>B<=>I<valore>.

Ad esempio, la seguente intestazione dichiara un addendum che deve essere
inserito alla fine della traduzione.

 PO4A-HEADER: mode=eof

Le cose si fanno più complicate quando vuole aggiungere il contenuto extra
in mezzo al documento. La seguente intestazione dichiara un addendum che
deve essere inserito dopo la sezione XML contenente la stringa C<About this
document> nella traduzione.

 PO4A-HEADER: position=About this document; mode=after; endboundary=</section>

In pratica, quando si cerca di applicare un addendum, po4a cerca la prima
riga che corrisponde all'argomento C<position> (può essere un'espressione
regolare). Non bisogna dimenticare che qui po4a considera il documento
B<translated>. Questa documentazione è in inglese, ma la propria riga
dovrebbe probabilmente essere la seguente, se si intende applicare
l'addendum alla traduzione francese del documento.

 PO4A-HEADER: position=À propos de ce document; mode=after; endboundary=</section>

Una volta trovata la C<position> (posizione) nel documento di destinazione,
po4a cerca la riga successiva dopo la C<position> che corrisponde al
C<endboundary> fornito. L'addendum viene aggiunto subito B<after> (dopo)
quella riga (perché abbiamo fornito una I<endboundary>, cioè un confine che
termina la sezione corrente).

Lo stesso identico effetto potrebbe essere ottenuto con la seguente
intestazione, che è equivalente:

 PO4A-HEADER: position=About this document; mode=after; beginboundary=<section>

Qui, po4a cerca la prima riga che corrisponde a C<< <section> >> dopo la
riga che corrisponde a C<About this document> nella traduzione e aggiunge
l'addendum B<before> (prima) quella riga poiché abbiamo fornito un
I<beginboundary>, cioè un confine che segna l'inizio della sezione
successiva. Quindi questa riga di intestazione richiede di inserire
l'addendum dopo la sezione contenente C<About this document> e indica a po4a
che una sezione inizia con una riga contenente il tag C<< <section> >>. Ciò
è equivalente all'esempio precedente perché quello che si vuole veramente è
aggiungere questo addendum dopo C<< </section> >> o prima di C<< <section>
>>.

Si può anche impostare l'inserimento I<mode> al valore C<before>, con una
semantica simile: combinando C<mode=before> con C<endboundary> metterà
l'addendum appena B<after> (dopo) il limite corrispondente, l'ultima
potenziale linea di confine prima della C<position>. La combinazione di
C<mode=before> e C<beginboundary> metterà l'addendum appena B<before>
(prima) del confine corrispondente, ovvero l'ultima potenziale linea di
confine prima di C<position>.

  Mode   | Boundary kind |     Used boundary      | Insertion point compared to the boundary
 ========|===============|========================|=========================================
 'before'| 'endboundary' | last before 'position' | Right after the selected boundary
 'before'|'beginboundary'| last before 'position' | Right before the selected boundary
 'after' | 'endboundary' | first after 'position' | Right after the selected boundary
 'after' |'beginboundary'| first after 'position' | Right before the selected boundary
 'eof'   |   (none)      |  n/a                   | End of file

=head3 Suggerimenti e trucchi sugli addenda

=over

=item

Si ricordi che queste sono espressioni regolari. Per esempio, se si vuole
far corrispondere la fine di una sezione nroff con la riga C<.fi>, non usare
C<.fi> come B<endboundary>, perché corrisponderebbe con C<il[ fi]le>, che
ovviamente non è quello che ci si aspettava. Il corretto B<endboundary> in
tal caso è: C<^\.fi$>.

=item

Gli spazi bianchi SONO importanti nel contenuto di C<position> e dei
confini. Quindi le due righe seguenti B<sono diverse>. Il secondo verrà
trovato solo se ci sono abbastanza spazi finali nel documento tradotto.

 PO4A-HEADER: position=About this document; mode=after; beginboundary=<section>
 PO4A-HEADER: position=About this document ; mode=after; beginboundary=<section>

=item

Sebbene questa ricerca di contesto possa essere considerata come operante
approssimativamente su ciascuna riga del documento B<tradotto>, in realtà
opera sulla stringa dati interna del documento tradotto. Questa stringa dati
interna può essere un testo che si estende su un paragrafo contenente più
righe o può essere la marcatura XML stessa da sola. L'esatto I<punto di
inserimento> dell'addendum deve essere prima o dopo la stringa dati interna
e non può essere all'interno della stessa.

=item

Passa l'argomento C<-vv> a B<po4a> per capire come aggiungere gli addenda
alla traduzione. Può anche essere utile eseguire B<po4a> in modalità di
debug per vedere la stringa di dati interna effettiva quando l'addendum non
si applica.

=back

=head3 Esempi di addenda

=over

=item

Se si vuole aggiungere qualcosa dopo la seguente sezione nroff:

  .SH "AUTHORS"

È necessario selezionare un approccio in due fasi impostando
B<mode=after>. Poi bisogna restringere la ricerca alla riga dopo B<AUTHORS>
con l'argomento espressione regolare B<position>. Quindi, si dovrebbe
abbinare l'inizio della sezione successiva (ad esempio, B<^\.SH>) con
l'espressione regolare dell'argomento B<beginboundary>. Vale a dire:

 PO4A-HEADER:mode=after;position=AUTHORS;beginboundary=\.SH

=item

Se si vuole aggiungere qualcosa dopo una data riga (come dopo "Copyright Big
Dude"), fare in modo che B<position> corrisponda a questa riga,
B<mode=after> e fare in modo che B<beginboundary> corrisponda a qualunque
riga.

 PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^

=item

Se si vuole aggiungere qualcosa alla fine del documento, fare in modo che
B<position> corrisponda a qualunque riga del documento (ma solo una
riga. Po4a non procederà se questa non è univoca), e fare in modo che
B<endboundary> non corrisponda a nulla. Non usare stringhe semplici come
B<"EOF">, ma preferire quelle che hanno meno probabilità di esistere nel
documento.

 PO4A-HEADER:mode=after;position=About this document;beginboundary=FakePo4aBoundary

=back

=head3 Esempio più dettagliato

Documento originale (formattato POD):

 |=head1 NAME
 |
 |dummy - a dummy program
 |
 |=head1 AUTHOR
 |
 |me

Poi, il seguente addendum assicurerà che una sezione (in Francese)
riguardante il traduttore venga aggiunta alla fine del file (in Francese,
"TRADUCTEUR" significa "TRADUTTORE", e "moi" significa "me").

 |PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head
 |
 |=head1 TRADUCTEUR
 |
 |moi
 |

Per mettere il proprio addendum prima dell'AUTHOR, usare l'intestazione
seguente:

 PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1

Questo funziona perché la successiva riga che corrisponde al
B<beginboundary> C</^=head1/> dopo la sezione "NAME" (tradotta in "NOM" in
Francese), è quella che dichiara gli autori. Perciò, l'addendum verrà messo
tra entrambe le sezioni. Si noti che se un'altra sezione viene aggiunta in
seguito tra le sezioni NAME e AUTHOR, po4a metterà erroneamente l'addenda
prima della nuova sezione.

Per evitare ciò si può ottenere lo stesso risultato usando
B<mode>=I<before>:

 PO4A-HEADER:mode=before;position=^=head1 AUTEUR

=head1 Come funziona?

Questo capitolo fornisce una breve panoramica del funzionamento interno di
po4a, nell'ottica di aiutarci nella manutenzione e nel contribuire al
miglioramento di questo software. Il capitolo può anche aiutare a capire
perché il programma non si comporta come ci si aspetta e a risolvere
eventuali problemi.

=head2 TransTractors e l'architettura del progetto

Al centro del progetto po4a c'è la classe
L<Locale::Po4a::TransTractor(3pm)|TransTractor> che è l'antenato comune di
tutte le classi degli analizzatori (parser). Questo strano nome deriva dal
fatto che è allo stesso tempo incaricato di tradurre il documento e di
estrarne le stringhe.

Più formalmente, esso prende un documento da tradurre più un file PO
contenente le traduzioni da usare come ingresso producendo due risultati
separati: un altro file PO (risultato dall'estrazione delle stringhe
traducibili dal documento in ingresso), e un documento tradotto (con la
stessa struttura di quello in ingresso, ma con tutte le stringhe traducibili
rimpiazzate dal contenuto del file PO in ingresso). Ecco una
rappresentazione grafica di tutto ciò:

   Input document --\                             /---> Output document
                     \      TransTractor::       /       (translated)
                      +-->--   parse()  --------+
                     /                           \
   Input PO --------/                             \---> Output PO
                                                       (extracted)

Questo piccolo osso è il cuore di tutta l'architettura di po4a. Se si
fornisce entrambi gli ingressi e si ignora il PO in uscita, si ottiene
B<po4a-translate>. Se si tralascia il documento in uscita invece, si ottiene
B<po4a-updatepo>. B<po4a> usa TransTractor una prima volta per ottenere un
file POT in uscita aggiornato (ignoranto i documenti in uscita), chiama
B<msgmerge -U> per aggiornare i file PO delle traduzioni su disco, e invoca
TransTractor con questi file PO aggiornati per aggiornare i documenti in
uscita. In breve, B<po4a> fornisce una soluzione tutta in uno per aggiornare
ciò che serve, usando un singolo file di configurazione.

Anche B<po4a-gettextize> utilizza due TransTractor, ma in un altro modo:
crea un TransTractor per lingua, quindi crea un nuovo file PO utilizzando i
msgid del documento originale come msgids e i msgid del documento tradotto
come msgstrs. È necessaria molta attenzione per garantire che le stringhe
corrispondenti, in questa modalità, corrispondano effettivamente, come
descritto in L<po4a-gettextize(1)>.

=head2 Analizzatori specifici per formato

Tutti gli analizzatori del formato po4a sono implementati sopra
TransTractor. Alcuni di essi sono molto semplici, come quelli Text, Markdown
e AsciiDoc. Caricano le righe una per una usando
C<TransTractor::shiftline()>, accumulano il contenuto dei paragrafi o
altro. Una volta che una stringa è stata completamente analizzata,
l'analizzatore utilizza C<TransTractor::translate()> per (1) aggiungere
questa stringa al file PO di output e (2) ottenere la traduzione dal file PO
di ingresso. L'analizzatore quindi invia il risultato al file di uscita
utilizzando C<TransTractor::pushline()>.

Alcuni altri analizzatori sono più complessi perché si affidano a un
analizzatore esterno per analizzare il documento di ingresso. Gli
analizzatori Xml, HTML, SGML e Pod sono basati sugli analizzatori
SAX. Dichiarano callback a eventi come "Ho trovato un nuovo titolo il cui
contenuto è il seguente" per aggiornare il documento in uscita e produrre
file POT in base al contenuto di ingresso utilizzando
C<TransTractor::translate()> e C<TransTractor::pushline()>. L'analizzatore
Yaml è simile ma diverso: serializza una struttura dati prodotta
dall'analizzatore YAML::Tiny. Questo è il motivo per cui il modulo Yaml di
po4a non riesce a dichiarare le linee di riferimento: la posizione di ogni
stringa nel file di ingresso non è mantenuta dall'analizzatore, quindi si
può fornire solo "$filename:1" come posizione della stringa. Gli
analizzatori orientati a SAX utilizzano valori globali e altri trucchi per
salvare il nome del file e i numeri di riga dei riferimenti.

Un problema specifico deriva dalle codifiche dei file e dagli indicatori
della distinta base. Gli analizzatori semplici possono dimenticarsi di
questo problema, che è gestito da C<TransTractor::read()> (usato
internamente per ottenere le righe di un documento di ingresso), ma i moduli
che si affidano a un analizzatore esterno devono garantire che tutti i file
vengano letti con uno strato di decodifica PerlIO appropriato. Il modo più
semplice è aprire il file da soli e fornire un filehandle o direttamente la
stringa completa all'analizzatore esterno. Controllare C<Pod::read()> e
C<Pod::parse()> per avere un esempio. Il contenuto letto dal TransTractor
viene ignorato, ma un nuovo filehandle viene passato all'analizzatore
esterno. La parte importante è la modalità C<< "<:encoding($charset)" >> che
viene passata alla funzione perl B<open()>.

=head2 Oggetti po

La classe L<Locale::Po4a::Po(3pm)|Po> è incaricata di caricare e utilizzare
i file PO e POT. Fondamentalmente, si può leggere un file, aggiungere voci,
ottenere traduzioni con il metodo B<gettext()>, scrivere il PO in un
file. Funzionalità più avanzate come l'unione di un file PO con un file POT
o la convalida di un file sono delegate rispettivamente a B<msgmerge> e
B<msgfmt>.

=head2 Contribuire a po4a

Anche se non si ha mai contribuito ad alcun progetto Open Source in passato,
siete benvenuti: siamo disposti ad aiutare e guidare. Oggigiorno po4a è
gestito meglio che in passato. Dato che disponiamo di manodopera, cerchiamo
di rendere il progetto accogliente migliorando la documentazione e i test
automatici per dare sicurezza nel contribuire al progetto. Per ulteriori
dettagli fare riferimento al file CONTRIBUTING.md.

=head1 Progetti open source che usano po4a

Ecco un elenco molto incompleto di progetti che usano po4a in produzione per
la loro documentazione. Se si vuole aggiungere il proprio progetto
all'elenco, inviaci un'e-mail (o una richiesta di merge).

=over

=item

adduser (man): strumento di gestione utenti e gruppi.

=item

apt (man, docbook): gestore pacchetti Debian.

=item

aptitude (docbook, svg): gestore pacchetti basato sul terminale per Debian

=item

L<Sito web F-Droid|https://gitlab.com/fdroid/fdroid-website> (markdown):
catalogo installabile di applicazioni FOSS (Free and Open Source Software)
per la piattaforma Android.

=item

L<git|https://github.com/jnavila/git-manpages-l10n> (asciidoc): sistema di
controllo versione distribuito per tenere traccia delle modifiche nel codice
sorgente.

=item

L<Pagine man di
Linux|https://salsa.debian.org/manpages-l10n-team/manpages-l10n> (man)

Questo progetto fornisce un'infrastruttura per la traduzione delle pagine
man in diverse lingue, pronta per l'integrazione nelle principali
distribuzioni (Arch Linux, Debian e derivate, Fedora, ecc.).

=item

L<Stellarium|https://github.com/Stellarium/stellarium> (HTML): un planetario
libero e open source per il proprio computer. po4a viene usato per tradurre
le descrizioni nelle varie culture del cielo.

=item

L<Jamulus|https://jamulus.io/> (markdown, yaml, HTML): un'applicazione FOSS
per il jamming online in tempo reale. La documentazione del sito viene
mantenuta in più lingue tramite po4a.

=item

Altro elemento da sistemare: L<https://gitlab.com/fdroid/fdroid-website/>
L<https://github.com/fsfe/reuse-docs/pull/61>

=back

=head1 FAQ

=head2 Come si pronuncia po4a?

Personalmente lo pronuncio come
L<pouah|https://en.wiktionary.org/wiki/pouah>, che è un termine onomatopeico
francese che si usa al posto di puah :) forse ho uno strano senso
dell'umorismo :)

=head2 Perché gli script singoli sono deprecati?

In effetti, B<po4a-updatepo> e B<po4a-translate> sono deprecati in favore di
B<po4a>. Il motivo è che dato che B<po4a> può essere usato come sostituto di
questi script, c'è molta duplicazione del codice. I singoli script constano
di circa 150 righe di codice mentre il programma B<po4a> è lungo 1200 righe,
quindi fanno molto in aggiunta alle parti interne comuni. La duplicazione
del codice ha come effetto che i difetti si verificano spesso in entrambe le
versioni e richiedono due correzioni. Un esempio di tale duplicazione sono i
bug #1022216 in Debian e il problema #442 in GitHub che avevano la stessa
identica correzione, ma uno in B<po4a> e l'altro B<po4a-updatepo>.

A lungo termine, si vorrebbe eliminare i singoli script e mantenere solo una
versione del codice. La cosa sicura è che i singoli script non verranno più
migliorati, quindi solo B<po4a> riceverà le nuove funzionalità. Detto
questo, non vi è alcuna urgenza di deprecazione. I singoli script verranno
conservati il più a lungo possibile e almeno fino al 2030. Ma se il proprio
progetto utilizza ancora B<po4a-updatepo> e B<po4a-translate> nel 2030,
potrebbe essere un problema.

Si potrebbe anche rimuovere la deprecazione di questi script ad un certo
punto, se un refactoring riducesse la duplicazione del codice a zero. Se si
ha un'idea (o meglio: una patch), ogni aiuto è il benvenuto.

=head2 E gli altri strumenti di traduzione per la documentazione che usano gettext?

Ce ne sono alcuni. Ecco un elenco forse incompleto e altri strumenti stanno
arrivando all'orizzonte.

=over

=item B<poxml>

Questo è lo strumento sviluppato dalle persone del progetto KDE per gestire
DocBook XML. Per quanto ne sappiamo, è stato il primo programma a estrarre
le stringhe da tradurre dalla documentazione in file PO e ad iniettarle
nuovamente dopo la traduzione.

Può gestire solo XML e solo una particolare DTD. Non piace particolarmente
la gestione degli elenchi, che finiscono in un unico grande msgid. Quando
l'elenco diventa grande, il blocco diventa più difficile da gestire.

=item B<po-debiandoc>

Questo programma realizzato da Denis Barbier è una sorta di precursore del
modulo SGML po4a, che più o meno lo rende deprecato. Come dice il nome,
gestisce solo la DTD DebianDoc, che è più o meno una DTD deprecata.

=item B<xml2po.py>

Utilizzato dal Gruppo di Documentazione di GIMP dal 2004, funziona
abbastanza bene anche se, come suggerisce il nome, solo con file XML e
necessita di makefile appositamente configurati.

=item B<Sphinx>

Il Progetto Sphinx usa anch'esso ampiamente gettext per gestire le
traduzioni. Sfortunatamente, funziona solo per pochi formati di testo, rest
e markdown, anche se forse è l'unico strumento che fa questo gestendo
l'intero processo di traduzione.

=back

I principali vantaggi di po4a rispetto ad essi sono la facilità di aggiunta
di contenuti extra (che è anche più arduo) e la capacità di ottenere la
gettext-izzazione.

=head2 SOMMARIO dei vantaggi dell'approccio basato su gettext

=over 2

=item

Le traduzioni non vengono memorizzate insieme all'originale, il che rende
possibile rilevare se le traduzioni diventano obsolete.

=item

Le traduzioni vengono memorizzate in file separati l'uno dall'altro, il che
impedisce ai traduttori di lingue diverse di interferire, sia quando inviano
la loro patch che a livello di codifica del file.

=item

È basato internamente su B<gettext> (ma B<po4a> offre un'interfaccia molto
semplice in modo che non sia necessario comprendere le parti interne per
usarlo). In questo modo, non bisogna reinventare la ruota e, a causa del
loro ampio utilizzo, possiamo assumere che questi strumenti siano più o meno
privi di bug.

=item

Non cambia nulla per l'utente finale (a parte il fatto che si spera che le
traduzioni vengano mantenute meglio). Il file di documentazione risultante
distribuito rimane esattamente lo stesso.

=item

Non c'è bisogno che i traduttori imparino una nuova sintassi di file e il
loro editor di file PO preferito (come la modalità PO di Emacs, Lokalize o
Gtranslator) funzionerà perfettamente.

=item

gettext offre un modo semplice per ottenere statistiche su ciò che è stato
fatto, cosa dovrebbe essere revisionato e aggiornato, e cosa c'è ancora da
fare. Qualche esempio si può trovare su:

 - https://docs.kde.org/stable5/en/kdesdk/lokalize/project-view.html
 - http://www.debian.org/intl/l10n/

=back

Ma non è tutto rose e fiori e questo approccio presenta anche alcuni
svantaggi che dobbiamo affrontare.

=over 2

=item

Gli addenda sono strani ad una prima occhiata.

=item

Non si può adattare il testo tradotto alle proprie preferenze, come dividere
un paragrafo qui e unirne altri due la. Ma in un certo senso è un bene,
perché se c'è un problema con l'originale, dovrebbe comunque essere
segnalato come un bug all'autore.

=item

Anche con un'interfaccia semplice, rimane un nuovo strumento che le persone
devono imparare.

Uno dei miei sogni sarebbe quello di integrare in qualche modo po4a in
Gtranslator o Lokalize. Aprendo un file di documentazione, le stringhe
potrebbero essere estratte automaticamente e file tradotto e file po
potrebbe venire scritti su disco. Se si riesce a fare un modulo MS Word (TM)
(o almeno RTF) persino i traduttori professionisti potrebbero usarlo.

=back

=head1 VEDERE ANCHE

=over

=item

La documentazione dello strumento tutto-in-uno che si dovrebbe usare:
L<po4a(1)>.

=item

La documentazione dei singoli script po4a: L<po4a-gettextize(1)>,
L<po4a-updatepo(1)>, L<po4a-translate(1)>, L<po4a-normalize(1)>.

=item

Gli script di aiuto aggiuntivi: L<msguntypot(1)>, L<po4a-display-man(1)>,
L<po4a-display-pod(1)>.

=item

The parsers of each formats, in particular to see the options accepted by
each of them: L<Locale::Po4a::AsciiDoc(3pm)> L<Locale::Po4a::Dia(3pm)>,
L<Locale::Po4a::Gemtext(3pm)>, L<Locale::Po4a::Guide(3pm)>,
L<Locale::Po4a::Ini(3pm)>, L<Locale::Po4a::KernelHelp(3pm)>,
L<Locale::Po4a::Man(3pm)>, L<Locale::Po4a::RubyDoc(3pm)>,
L<Locale::Po4a::Texinfo(3pm)>, L<Locale::Po4a::Text(3pm)>,
L<Locale::Po4a::Xhtml(3pm)>, L<Locale::Po4a::Yaml(3pm)>,
L<Locale::Po4a::BibTeX(3pm)>, L<Locale::Po4a::Docbook(3pm)>,
L<Locale::Po4a::Halibut(3pm)>, L<Locale::Po4a::LaTeX(3pm)>,
L<Locale::Po4a::Org(3pm)>, L<Locale::Po4a::Pod(3pm)>,
L<Locale::Po4a::SimplePod(3pm)>, L<Locale::Po4a::Sgml(3pm)>,
L<Locale::Po4a::TeX(3pm)>, L<Locale::Po4a::VimHelp>,
L<Locale::Po4a::Wml(3pm)>, L<Locale::Po4a::Xml(3pm)>.

=item

L'implementazione del nucleo della struttura:
L<Locale::Po4a::TransTractor(3pm)> (particularly important to understand the
code organization), L<Locale::Po4a::Chooser(3pm)>, L<Locale::Po4a::Po(3pm)>,
L<Locale::Po4a::Common(3pm)>. Controllare anche il file F<CONTRIBUTING.md>
nell'albero dei sorgenti.

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

