[Docs] Tradurre in Italiano la documentazione di Python. Una proposta.

[Riccardo Polignieri]

Dopo aver terminato il mio libro, ho avuto qualche ora di tempo per riprendere
in mano questa cosa e fare una prima ricognizione del lavoro effettivo da fare.

Nell'astronomicamente improbabile ipotesi che qualcuno sia sempre interessato,
registro qui i progressi che sto facendo...

Per prima cosa, mi sono "accorto" che la documentazione di Python comprende
ormai quasi 500 file .rst, che sarebbero ovviamente da tradurre... gulp!
Questo mi convince sempre più del fatto che occorre seguire quanto più
possibile da vicino gli strumenti e i formati dell'orginale... ovvero
Sphinx, Sphinx e ancora Sphinx. Con una mole di lavoro così enorme, non
possiamo permetterci il lusso di inventarci anche un altro modo di
renderizzare/pubblicare, con tutto il pasticcio di adattamento tra formati
che ne seguirebbe.

Quindi, per cominciare la ricognizione, ho cercato di capire se è facile
fare una build della documentazione con Sphinx, con tutte le impostazioni e le
estensioni usate nell'originale (ovvero, produrre sul mio computer le stesse
identiche pagine di docs.python.org).

La risposta è che... non è facile quando avrei voluto, perché ci sono un paio di
hack manuali (al limite del baco vero e proprio... infatti spero che almeno uno
prima o poi lo correggano) legati ad alcune estensioni Sphinx, che non sono
replicabili tali-e-quali.
Comunque ho sistemato abbastanza facilmente questi problemucci, e alla fine sono
riuscito ad automatizzare un processo di build senza troppa fatica.

(Resta ancora, a dire il vero, un problema legato al modo peculiare in cui la
build dell'originale pesca le NEWS, ovvero ciò che si vede in
docs.python.org/3/whatsnew/changelog.html. Si vedrà in futuro...)

Dopo di che, mi sono messo a studiare il modo di tener traccia dello stato di
aggiornamento di ciascun file dell'originale (file per file!), usando ovviamente
i commit di Git come riferimento. Ciascun file riporterà un "synctag" (come
l'ho chiamato) che indica con precisione il commit e la data dell'originale
*al momento in cui è stata fatta la traduzione*.
Ho scritto una utility che consente (file per file) di vedere di quanti commit
l'originale è andato avanti rispetto al synctag riportato nella traduzione, e
fare un "git diff" comodo per aggiornare la traduzione.

Anche qui ci sono dei dettagli tecnici fastidiosi... per esempio il fatto che ci
sono anche molti file non-rst (immagini, moduli python di esempio etc.) che non
possiamo marcare con un synctag. Per questi ho dovuto fare un registro separato,
e una utility che lo mantiene aggiornato.

In tutto questo, ho anche dato un'occhiata alla possibilità di usare il sistema
di I18N di Sphinx (basato su gettext) per fare le traduzioni... vedi
https://www.sphinx-doc.org/en/master/usage/advanced/intl.html
Ma in realtà mi sono convinto presto che è solo un mal di testa... le stringhe
di gettext non si adattano bene ai documenti .rst, e si crea solo confusione.

Alla fine l'unica soluzione resta di tradurre file per file, facendo attenzione
a mantenere la sintassi .rst dell'originale senza rompere i link etc.
La buona notizia è che, adesso, credo di sapere tecnicamente come strutturare
il processo di traduzione (e aggiornamenti futuri) senza troppe complicazioni
per chi traduce.


Tutto questo adesso sta in una repository sul mio computer, che non ho ancora
pubblicato su GitHub perché adesso voglio staccare per qualche giorno e poi
rivedere il lavoro a mente fresca per capire se mi convince ancora...

Sto anche scrivendo un bel po' di documentazione su tutti questi aspetti, ma
non dovrebbe essere troppo difficile.

In sostanza sarei (quasi) pronto a partire con le traduzioni vere e proprie...

...e qui ovviamente si fermerà tutto, beninteso, per mancanza globale totale
di interesse. Ma almeno la proof of concept ci sarà, e sarà funzionante.



On 9/5/2020 9:48 PM, Riccardo Polignieri wrote:
> # Tradurre in Italiano la documentazione di Python.
> (...)