Tradurre le pagine

Per rendere più semplice il lavoro dei traduttori le pagine sono generate in un modo leggermente differente da quello al quale si è normalmente abituati. Le pagine web sono generate a partire da sorgenti wml. Ci sono delle directory separate per ogni lingua.

Se si ha l'intenzione di cominciare una nuova traduzione del sito web di Debian, dare un'occhiata alla sezione su come cominciare una nuova traduzione.

Tradurre singole pagine

L'uso del WML consente di separare il contenuto di una pagina dagli elementi comuni a più pagine. Ciò significa che è necessario tradurre i sorgenti WML e non i file HTML. Bisogna usare git per ottenere i sorgenti aggiornati. Si dovrebbe effettuare il check out almeno di due directory: webwml/english/ e webwml/<lingua>/.

Per tradurre una singola pagina dall'inglese in un'altra lingua, deve essere tradotto il file .wml originale e la traduzione deve essere messa nella directory dell'altra lingua. Il percorso relativo ed il nome devono essere uguali a quelli della directory inglese per consentire ai link di funzionare.

Header della traduzione

È fortemente raccomandato che il traduttore aggiunga una riga agli header dopo l'ultima dichiarazione #use per segnalare l'esatto commit del file originale che è stato tradotto, così da rendere l'aggiornamento più facile. La riga deve essere come questa: #use wml::debian::translation-check translation="git_commit_hash" Notare che quando si utilizza lo script copypage.pl per creare il file da tradurre (operazione fortemente raccomandata), la riga con l'hash del commit git verrà creata automaticamente. L'uso di copypage.pl è spiegato in seguito.

Alcuni team di traduttori usano questa riga anche per associare ad ogni pagina web il nome del traduttore. Così il traduttore può essere avvisato automaticamente via e-mail quando viene modificata la versione inglese della pagina che mantiene e quindi deve aggiornare la sua traduzione. È sufficiente aggiungere il nome del traduttore come maintainer alla fine della riga #use come nel seguente esempio: #use wml::debian::translation-check translation="git_commit_hash" maintainer="nome del traduttore". Lo script copypage.pl creerà questa riga automaticamente nel caso in cui venga configurata la variabile d'ambiente DWWW_MAINT oppure usando l'opzione da riga di comando -m.

L'header della pagina web può essere fatto semplicemente usando lo script copypage.pl posto nella directory radice webwml. Lo script copierà la pagina al posto giusto, creando directory e makefile (se necessari) e aggiungendo automaticamente gli header richiesti. Si verrà avvisati nel caso in cui una pagina da copiare esista nel repository, o perché la pagina è stata rimossa dal repository (a causa del fatto che era troppo datata) oppure perché qualcuno ha già inviato un commit con la traduzione e la copia locale del proprio repository non è aggiornata.

Per iniziare ad usare lo script copypage.pl è necessario, come prima cosa, configurare correttamente il file language.conf nella directory principale webwml che verrà usato per stabilire in quale lingua si sta traducendo. Questo file può avere due righe: la prima con il nome della lingua (per esempio italian) e la seconda con il nome del traduttore. La configurazione della lingua può essere fatta anche tramite la variabile d'ambiente DWWW_LANG ed è possibile usare la variabile d'ambiente DWWW_MAINT per impostare il nome del traduttore, in questo modo verrà inserito automaticamente come manutentore della traduzione per la propria lingua nell'apposito campo degli header dei file wml. C'è una terza possibilità, specificare la lingua e opzionalmente il traduttore nella riga di comando -l italian -m "Paolino Paperino" e non usare il file language.conf. Vi sono altre funzionalità disponibili nello script: basta eseguirlo senza alcun argomento per ottenere la schermata di aiuto.

In altre parole dopo aver eseguito ./copypage.pl file.wml, tradurre il testo originale del file. Commenti nei file indicheranno se ci sono cose da non tradurre: vanno rispettati. Non bisogna cambiare la formattazione; se fossero necessarie correzioni esse dovrebbero essere fatte nel file originale.

Compilazione e pubblicazione della pagina

Dato che è usata la negoziazione dei contenuti, i file HTML non sono chiamati file.html ma file.<lang>.html, dove <lang> è il codice di due caratteri della lingua, in accordo con ISO 639 (p.es. it per l'italiano).

È possibile ottenere i file HTML a partire dai file WML eseguendo make file.<lang>.html. Se funziona, controllare la validità della sintassi con weblint file.<lang>.html.

Nota: le pagine web sono regolarmente ricompilate sul server www-master a partire dal sorgente wml in git; questo processo è in grado di superare la maggior parte degli errori. Comunque, se si fa il commit di un file errato al livello più alto della traduzione (p.es. il file top-level index.wml), si potrebbe interrompere il processo di compilazione e mandare in stallo tutti gli altri aggiornamenti del sito web. Bisogna porre una particolare attenzione a questi file.

Una volta che si è controllata la pagina, si può fare il commit in git. Se si hanno i permessi per farlo da soli, eseguire il push dei commit nel repository git di webwml; altrimenti, inviare il file a qualcuno con accesso in scrittura al repository.

Iniziare una nuova traduzione

Per iniziare da zero la traduzione delle pagine web Debian in una nuova lingua, mandare un'e-mail (in inglese) a [email protected].

Prima di tutto, clonare i sorgenti come descritto nella nostra pagina di introduzione a git.

Dopo aver fatto il checkout delle directory, cominciare creando una nuova directory per la traduzione, accanto ad english/ e alle altre. Il nome della directory con la traduzione deve essere in inglese ed interamente in caratteri minuscoli (p.es. "italian" non "Italiano").

Copiare i file Make.lang e .wmlrc dalla directory english/ alla nuova directory. Questi file sono indispensabili per costruire la traduzione dai file WML. Sono stati fatti in modo tale che dopo che siano stati copiati nella directory per una nuova lingua, restino solo da cambiare le seguenti cose:

La variabile LANGUAGE deve essere cambiata nel file Make.lang.
Le variabili CUR_LANG, CUR_ISO_LANG e CHARSET devono essere cambiate nel file .wmlrc. Aggiungere CUR_LOCALE a questo file se avete bisogno di fare degli ordinamenti alfabetici.
Alcune lingue potrebbero richiedere del lavoro extra per gestire un diverso insieme di caratteri. Questo può essere fatto usando le opzioni --prolog e --epilog di wml. Usare le variabili WMLPROLOG e WMLEPILOG in Make.lang per questo fine.
La variabile LANGUAGES deve essere modificata nel top-level file webwml/Makefile affinché la vostra lingua sia costruita insieme alle altre su www.debian.org. Preferiamo che sia lasciato questo particolare cambiamento ai webmaster, poiché potreste non sapere che la vostra traduzione ha dei problemi quando ne viene fatto il check out dal CVS e che potrebbe danneggiare il processo di costruzione del resto del nostro sito web.

Dopo aver fatto ciò, scrivere la seguente linea in un nuovo file chiamato "Makefile" in quella directory:

include $(subst webwml/yourlanguagedir,webwml/english,$(CURDIR))/Makefile

(Naturalmente, sostituire yourlanguagedir con il nome della directory con la traduzione).

Ora creare una subdirectory nella directory con la traduzione chiamata "po", e copiare lo stesso Makefile in quella subdirectory (cp ../Makefile .).

Nella directory po/ , eseguire make init-po per generare il set iniziale di file *.po

Ora che lo scheletro di base è pronto, si può iniziare ad aggiungere le traduzioni dei tag WML condivisi usati nei template. I primi template che dovrebbero essere tradotti sono quelli che compaiono in tutte le pagine web, come le keyword degli header, i componenti della barra di navigazione e i piè di pagina.

Iniziare la traduzione dei file in po/templates.xy.po (dove xy è il codice di due lettere della lingua). Per ogni msgid "qualcosa" c'è un msgstr "" dove si dovrebbe mettere la traduzione di qualcosa tra le virgolette dopo msgstr.

Non è necessario tradurre tutte le stringhe in tutti i file .po, solo quelle che servono nelle pagine tradotte. Per vedere se è necessario tradurre una stringa, guardare i commenti nel file .po sopra ogni dichiarazione msgid. Se il riferimento è ad un file in english/template/debian, la traduzione va fatta subito. Altrimenti può essere rimandata a quando si tradurrà la sezione di pagine web che la richiedono.

Lo scopo dei file in po/ è di rendere più facili le cose ai traduttori, in modo che non debbano (quasi) mai modificare nulla nella directory english/template/debian. Se si trova qualsiasi errore nel modo in cui qualcosa è impostato nella directory template, ci si assicuri che il problema abbia una soluzione generale (si chieda pure a qualcun altro di farlo per voi), piuttosto che inserire delle traduzioni nei template, cosa che potrebbe (quasi sempre) creare problemi maggiori.

Se non si è sicuri di fare bene qualcosa, si chieda sulla mailing list debian-www prima di fare il commit.

Nota: se pensate di dover fare qualsiasi altra modifica mandate una e-mail a debian-www specificando le modifiche e le motivazioni in modo che il problema possa essere corretto.

Dopo che anche i template sono pronti, si può iniziare con la traduzione della pagina iniziale e degli altri file *.wml. Per una lista dei file che dovrebbero essere tradotti prima, si legga Suggerimenti utili per la traduzione. Si traducano le pagine *.wml come descritto all'inizio di questa pagina.

Rimettere in uso traduzioni datate

Come descritto alla pagina Mantenere le traduzioni del sito web aggiornate, le traduzioni troppo datate vengono rimosse automaticamente dopo che è passato un certo periodo di tempo senza che vi sia stato alcun aggiornamento.

Nel caso si sia trovato un file rimosso e si vuole ripristinarlo per modificarlo, cercare nello storico dei commit con il comando standard di git.

Per esempio, se il file eliminato è eliminato.wml, eseguire la ricerca nello storico con questo comando:

   git log --all --full-history -- <percorso/al/file/eliminato.wml>

Si dovrebbe trovare l'esatto commit in cui il file è stato rimosso oltre la stringa di hash del commit. Per vedere i dettagli sulle modifiche fatte al file in questo commit è possibile usare il sottocomando git show:

  git show <COMMIT_HASH_STRING> -- <percorso/al/file/eliminato.wml>

Se il commit è esattamente quello in cui è stato rimosso il file, è possibile ripristinarlo usando git checkout:

  git checkout <COMMIT_HASH_STRING>^ -- <percorso/al/file/eliminato.wml>

Una volta fatto questo si deve, naturalmente, aggiornare il documento prima di farne di nuovo il commit. In caso contrario potrebbe essere rimosso.

Il resto della storia

Quanto scritto sopra sarà probabilmente sufficiente per iniziare. Sotto si trovano dei riferimenti a documenti contenenti spiegazioni più dettagliate ed altre informazioni utili.

Un certo numero di esempi sono forniti per farsi un'idea più chiara di come cominciare.
Parecchie domande comuni trovano risposta e suggerimenti utili nella pagina dei suggerimenti al traduttore.
Ci sono vari script nel sito per aiutare nel mantenere le traduzioni aggiornate.
Per vedere lo stato della vostra traduzione e per confronti con le altre vedere le statistiche.

Speriamo che si trovi il lavoro che abbiamo fatto utile per tradurre con facilità le pagine. Come già detto, se si hanno delle domande le si pongano pure alla mailing-list debian-www.