po4a - framework per la traduzione di documentazione e altro materiale
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.
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.
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.
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).
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.
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.
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.
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.
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
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."
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>
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 :)
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.
- •
- 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.
- •
- 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.
Denis Barbier <barbier,linuxfr.org>
Martin Quinson (mquinson#debian.org)
Danilo Piazzalunga <[email protected]>
Marco Ciampa <[email protected]>