Provided by: po4a_0.69-1_all 
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
devi 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à è spiacevole e
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.
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
Storicamente, po4a è stato costruito attorno a quattro script, ognuno dei quali svolgeva un compito
specifico. po4a-gettextize(1) aiuta nell'avvio delle traduzioni e opzionalmente a convertire i progetti
di traduzione esistenti in po4a. po4a-updatepo(1) riporta le modifiche alla documentazione originale nei
corrispondenti file po. po4a-translate(1) crea il file sorgente tradotto dal file originale e dal
corrispondente file PO. Infine, po4a-normalize(1) è utile principalmente per eseguire il debug dei parser
po4a, poiché produce un documento non tradotto da quello originale. Rende più facile individuare i
piccoli difetti introdotti dal processo di analisi.
La maggior parte dei progetti richiede solo le funzionalità di po4a-updatepo(1) e po4a-translate(1), ma
questi script si sono dimostrati macchinosi e soggetti a errori nell'uso. Se la documentazione da
tradurre è suddivisa in più file origine, è difficile mantenere aggiornati i file PO e creare
correttamente i file di documentazione. In risposta a questo problema, è stato fornito uno strumento
omnicomprensivo: po4a(1). Questo strumento utilizza un file di configurazione che descrive la struttura
del progetto di traduzione: la posizione dei file PO, l'elenco dei file da tradurre e le opzioni da
utilizzare, automatizzando completamente il processo. Quando si esegue po4a(1), esso aggiorna i file PO e
rigenera i file di traduzione necessari. Se è tutto già aggiornato, po4a(1) non cambia alcun file.
Il resto di questa sezione fornisce una panoramica su come utilizzare l'interfaccia degli script di po4a.
La maggior parte degli utenti preferirà probabilmente utilizzare lo strumento omnicomprensivo, descritto
nella documentazione di po4a(1).
Panoramica grafica degli script po4a
Il seguente schema offre una panoramica di come ogni script po4a può essere utilizzato. Qui, 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 o simile); i traduttori si occuperanno principalmente del file PO, mentre gli
utenti finali vedranno solo il file XX.doc.
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-updatepo] |
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-translate]
|
V
XX.doc
(aggiornato)
Questo schema è complicato, ma in pratica solo la parte destra (che coinvolge po4a-updatepo(1) e
po4a-translate(1)) viene utilizzata, una volta impostato e configurato il progetto.
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 po4a-updatepo(1). 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-translate(1) 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.
Come notato prima, il programma po4a(1) combina gli effetti degli script separati, aggiornando i file PO
e il documento tradotto in un'unica esecuzione. La logica sottostante rimane la stessa.
Iniziare una nuova traduzione
Se usa po4a(1), non esiste un passaggio specifico per avviare una traduzione. Bisogna solo elencare le
lingue nel file di configurazione e i file PO mancanti verranno creati automaticamente. Naturalmente, il
traduttore deve quindi fornire le traduzioni per ogni contenuto usato nei documenti. po4a(1) crea anche
un file POT, che è un file modello PO. I potenziali traduttori possono tradurre il progetto in una nuova
lingua rinominando questo file e fornendo le traduzioni nella propria lingua.
Se preferisce usare i singoli script separatamente, bisognerebbe usare po4a-gettextize(1) come segue per
creare il file POT. Questo file potrà quindi essere copiato in XX.po per iniziare una nuova traduzione.
$ po4a-gettextize --format <formato> --master <master.doc> --po <traduzione.pot>
Il documento master viene utilizzato in ingresso, mentre il file POT è l'uscita di questo processo.
Integrazione delle modifiche al documento originale
Lo script da usare per questo è po4a-updatepo(1) (fare riferimento alla sua documentazione per i
dettagli):
$ po4a-updatepo --format <formato> --master <nuovo_master.doc> --po <vecchio_doc.XX.po>
Il documento master viene usato in ingresso, mentre il file PO viene aggiornato: viene utilizzato sia in
ingresso che in uscita.
Generazione di un documento tradotto
Una volta finito con la traduzione, si può voler prendere la documentazione tradotta e distribuirla agli
utenti con quella originale. A questo scopo, usare il programma po4a-translate(1) in questo modo:
$ po4a-translate --format <format> --master <master.doc> --po <doc.XX.po> --localized <XX.doc>
Sia il file master che PO vengono usati in ingresso, mentre il file localizzato (tradotto) è il file in
uscita di questo processo.
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 istruire
po4a che una sezione inizia con una riga contenente il tag "<section">. Questo è 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. Quindi 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, in modo che vi possiate
sentire a vostro agio se desiderate aiutarci nella manutenzione e 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.
L'architettura po4a è object oriented. La classe Locale::Po4a::TransTractor(3pm) è 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 omette il file PO in ingresso e il
documento in uscita, si ottiene po4a-gettextize. Se si fornisce entrambi gli ingressi e si ignora il file
PO in uscita, si ottiene po4a-translate. po4a chiama TransTractor due volte e chiama msgmerge -U tra
queste invocazioni di TransTractor per fornire una soluzione tutta in uno con un singolo file di
configurazione. Vedere Locale::Po4a::TransTractor(3pm) per ulteriori dettagli."
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.
• 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 :)
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>
Strumenti Po4a 2023-01-03 PO4A(7)