[Docs] inizio lavori di traduzione

Lun 30 Lug 2007 22:09:36 CEST

Salute a tutti.

Approfittando del rinato interesse per python.it, invio questo messaggio 
  per far partire i lavori di traduzione.

C'è molto da fare, e cercherò di riassumere i vari punti qui, ma 
conviene iniziare a fare qualcosa piuttosto che discutere sul come fare 
cosa.

Le cose da fare ci sono, e anche gli strumenti.

Nota: questo messaggio cercherò di inserirlo anche nel wiki.

Riassunto stato lavori
======================
Su python.it tutti i documenti sono su un repository Subversion, 
all'indirizzo http://svn.python.it/.

In ciascuna delle directory principali c'è un file LEGGIMI che cerca di 
spiegare cosa c'è in quella directory.

I documenti da tradurre sono suddivisi in quelli ufficiali Python e gli 
altri contributi.

I primi si trovano in http://svn.python.it/python/, tra cui ci sono, in 
particolare:

* peps
* documentazione ufficiale
* faq
* howto

Di questi la grande maggioranza è stata tradotta.
In particolare le FAQ sono state anche inserite su python.org.

Nei contributi ci sono invece diversi articoli e guide, tutti tradotti.
In particolare, però, Dive into Python va aggiornato (inoltre, questo 
documento si trova anche nel sito ufficiale di dive into python).

Un primo compito da fare, è un controllo di tutto quello fatto 
(purtroppo è passato diverso tempo ed io non ricordo più tutti dettagli).

Dettagli strumenti per le traduzioni
====================================

Il principale strumento per le traduzioni è il repository Subversion, 
dove tutti i documenti sono stati inseriti cercando di mettere ordine.

Per ogni documento tradotto, nel repository è inserito il documento 
originale.

Inoltre, poi, per ciascun "manuale" che ha diverse versioni, ciascuna 
versione è stata inserita in un tag (se completa).

In branches si trovano le versioni in sviluppo, in trunk la versione 
attuale pronta per il review.

Sempre come supporto alle traduzioni, ho scritto alcuni script più file 
XML di controllo, che trovate su:
http://svn.python.it/admin/trunk/

Il file http://svn.python.it/admin/trunk/authors.xml riporta tutti i 
traduttori che hanno partecipato alle traduzioni.

Questo file è *molto* importante, perchè tiene traccia delle versioni 
usate nelle traduzioni (ad esempio per capire se le FAQ ufficiali sono 
state aggiornate).

Il file http://svn.python.it/admin/trunk/translations_status.xml è in 
*cuore* del sistema, in quanto riporta chi sta traducendo cosa.

A giorni aggiungerò un nuovo files authors_list.xml, con la lista di 
tutti i traduttori "ufficiali".

NOTA:
   non c'è nessuna interfaccia utente ad alto livello, ma non credo che
   sia necessario.
   Qualcuno mi ha suggerito Launchpad, ma per ora magari lasciamo
   perdere.

In http://svn.python.it/admin/trunk/docs/ si trovano dei documenti che 
illustrano il processo di traduzione.
Inoltre qui si trova il glossario dei termini.

Il glossario è in XML, con un foglio di stile per visualizzarlo.
Occorre qualche volontario che tenga aggiornato il glossario!

NOTA:
   un problema da risolvere è come copiare questi files nel sito web, al
   posto giusto

Script di supporto per le traduzioni
====================================

Sempre per facilitare i lavori di traduzione, ho sviluppato alcuni 
script in http://svn.python.it/admin/trunk/scripts/

Gli script servono per due compiti:
1) Suddividere un nuovo file da tradurre in N righe uguali, in modo da
    suddividere il lavoro.

    Vedi, ad esempio: 
http://svn.python.it/python/python/Doc/branches/2.4.3/lib/libdecimal.tex

2) Riportare nella versione A della traduzione, le modifiche che ci sono
    state nel passaggio dalla versione A alla versione B del documento
    originale.

    Vedi ad esempio:
http://svn.python.it/python/python/Doc/branches/2.4.3/lib/asttable.tex
    (che è stato anche aggiornato)

    oppure:
http://svn.python.it/python/python/Doc/branches/2.4.3/lib/libstringio.tex

Al momento stavamo passando dalla versione 2.3.4 alla 2.4.3 (con qualche 
documento già aggiornato).

Devo un attimo verificare se siamo in grado di recuperare quanto già 
tradotto per il passaggio alla versione 2.5 (non è comunque una cosa 
semplice, quindi è meglio *completare* una versione).

Gli script servono semplicemente per evitare un noioso lavoro manuale, e 
ci sono ancora alcuni piccoli problemi da risolvere (in particolare, lo 
script per calcolare i diff assume che sia il documento originale che 
quello tradotto abbiamo lo stesso numero di "paragrafi".
Non sempre è così, in particolare a volte la cosa è dovuta ad errori 
nella precedente traduzione (alcuni li avevo corretti, ora non ricordo 
più).

L'output degli script, in particolare quello per il diff, è un pò rozzo, 
ma non mai avuto la voglia di perfezionarlo (dato che non avevo feedback).

Gestione branching per le traduzioni
====================================

Per i manuali che hanno diverse versioni, come la libreria standard, 
ogni versione ha il suo branch ed il suo tag una volta terminata.

La versione corrente della libreria standard (al momento la 2.3.4) si 
trova nel branch.

Supponiamo di voler passare alla 2.5.
Il procedimento è il seguente:

   * Copia del trunk nel branch 2.5
   * Lancio dello script update-version.py nel branch.

     Questo script copia tutti i file aggiunti nella versione originale,
     e li suddivide in N parti con equal numero di linee.
     Inoltre trova i punti in cui sono stati modificati i vari files.

A questo punto tutto quello che resta da fare è controllare l'output di 
update-version.py, che si trova in
http://svn.python.it/admin/branches/updates/

Il coordinatore, quindi andrà alla ricerca dei traduttori disponibili, e 
terrà aggiornarto il file translations_status.xml

Cosa tradurre
=============

Per iniziare direi di aggiornare il tutorial ufficiale alla versione 2.5.
Dovrebbe essere abbastanza semplice.

In seguito passiamo alla libreria standard, e alle FAQ (che devono 
essere revisionate, e aggiornate).

Sarebbe interessante poter aggiornare Dive into Python, anche perchè, 
come le FAQ, il risultato finale può essere messo su un sito separato.

Il problema è che Dive into Python è scitto in un brutto XML (leggi: non 
scritto da un umano) e quindi il mio script non funziona.

Magari si può fare qualcosa con xmldiff, da verificare.

Tutte le altre traduzioni, sono già state fatte, ed i documenti non 
credo siano stati aggiornati dagli autori originali.

Dettagli traduzione documentazione standard
===========================================

La traduzione della documentazione è senz'altro il più grande regalo che 
ci hanno fatto i nostri predecessori.

Credo che siamo gli unici (come nazione) ad avere tradotto quasi tutta 
la documentazione di Python.

Un mio sogno è far includere la nostra traduzione nel sito ufficiale di 
python.org.

Comunque, riguardo la documentazione standard, ci sono delle novità recenti.

Al momento, la documentazione è scritta in LateX ed diversi strumenti 
per il build soo scritti in Perl.

Questo approccio ha diversi problemi, e quindi il mantenitore della 
documentazione standard ha sviluppato 'sphinx', che permette di gestire 
la documentazione in reStructuredText, più altri bonus.

Una questione critica da decidere è se passare a sphinx fin da subito 
per Python 2.5, oppure aspettare la versione originale, che verrà 
aggiornata in Python 2.6.

Io sono per restare al metodo attuale, o almeno vedere che feedback 
riceviamo con la traduzione del tutorial.

Un'altra questione da decidere, è se inserire la versione "di lavoro" 
delle traduzioni sul sito, in modo da ricevere feedback immediato, 
oppure se aspettare di avere concluso i lavori.

Infine va anche predisposto il sito per il dominio
docs.python.it, e per gestire gli archivi delle traduzioni.

Per ora questo è tutto, non mi viene in mente altro.
Spero di non avervi annoiato (non pensavo di riuscire a scrivere tutta 
questa roba :)).

Manlio Perillo