Provided by: po4a_0.73-2ubuntu1_all bug

NOME

       po4a - framework per la traduzione di documentazione e altro materiale

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.

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.

       L'obiettivo del progetto po4a è facilitare il lavoro dei traduttori di documentazione. In
       particolare, rende le traduzioni della documentazione 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 FAQ più avanti in questo documento per avere un elenco completo di vantaggi
       e svantaggi di questo approccio.

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

       man (parser maturo)
           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 Locale::Po4a::Man(3pm) supporta anche il formato mdoc, usato dalle pagine
           man BSD (sono anche abbastanza comuni su Linux).

       AsciiDoc (parser maturo)
           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 Locale::Po4a::AsciiDoc per i dettagli.

       pod (parser maturo)
           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 Locale::Po4a::Pod per i dettagli.

       sgml (parser maturo)
           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 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 Locale::Po4a::Sgml(3pm) per i dettagli.

       TeX / LaTeX (parser maturo)
           Il formato LaTeX è un formato di documentazione importante usato dal mondo del Free
           Software e da diverse pubblicazioni.

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

       text (parser maturo)
           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 Locale::Po4a::Text(3pm)
           per i dettagli.

       xml e XHMTL (parser probabilmente maturo)
           Il formato XML è un formato base per molti formati di documentazione.

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

       BibTex (parser probabilmente maturo)
           Il formato BibTex viene usato assieme a LaTex per la formattazione di elenchi di
           riferimenti bibliografici.

           Consultare Locale::Po4a::BibTex per i dettagli.

       Docbook (parser probabilmente maturo)
           Un linguaggio a marcatori basato su XML che usa etichette semantiche per descrivere i
           documenti.

           Consultare Locale::Po4a:Docbook per ulteriori dettagli.

       Guide XML (parser probabilmente maturo)
           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 Locale::Po4a:Guide per maggiori dettagli.

       Wml (parser probabilmente maturo)
           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 Locale::Po4a::Wml per maggiori dettagli.

       Yaml (parser probabilmente maturo)
           Un soprainsieme di JSON, YAML viene spesso usato per progetti sistemistici o per
           configurazione. YAML è centrale per il sistema di Red Hat Ansible.

           See Locale::Po4A::Yaml for greater details.

       RubyDoc (parser probabilmente maturo)
           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 Locale::Po4a::RubyDoc per maggiori dettagli.

       Halibut (parser probabilmente 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 Locale::Po4a:Halibut per maggiori dettagli.

       Ini (parser probabilmente sperimentale)
           Formato di file di configurazione reso popolare da MS-DOS.

           Consultare Locale::Po4a::Ini per maggiori dettagli.

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

       gemtext (parser molto sperimentale)
           Il formato di testo normale nativo del protocollo Gemini. Solitamente si usa
           l'estensione ".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à.

       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+(Locale::Po4a::KernelHelp), oppure i diagrammi prodotti dal programma
           Dia(Locale::Po4a::Dia). Aggiungere un nuovo formato è spesso molto facile e il grosso
           del lavoro è produrre un parser per il formato scelto. Per maggiori informazioni su
           questo argomento, consultare Locale::Po4a::TransTractor(3pm).

       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.

Uso di po4a

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

   Schema dettagliato del flusso di lavoro di po4a
       Assicurati di leggere 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, master.doc è un nome di esempio per la documentazione da tradurre;
       XX.doc è lo stesso documento tradotto nella lingua XX mentre doc.XX.po è il catalogo di
       traduzione per quel documento nella lingua XX. Gli autori della documentazione si
       occuperanno principalmente di 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 XX.doc.

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

                                          master.doc
                                              |
                                              V
            +<-----<----+<-----<-----<--------+------->-------->-------+
            :           |                     |                        :
       {traduzione}     |       {aggiornamento di master.doc}          :
            :           |                     |                        :
          XX.doc        |                     V                        V
        (opzionale)     |                 master.doc ->-------->------>+
            :           |                  (nuovo)                     |
            V           V                     |                        |
         [po4a-gettextize]  doc.XX.po -->+    |                        |
                 |          (vecchio)    |    |                        |
                 |              ^        V    V                        |
                 |              |  [po4a aggiorna i po]                |
                 V              |           |                          V
          translation.pot       ^           V                          |
                 |              |       doc.XX.po                      |
                 |              |        (fuzzy)                       |
           {traduzione}         |           |                          |
                 |              ^           V                          V
                 |              |   {modifica manuale}                 |
                 |              |           |                          |
                 V              |           V                          V
             doc.XX.po --->---->+<---<-- doc.XX.po    addendum     master.doc
             (iniziale)                (aggiornato)  (opzionale)  (aggiornato)
                 :                          |            |             |
                 :                          V            |             |
                 +----->----->----->------> +            |             |
                                            |            |             |
                                            V            V             V
                                            +------>-----+------<------+
                                                         |
                                                         V
                                            [po4a aggiorna le traduzioni]
                                                         |
                                                         V
                                                       XX.doc
                                                    (aggiornato)

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

       La parte sinistra mostra come 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 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 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 GNOME Translation Editor, Lokalize di
       KDE o poedit o utilizzando una piattaforma di traduzione sul web come weblate o 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 po4a crea un documento sorgente tradotto dal
       documento originale master.doc e il catalogo di traduzioni 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, po4a aggiorna sia i file delle traduzioni che i documenti tradotti
       automaticamente.

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

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

   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 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 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 PO4A-HEADER:, seguita da un elenco
       separato da punti e virgola di campi chiave=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 "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 "position" (può essere un'espressione regolare). Non bisogna
       dimenticare che qui po4a considera il documento tradotto. 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 "position" (posizione) nel documento di destinazione, po4a cerca la
       riga successiva dopo la "position" che corrisponde al "endboundary" fornito. L'addendum
       viene aggiunto subito after (dopo) quella riga (perché abbiamo fornito una 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 "<section"> dopo la riga che corrisponde a
       "About this document" nella traduzione e aggiunge l'addendum before (prima) quella riga
       poiché abbiamo fornito un 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 "About this document" e indica a po4a che una sezione inizia con una
       riga contenente il tag "<section>". Ciò è equivalente all'esempio precedente perché quello
       che si vuole veramente è aggiungere questo addendum dopo "</section>" o prima di
       "<section>".

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

         Modo   | Tipo confine  |     Confine usato       | Punto di inserimento rispetto al confine
        ========|===============|=========================|=========================================
        'before'| 'endboundary' | ultimo prima 'position' | Subito dopo del confine selezionato
        'before'|'beginboundary'| ultimo prima 'position' | Subito prima del confine selezionato
        'after' | 'endboundary' |  primo dopo 'position'  | Subito dopo del confine selezionato
        'after' |'beginboundary'|  primo dopo 'position'  | Subito prima del confine selezionato
        'eof'   |   (nessuno)   |           -             | Fine del file

       Suggerimenti e trucchi sugli addenda

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

       •   Gli spazi bianchi SONO importanti nel contenuto di "position" e dei confini. Quindi le
           due righe seguenti 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>

       •   Sebbene questa ricerca di contesto possa essere considerata come operante
           approssimativamente su ciascuna riga del documento 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 punto di inserimento dell'addendum deve essere prima o
           dopo la stringa dati interna e non può essere all'interno della stessa.

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

       Esempi di addenda

       •   Se si vuole aggiungere qualcosa dopo la seguente sezione nroff:

             .SH "AUTHORS"

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

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

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

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

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

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

       Esempio più dettagliato

       Documento originale (formattato POD):

        |=head1 NOME
        |
        |dummy - un programma fantoccio
        |
        |=head1 AUTORE
        |
        |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 beginboundary "/^=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 mode=before:

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

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.

   TransTractors e l'architettura del progetto
       Al centro del progetto po4a c'è la classe Locale::Po4a::TransTractor(3pm) che è l'antenato
       comune di tutte le classi 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ò:

          Documento in ingresso --\                            /---> Documento in uscita
                                   \      TransTractor::      /         (tradotto)
                                   +-->--   parse()  --------+
                                   /                          \
          PO in ingresso ---------/                            \---> PO in uscita
                                                                      (estratto)

       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 po4a-translate. Se si tralascia il
       documento in uscita invece, si ottiene po4a-updatepo. po4a usa TransTractor una prima
       volta per ottenere un file POT in uscita aggiornato (ignoranto i documenti in uscita),
       chiama 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,
       po4a fornisce una soluzione tutta in uno per aggiornare ciò che serve, usando un singolo
       file di configurazione.

       Anche 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 po4a-gettextize(1).

   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 TransTractor::shiftline(), accumulano il contenuto dei paragrafi o altro. Una
       volta che una stringa è stata completamente analizzata, il parser utilizza
       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 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 TransTractor::translate() e
       "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
       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 Pod::read() e 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à "<:encoding($charset)"
       che viene passata alla funzione perl open().

   Oggetti po
       La classe Locale::Po4a::Po(3pm) è incaricata di caricare e utilizzare i file PO e POT.
       Fondamentalmente, si può leggere un file, aggiungere voci, ottenere traduzioni con il
       metodo 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 msgmerge
       e msgfmt.

   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.

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

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

       •   apt (man, docbook): gestore pacchetti Debian.

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

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

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

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

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

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

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

FAQ

   Come si pronuncia po4a?
       Personalmente lo pronuncio come 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 :)

   Perché gli script singoli sono deprecati?
       In effetti, po4a-updatepo e po4a-translate sono deprecati in favore di po4a. Il motivo è
       che dato che 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
       po4a è lungo 1200 righe, quindi fanno molto in aggiunta alle parti interne comuni. La
       duplicazione del codice provoca bug che si verificano 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 po4a e
       l'altro 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
       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 po4a-updatepo e 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.

   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.

       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.

       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.

       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.

       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.

       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.

   SOMMARIO dei vantaggi dell'approccio basato su gettext
       • Le traduzioni non vengono memorizzate insieme all'originale, il che rende possibile
         rilevare se le traduzioni diventano obsolete.

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

       • È basato internamente su gettext (ma 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.

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

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

       • 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/

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

       • Gli addenda sono strani ad una prima occhiata.

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

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

VEDERE ANCHE

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

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

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

       •   I parser di ogni formato, in particolare per vedere le opzioni accettate da ognuno di
           essi: Locale::Po4a::AsciiDoc(3pm) Locale::Po4a::Dia(3pm), Locale::Po4a::Guide(3pm),
           Locale::Po4a::Ini(3pm), Locale::Po4a::KernelHelp(3pm), Locale::Po4a::Man(3pm),
           Locale::Po4a::RubyDoc(3pm), Locale::Po4a::Texinfo(3pm), Locale::Po4a::Text(3pm),
           Locale::Po4a::Xhtml(3pm), Locale::Po4a::Yaml(3pm), Locale::Po4a::BibTeX(3pm),
           Locale::Po4a::Docbook(3pm), Locale::Po4a::Halibut(3pm), Locale::Po4a::LaTeX(3pm),
           Locale::Po4a::Pod(3pm), Locale::Po4a::Sgml(3pm), Locale::Po4a::TeX(3pm),
           Locale::Po4a::Wml(3pm), Locale::Po4a::Xml(3pm).

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

AUTORI

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

TRADUZIONE

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