Manuale del traduttore/revisore

Da Wiki di NetBSD Italia.

(Differenze fra le revisioni)
m (Configurazione di Vi/Vim)
m (Bot: Sostituzione automatica (-a'([^']|$) +à\1))
Riga 15: Riga 15:
Il metodo piu' rapido per iscriversi al progetto NetBSDit-docs ottenendo cosi' accesso
Il metodo piu' rapido per iscriversi al progetto NetBSDit-docs ottenendo cosi' accesso
in scrittura per il repository CVS in modo da poter pubblicare eventuali modifiche alla
in scrittura per il repository CVS in modo da poter pubblicare eventuali modifiche alla
-
documentazione, sara' sufficiente contattare il team di [[NetBSD Italia]] inviando una
+
documentazione, sarà sufficiente contattare il team di [[NetBSD Italia]] inviando una
email di richiesta (posibilmente con una breve lista dei documenti che sui quali si
email di richiesta (posibilmente con una breve lista dei documenti che sui quali si
desidera lavorare) a [[Utente:Claudio|Claudio M. Alessi]], [[Utente:leot|Leonardo Taccari]] oppure
desidera lavorare) a [[Utente:Claudio|Claudio M. Alessi]], [[Utente:leot|Leonardo Taccari]] oppure
Riga 21: Riga 21:
[http://mail-index.netbsd.org/netbsd-docs-it/tindex.html NetBSD-Docs-it]. In alternativa
[http://mail-index.netbsd.org/netbsd-docs-it/tindex.html NetBSD-Docs-it]. In alternativa
si puo' accedere al canale '''#NetBSD-it@Freenode''' per parlare direttamente con i membri
si puo' accedere al canale '''#NetBSD-it@Freenode''' per parlare direttamente con i membri
-
della comunita'. In questo caso si prega di non essere ''troppo'' formali :-)
+
della comunità. In questo caso si prega di non essere ''troppo'' formali :-)
== Scelta degli argomenti ==
== Scelta degli argomenti ==
Prima di cominciare a tradurre un documento e' buona norma verificare che questo sia
Prima di cominciare a tradurre un documento e' buona norma verificare che questo sia
-
disponibile per la traduzione. Infatti, qualcun altro potrebbe essere gia' impegnato
+
disponibile per la traduzione. Infatti, qualcun altro potrebbe essere già impegnato
-
nella traduzione di un determinato argomento o questo potrebbe essere gia' stato tradotto.
+
nella traduzione di un determinato argomento o questo potrebbe essere già stato tradotto.
Di norma comunque, i documenti tradotti (o in fase di traduzione) vengono mantenuti quanto
Di norma comunque, i documenti tradotti (o in fase di traduzione) vengono mantenuti quanto
piu' aggiornati possibile sul repository CVS.
piu' aggiornati possibile sul repository CVS.
Riga 40: Riga 40:
I file necessari per lavorare a una traduzione si possono ottenere direttamente dai
I file necessari per lavorare a una traduzione si possono ottenere direttamente dai
repository ufficiali del progetto [http://netbsdit.docs.sf.net NetBSDit-docs]. Per
repository ufficiali del progetto [http://netbsdit.docs.sf.net NetBSDit-docs]. Per
-
ottenere la guida di NetBSD, che attualmente e' quella con maggiore priorita' nella
+
ottenere la guida di NetBSD, che attualmente e' quella con maggiore priorità nella
lista delle [[traduzioni]], eseguire il comando:
lista delle [[traduzioni]], eseguire il comando:
  $ cvs -d :pserver:anonymous@netbsdit-docs.cvs.sf.net:/cvsroot/netbsdit-docs -P netbsd/guida
  $ cvs -d :pserver:anonymous@netbsdit-docs.cvs.sf.net:/cvsroot/netbsdit-docs -P netbsd/guida
-
In questo modo verra' creata la directory ''netbsd'' contenente tutti i file XML (tradotti
+
In questo modo verrà creata la directory ''netbsd'' contenente tutti i file XML (tradotti
e non) della guida ufficiale, ''The NetBSD Guide'', i quali potranno essere modificati per
e non) della guida ufficiale, ''The NetBSD Guide'', i quali potranno essere modificati per
effettuare successivamente (ed eventualmente) un ''commit'' sul repository CVS.
effettuare successivamente (ed eventualmente) un ''commit'' sul repository CVS.
Riga 88: Riga 88:
==== Configurazione di Vi/Vim ====
==== Configurazione di Vi/Vim ====
-
Fra le varie funzionalita', l'editor vi (e derivati) offre la possibilita' di rimpiazzare
+
Fra le varie funzionalità, l'editor vi (e derivati) offre la possibilità di rimpiazzare
automaticamente del testo al momento in cui lo si digita. Questo risulta molto utile quando
automaticamente del testo al momento in cui lo si digita. Questo risulta molto utile quando
si lavora su documenti in cui alcuni caratteri vanno rimpiazzati praticamente sempre. Anziche'
si lavora su documenti in cui alcuni caratteri vanno rimpiazzati praticamente sempre. Anziche'
[[#Utilizzare un editor in-line|utilizzare un editor in-line]] '''dopo''' la stesura del testo
[[#Utilizzare un editor in-line|utilizzare un editor in-line]] '''dopo''' la stesura del testo
e' conveniente farlo durante il processo di traduzione risparmiando un po' tempo. Su vi tutto
e' conveniente farlo durante il processo di traduzione risparmiando un po' tempo. Su vi tutto
-
quello che bisogna fare e' ''mappare'' ogni singolo rimpiazzo eseguendo in modalita' ''comando''
+
quello che bisogna fare e' ''mappare'' ogni singolo rimpiazzo eseguendo in modalità ''comando''
(command-mode) quanto segue:
(command-mode) quanto segue:
  :map! vecchio nuovo
  :map! vecchio nuovo
-
Dove ''vecchio'' corrisponde al testo digitate e ''nuovo'' al rimpiazzo che verra' utilizzato
+
Dove ''vecchio'' corrisponde al testo digitate e ''nuovo'' al rimpiazzo che verrà utilizzato
automaticamente. Quindi ad esempio, per rimpiazzare automaticamente ogni volta che viene
automaticamente. Quindi ad esempio, per rimpiazzare automaticamente ogni volta che viene
digitato il carattere accentuato ''è'' con la stringa ''è'' basta eseguire il comando:
digitato il carattere accentuato ''è'' con la stringa ''è'' basta eseguire il comando:
Riga 104: Riga 104:
  :map! è è
  :map! è è
-
E' cosi' via per tutte le altre entita' XML necessarie. Grosso modo un elenco piu' o meno
+
E' cosi' via per tutte le altre entità XML necessarie. Grosso modo un elenco piu' o meno
utile (ma incompleto) e' rappresentato cosi':
utile (ma incompleto) e' rappresentato cosi':
  à è é ì ò ù
  à è é ì ò ù
-
Non resta che ''mappare'' ogni carattere associandolo alla sua rispettiva entita' XML.
+
Non resta che ''mappare'' ogni carattere associandolo alla sua rispettiva entità XML.
==== Configurazione di GNU Emacs ====
==== Configurazione di GNU Emacs ====
Riga 116: Riga 116:
==== Utilizzare un editor in-line ====
==== Utilizzare un editor in-line ====
L'approfondimento di tali strumenti e' delegato a documenti appositi. Questo paragrafo
L'approfondimento di tali strumenti e' delegato a documenti appositi. Questo paragrafo
-
mostrera' semplicemente un esempio (il piu' semplice) di rimpiazzamento testuale al fine
+
mostrerà semplicemente un esempio (il piu' semplice) di rimpiazzamento testuale al fine
di stimolare gli utenti meno pratici a non effettuare noiose sostituzioni a mano una per
di stimolare gli utenti meno pratici a non effettuare noiose sostituzioni a mano una per
una optando invece per una soluzione piu' elegante, comoda e rapida. Il seguente comando
una optando invece per una soluzione piu' elegante, comoda e rapida. Il seguente comando
-
rimpiazza tutte le occorrenze del carattere ''ù'' con la relativa entita' XML, ''ù''
+
rimpiazza tutte le occorrenze del carattere ''ù'' con la relativa entità XML, ''ù''
nel file chap-edit.xml:
nel file chap-edit.xml:
Riga 140: Riga 140:
[[#Adesione al progetto|aderendo al progetto]] come descritto sopra. In alternativa e'
[[#Adesione al progetto|aderendo al progetto]] come descritto sopra. In alternativa e'
possibile contattare direttamente un membro del progetto al fine di delegare a lui il
possibile contattare direttamente un membro del progetto al fine di delegare a lui il
-
''commit'' della documentazione attualmente tradotta. In questo caso sara' sufficiente
+
''commit'' della documentazione attualmente tradotta. In questo caso sarà sufficiente
inviargli un tarball contenente i file XML tradotti ma, banale a dirsi, non prima di averlo
inviargli un tarball contenente i file XML tradotti ma, banale a dirsi, non prima di averlo
adeguatamente informato.
adeguatamente informato.
Riga 155: Riga 155:
  $ cvs ci -m "Corretto un errore di battitura." chap-edit.xml
  $ cvs ci -m "Corretto un errore di battitura." chap-edit.xml
-
Cosi' facendo verra' aggiornato solo il file ''chap-edit.xml''.
+
Cosi' facendo verrà aggiornato solo il file ''chap-edit.xml''.
Una volta terminata una traduzione, ricordarsi di cambiare lo stato nella riga relativa
Una volta terminata una traduzione, ricordarsi di cambiare lo stato nella riga relativa
al file nella tabella delle [[traduzioni]].
al file nella tabella delle [[traduzioni]].

Versione delle 21:01, 31 mar 2008

Questo articolo è solo un abbozzo, contribuisci a migliorarlo secondo le convenzioni di NetBSD-it mettendo a disposizione le tue conoscenze. La comunità te ne sarà grata!

Questo testo si propone come manuale di riferimento per traduttori e revisionisti i quali hanno intenzione di lavorare su una delle guide messe a disposizione degli utenti NetBSD e pkgsrc. Le istruzioni sono relative a tutte le guide (correlate al progetto NetBSD), non solo The NetBSD Guide.

Indice

Introduzione

Il formato utilizzato dalla guida di NetBSD e' XML/DocBook. Come specificato nell'appendice B.1 della guida ufficiale non bisogna cominciare a lavorare con HTML o altri formati: risulterà molto difficile convertire il tuo lavoro in XML/DocBook.

Adesione al progetto

Il metodo piu' rapido per iscriversi al progetto NetBSDit-docs ottenendo cosi' accesso in scrittura per il repository CVS in modo da poter pubblicare eventuali modifiche alla documentazione, sarà sufficiente contattare il team di NetBSD Italia inviando una email di richiesta (posibilmente con una breve lista dei documenti che sui quali si desidera lavorare) a Claudio M. Alessi, Leonardo Taccari oppure scrivendo un post direttamente nella lista di discussione ufficiale NetBSD-Docs-it. In alternativa si puo' accedere al canale #NetBSD-it@Freenode per parlare direttamente con i membri della comunità. In questo caso si prega di non essere troppo formali :-)

Scelta degli argomenti

Prima di cominciare a tradurre un documento e' buona norma verificare che questo sia disponibile per la traduzione. Infatti, qualcun altro potrebbe essere già impegnato nella traduzione di un determinato argomento o questo potrebbe essere già stato tradotto. Di norma comunque, i documenti tradotti (o in fase di traduzione) vengono mantenuti quanto piu' aggiornati possibile sul repository CVS. Una lista completa di documenti e dei relativi traduttori e revisionisti e' stata disposta in una tabella, consultabile nella pagina di coordinamento per le traduzioni. Si consiglia di considerare inoltre l'idea di postare su 'netbsd-docs-it per chiarimenti, richieste, commenti e altro.

Una volta scelto l'argomento da tradurre (o revisionare) bisogna provvedere a modificare appropriatamente la relativa voce nella tabella all'interno della pagina Traduzioni.

Ottenere i sorgenti

I file necessari per lavorare a una traduzione si possono ottenere direttamente dai repository ufficiali del progetto NetBSDit-docs. Per ottenere la guida di NetBSD, che attualmente e' quella con maggiore priorità nella lista delle traduzioni, eseguire il comando:

$ cvs -d :pserver:anonymous@netbsdit-docs.cvs.sf.net:/cvsroot/netbsdit-docs -P netbsd/guida

In questo modo verrà creata la directory netbsd contenente tutti i file XML (tradotti e non) della guida ufficiale, The NetBSD Guide, i quali potranno essere modificati per effettuare successivamente (ed eventualmente) un commit sul repository CVS.

Per ottenere i sorgenti XML relativi ad altri documenti basta seguire la stessa procedura cambiando solo il percorso. In generale, per ottenere i sorgenti del documento guida-prova relativa a software (al momento solo NetBSD o pkgsrc) basta eseguire cvs(1) in questo modo:

$ cvs -d :pserver:anonymous@netbsdit-docs.cvs.sf.net:/cvsroot/netbsdit-docs -P software/guida-prova

Questa sintassi e' dovuta alla struttura ad albero del repository su cui risiedono i sorgenti, i quali sono distribuiti in modo da rendere quanto piu' semplice possibile la gestione dei file anche agli utenti meno pratici.

Modificare i file

Per il processo di modifica tutto cio' di cui si necessita sono i sorgenti delle pagine che si intende modificare e un semplice editor di testi puro, quindi esclusi OpenOffice, KWord e simili. Piuttosto utilizzare software decenti come vi(1) che e' incluso nel sistema base o ancora meglio editors/vim o editors/emacs (giusto per nominarne alcuni).

Regole di formattazione

Il team di NetBSD fornisce alcune regole da seguire al fine di rendere i sorgenti compatti e facilmente comprensibili. In particolare bisogna utilizzare:

  • 2 spazi per indentare il codice. Non sono ammessi tab o sequenze di spazi diverse da 2;
  • linee lunghe non piu' di 72 caratteri;
  • delle linee di separazione (commenti) fra 2 sezioni differenti.

Per un esempio di documento XML/DocBook consultare l'appendice B.3 della guida ufficiale.

Caratteri accentuati

Il processo di traduzione non richiede necessariamente la conoscenza del linguaggio di markup XML ma solo di alcuni accorgimenti per altro comuni a tutti i linguaggi derivati come l'(X)HTML. Fondamentalmente l'unica cura che bisogna avere e' di rimpiazzare i caratteri accentuati con le relative entità XML. Questo vuol dire che caratteri come è, à o ì vanno rimpiazzati con le relative entità, rispettivamente: è, à e ì. Per un elenco dei caratteri italiani piu' comuni consultare la tabella ISO 8859-1 (Latin-1).

Configurazione di Vi/Vim

Fra le varie funzionalità, l'editor vi (e derivati) offre la possibilità di rimpiazzare automaticamente del testo al momento in cui lo si digita. Questo risulta molto utile quando si lavora su documenti in cui alcuni caratteri vanno rimpiazzati praticamente sempre. Anziche' utilizzare un editor in-line dopo la stesura del testo e' conveniente farlo durante il processo di traduzione risparmiando un po' tempo. Su vi tutto quello che bisogna fare e' mappare ogni singolo rimpiazzo eseguendo in modalità comando (command-mode) quanto segue:

:map! vecchio nuovo

Dove vecchio corrisponde al testo digitate e nuovo al rimpiazzo che verrà utilizzato automaticamente. Quindi ad esempio, per rimpiazzare automaticamente ogni volta che viene digitato il carattere accentuato è con la stringa è basta eseguire il comando:

:map! è è

E' cosi' via per tutte le altre entità XML necessarie. Grosso modo un elenco piu' o meno utile (ma incompleto) e' rappresentato cosi':

à è é ì ò ù

Non resta che mappare ogni carattere associandolo alla sua rispettiva entità XML.

Configurazione di GNU Emacs

XXX: per ragioni di coerenza e correttezza digitale (?) e' il caso di considerare anche gli utenti GNU Emacs.

Utilizzare un editor in-line

L'approfondimento di tali strumenti e' delegato a documenti appositi. Questo paragrafo mostrerà semplicemente un esempio (il piu' semplice) di rimpiazzamento testuale al fine di stimolare gli utenti meno pratici a non effettuare noiose sostituzioni a mano una per una optando invece per una soluzione piu' elegante, comoda e rapida. Il seguente comando rimpiazza tutte le occorrenze del carattere ù con la relativa entità XML, ù nel file chap-edit.xml:

$ sed 's/ù/\&ugrave;/g' < chap-edit.xml > chap-edit.xml.entity
$ mv chap-edit.xml.entity chap-edit.xml

Il carattere & essendo riservato a sed(1) necessita di un ulteriore carattere cosiddetto di escape, ovvero '\'. Riassumendo: i due comandi non fanno altro che rimpiazzare tutte le occorrenze (come descritto sopra) e salvare il risultato nel file chap-edit.xml.entity il quale viene poi rinominato in chap-edit.xml, sostituendo il precedente (secondo comando). Altri caratteri possono essere rimpiazzati utilizzando la flag -e o in modo analogo eseguendo sed(1) una volta per ogni carattere.

Termini noti

XXX: spostare l'elenco dei termini in questo paragrafo?

Pubblicare il lavoro

Per coloro i quali non fossero traduttori e/o revisionisti ufficiale (quindi senza accesso ai repository del progetto NetBSDit-docs) e' consigliato rimediare un account aderendo al progetto come descritto sopra. In alternativa e' possibile contattare direttamente un membro del progetto al fine di delegare a lui il commit della documentazione attualmente tradotta. In questo caso sarà sufficiente inviargli un tarball contenente i file XML tradotti ma, banale a dirsi, non prima di averlo adeguatamente informato.

Per effettuare un commit tutto quello che si deve fare e' eseguire il seguente comando:

$ cvs ci -m "Descrizione delle modifiche apportate."

In questo modo tutti i file aggiornati, ovvero quelli che non corrisponderanno alla versione presente nel repository CVS, verranno caricati sul server rimpiazzando quelli vecchi. E' possibile anche specificare una lista di file da aggiornare in modo da ignorare temporaneamente tutte le eventuali altre modifiche, come segue:

$ cvs ci -m "Corretto un errore di battitura." chap-edit.xml

Cosi' facendo verrà aggiornato solo il file chap-edit.xml. Una volta terminata una traduzione, ricordarsi di cambiare lo stato nella riga relativa al file nella tabella delle traduzioni.

Suggerimenti e consigli

Una solida organizzazione accompagnata dalla potenza di avanzati software per il versioning semplifica di molto lo sviluppo di qualsiasi progetto. Tuttavia, dal momento che si ha a che fare con file in formato XML, i quali possono creare un po' di confusione, e' bene seguire poche linee guide al fine di essere quanto piu' efficienti possibili. In particolar modo per i nuovi arrivati e' consigliato:

  • Modificare un file alla volta. Evitare di cominciare a tradurre altri file finche' quello corrente non sia stato ultimato. Questo puo' evitare confusioni o, qualora piu' traduttori stiano lavorando agli stessi file, puo' minimizzare i conflitti nel repository;
  • Ove possibile, cercare sempre di concludere le sequenze logiche di testo. In termini pratici questo significha di concludere una traduzione in un unico processo di editing evitando di suddividere nel tempo modifiche relative allo stesso capitolo. Sebbene i file (quindi i capitoli) siano piuttosto grossi e' buona norma cercare di seguire questa regola riferendosi quanto meno ai paragrafi;
  • Effettuare tempestivamente il commit al fine di assicurare il completo salvataggio della documentazione tradotta fino a quel momento. Questo riduce i rischi di perdite e consente di riprendere il lavoro anche da altre postazioni semplicemente scaricando la versione del documento presente nel repository;

Si ricorda inoltre agli utenti avanzati che e' possibile fornire della nuova documentazione al fine di estendere le guide ufficiali.

Collegamenti esterni

Strumenti personali