I file da tradurre

Per quanto riguarda i file da tradurre, chi vuole collaborare dovrà per prima iscriversi alla cosa mailing list dedicata (docs@lists.python.it) ed annunciare la buona notizia.

Sulla lista gli verranno indicati i documenti e le porzioni di documenti che non sono già stati presi in consegna.

Nota:

per facilitare questo tipo di coordinazione esiste il file
http://svn.python.it/admin/trunk/translation_status.xml
in cui viene mantenuta aggiornata la situazione.

Una volta scelto cosa tradurre, l'interessato può scaricare il documento dal repository (con un semplice browser) e tradurre la parte assegnatagli (usando un qualsiasi editor di testo).

Finita infine la traduzione, il documento può essere inserito nel repository (se si ha l'accesso in scrittura) o passato alla lista (docs@lists.python.it) annunciandolo.

Convenzioni generali

Per la traduzione si usa l'impersonale oppure, a seconda dei casi, il "Voi", ovvero la seconda persona plurale.

Glossario

Durante la traduzione tenere sempre a portata di mano il glossario che racchiude le traduzioni adottate per una serie di termini, disponibile all'indirizzo http://svn.python.it/admin/trunk/docs/glossario.xml

Questo documento viene aggiornato (segnalandolo in docs@lists.python.it) ogni qual volta si presentino dubbi di traduzione/interpretazione di vari termini presenti nella documentazione. Siate sicuri di avere sempre la versione aggiornata!

Codice nel testo

L'eventuale codice riscontrato nel documento si lascia intatto, si traducono i commenti (solitamente contraddistinti anteponendovi il carattere "#" o """testo testo """) e le stringhe di testo.

def buildConnectionString(params):
    """Build a connection string from a dictionary of parameters.

       Returns string.""" (COMMENTO)

    return ";".join(["%s=%s" % (k, v) for k, v in params.items()])

 if __name__ == "__main__":
     myParams = {"server":"mpilgrim", \
                 "database":"master", \
                 "uid":"sa", \
                 "pwd":"secret" \
                 }

print buildConnectionString(myParams) # blah, blah (COMMENTO)

Dubbi nella traduzione

Se trovate passi nel testo che non sapete come tradurre evidenziatemeli sulla mailing list, ma anche nel testo, magari con un po' di asterischi tipo:

******** blah, blah, blah ******

Editor e codifiche

Potete usare qualunque editor di testi, da Emacs a Joe o anche qualsiasi altro sotto X, Kedit, kate, Gnotepad+, gedit insomma, cosa vi pare.

L'unica raccomandazione è, su Windows, usare almeno Wordpad invece che Notepad.

Per quanto riguarda la codifica, quella ufficiale è latin1 (ISO-8859-1), con convenzioni di fine riga UNIX (\n)

Gli utenti Windows dovranno prestare particolare attenzione all'editor usato, in modo che non modifichi il separatore di riga.

Per quanto riguarda l'encoding, quello usato (cp1252) è coincide praticamente con latin1, a parte, in particolare, nel supporto per l'euro.

Gli utenti Unix/Linux/Posix dovranno invece fare attenzione al locale installato. E' probabile che questo sia l'ISO-8859-15 (latin1 + euro), nel qual caso è accettabile.

In taluni casi, tuttavia, può essere installato un locale con UTF-8, nel qual caso basterà configurare l'editor usato o, al limite, riconvertire il documento con il programma recode.

Per chi non ha dimestichezza con XML, SGML, LaTeX ecc. dovete sapere che ad esempio scrivere:

<TAG-PARAGRAFO>
  pippo      pluto
      topolino

   minni
</TAG-PARAGRAFO>

sarà sempre visualizzato come:

pippo pluto topolino minni

XXX TODO: aggiungere info riguardo TeX, XML e reStructuredText

Codifica e tastiera

Per chi usa la tastiera italiana usate tranquillamente le accentate, anzi se potete usatele!!!

XXX TODO approfondire meglio questo punto.

Per chi usa la tastiera americana usate, per esempio per la lettera "è"="e'" ecc. ecc.

Poi me la vedo io con somma gioia da parte vostra :-)

Per tutti, non mettetemi porcate tipo la "E" accentata, poi in console magari non la vedo, la sostituisco con "E'" per poi convertirla con uno script e alla fine mi trovo errori inspiegabili...

Ultime considerazioni

Tutte queste considerazioni riportate in questo documento sono utili a mantenere una coerenza nella gestione della documentazione per perseguire i seguenti obiettivi: - mantenere un'uniformità di stile nella traduzione della documentazione (per questo è importante tradurre bene oppure chiedere aiuto sulla lista docs@lists.python.it in caso di anche semplici dubbi...esiste per questo!); - semplificare ed alleggerire il più possibile la gestione della documentazione; - rendere più rapida la migrazione della documentazione da una versione di Python alla successiva; - grazie ai precedenti obiettivi riuscire a ritagliare tempo per implementare nuove sezioni che possano essere di aiuto a tutti gli utenti di Python.

Controllo dei documenti

Prima di effettuare un commit, il documento va sempre controllato. In particolare che l'encoding usato sia valido e che, se possibile, compili senza problemi.

Coordinazione traduzioni

Per agevolare il coordinamento delle traduzioni, è stato creato il documento http://svn.python.it/admin/trunk/translations_status.xml.

In questo documento è possibile sapere chi sta traducendo cosa. In caso di aggiornamenti, comunicare la cosa al responsabile mailto:docs@python.it, il quale provvedere ad aggiornare tale documento.

Messaggi di log

E' utile mantenere una convenzione uniforme riguardo i messaggi di log usati in un commit.

Innanzitutto faccio notare che tali messaggi non sono sotto controllo versione, quindi in caso di errori è abbastanza scomodo andare a fare delle correzioni.

Come spiegato anche nel manuale di Subversion nel messaggio di log non vanno inseriti tutti i dettagli, per questo ci sono i diff. Vanno inserite solo le informazioni essenziali come:

chi ha tradotto la parte del documento quale parte è stata tradotta

XXX TODO: aggiungere altre informazini.