KDE Localization/it/Rigenerazione della documentazione

Perché rigenerare la documentazione?

Ci sono fondamentalmente due motivi per rigenerare la documentazione:

1. Sei un traduttore di un file di documentazione, e vuoi vedere come verrà il tuo lavoro finito.
2. Sei un traduttore con un account di Subversion e ti è stato affidato un file della documentazione da mettere su SVN, e devi rigenerare la documentazione per poterla poi depositare anch'essa su SVN.

La rigenerazione della documentazione è un capitolo particolarmente spinoso. Il processo di traduzione della documentazione si compone di vari passi:

1. Scrittura dell'originale inglese in formato docbook;
2. Generazione del file .pot con xml2pot;
3. Traduzione del file .po, cioè quello che facciamo noi, e che è ben descritto da altre parti;
4. Rigenerazione della documentazione. Questo passo è assolutamente necessario, altrimenti tutto il lavoro sarà stato fatto per nulla! E noi sappiamo tutti quanta fatica si faccia a tradurre la documentazione, giusto?

Allora, supponendo che voi vi siate già muniti di una copia locale di SVN (per quanto riguarda i file delle traduzioni), dovete eseguire i seguenti incantesimi...

Avviare la rigenerazione

Innanzitutto, assicuratevi di aver aggiornato le cartelle templates/docmessages e it/docmessages prima di cominciare.

Per la rigenerazione va usato lo script update_xml, e si trova nella cartella l10n/scripts. Prende due argomenti, il secondo dei quali facoltativo:

1. il codice della lingua, per noi ovviamente it;
2. il pacchetto da rigenerare; se il secondo argomento manca, update_xml cercherà di rigenerare tutti i pacchetti.

A questo punto, cominceranno a scorrere dei messaggi, si spera comprensibili, che seguiranno il processo di rigenerazione.

I messaggi d'errore

update_xml produce spesso messaggi d'errore incomprensibili e criptici. Se avete la sventura di incapparvi (e succede in tutte le rigenerazioni, quindi state tranquilli che capiterà anche a voi...), mantenete la calma. Di solito il 90% degli errori sono dovuti a cause piuttosto semplici.

• CREDIT_FOR_TRANSLATORS o CREDIT_FOR_TRANSLATOR tradotti con la struttura sbagliata: questo è un classico. Le strutture della stringa che deve sostituire CREDIT_FOR_TRANSLATORS o CREDIT_FOR_TRANSLATOR sono rigide, rigorose e difficili da memorizzare. Usando Lokalize, premete Ctrl+Spazio per averne dei modelli perfetti da riempire con nome, cognome ed eventualmente ruolo, ed eviterete praticamente qualsiasi problema di questo tipo.

• Entità trascritte male: può capitare che, nella traduzione, un'entità &Qt; sia diventata un'entità &QT; per un dito pigro sul tasto shift; ovviamente update_xml non capirà cosa sta succedendo, e si rifiuterà di rigenerare l'agognato index.docbook;

• Entità tradotte: per lo stesso motivo, se avete tradotto &etc; con &ecc;, update_xml incrocerà i byte e si rifiuterà di andare avanti.

• Entità mancanti in user.entities: questo file contiene le traduzioni italiane di espressioni come &etc;, &ie; e altre; se l'autore si aspetta che ci sia un'entità &Shift;, e questa manca dal file, il povero update_xml non saprà a che santo votarsi, e... avete indovinato, non rigenererà la documentazione. In questo caso, rompete le scatole in lista per farla aggiungere.

• Tag sbagliati: se per sbaglio vi è scappato un <guilabel>Modifica<guilabel>, cioè senza un misero /, state freschi: update_xml risponderà che la DTD non è rispettata, e vi toccherà spulciarvi i file per trovare l'errore. Di solito viene indicata la riga incriminata, ma del file docbook rigenerato, non del PO. Siccome il docbook non conforme viene eliminato, non è possibile visionarlo per controllare l'errore subito, ma dovete rigenerarvene una copia da voi con po2xml originale.xml traduzione.po > risultato.xml, verificare dov'è il problema con checkXML risultato.xml, e infine correggere il file PO.

• A volte gli sviluppatori hanno la pessima idea di usare entità che non sono ancora nella versione di KDE che avete sulla vostra macchina. A questo punto dovete prendere i file delle entità nuovi di trinca da Subversion. Installate contributor.entities, general.entities e l10n.entities dalla cartella kdoctools/customization/entities del deposito Git di kdelibs al posto di quelli che avete adesso. Usate locate per sapere dove la vostra distribuzione ha messo quei file.

Una volta che, sudate le sette camicie, riuscirete finalmente a rigenerare la documentazione, che verrà messa da update_xml in l10n/it/docs (Attenzione: non l10n/it/docmessages), potrete finalmente depositarla su SVN o ottenerne le pagine HTML con meinproc index.docbook.

Aggiungere le immagini in italiano

La ciliegina sulla torta per l'utente finale è trovare le immagini localizzate in italiano.

Per sapere quali immagini dovete localizzare, guardate nella cartella l10n/documentation/<pacchetto>/<programma>, e vedere quante immagini (di solito in formato .png) sono da localizzare. Se la cartella sotto documentation manca, lanciate una rigenerazione della documentazione per il pacchetto in questione: lo script recupererà o aggiornerà automaticamente la documentazione originale, immagini incluse.

Potete lasciar perdere le immagini che non contengono testo, o che comunque non cambiano dalla versione italiana a quella inglese, come per esempio questa icona di Korganizer. Per le altre, dovrete installare il programma (se non l'avete già), e usare la traduzione italiana corrente; può darsi che la traduzione della GUI disponibile su SVN sia più recente di quella che viene distribuita con il programma, o magari la versione attuale del programma non contiene nemmeno la traduzione italiana; questa è una situazione tipica se la traduzione è stata realizzata di recente. Tocca quindi a voi fare un:

msgfmt programma.po -o programma.mo

Il file .mo va messo nella cartella giusta; per trovare la cartella dove mettere il file .mo, che può variare con la distribuzione che usate, potete semplicemente fare un

locate programma.mo

e dovreste in linea di massima vedere dov'è la traduzione italiana attuale, o le traduzioni in altre lingue se manca quella italiana. Cartelle comuni sono /usr/share/locale/it/LC_MESSAGES/ e /usr/kde/4.X/share/locale/it/LC_MESSAGES/.

Accedete come root al sistema e copiate nella cartella giusta il vostro file .mo (fate una copia di sicurezza del vecchio), e ricordatevi di permettere a tutti l'accesso al file con un chmod 644 programma.mo.

A questo punto, siete pronti! Fate partire il programma, e ricreate le situazioni d'uso descritte nel manuale per riprodurre le immagini da localizzare. Per catturare le instantanee potete usare Ksnapshot.

Lo stile da utilizzare è quello predefinito di KDE al momento in cui si scatta l'immagine. Attenetevi per quanto possibile alle linee guida qui riportate, in particolare tenete le finestre alle loro dimensioni minime per ridurre le dimensioni dei file.

Una volta che avete fatto le istantanee, depositate i file .png nella giusta sottocartella di it/docs (attenzione! Non it/docmessages), di fianco alla documentazione rigenerata; se non avete un account di Subversion, inviate le immagini a qualcuno che ce l'abbia.