Convertire la traduzione di un manuale a po4a¶

po4a-gettextize cercherà di estrarre il contenuto di qualunque file di traduzione gli venga fornito, ed usare questo contenuto come voci msgstr nel file PO prodotto. Si osservi che tale processo è molto fragile: esso si basa sulla supposizione che la stringa in posizione N nel file tradotto corrisponda alla stringa di posizione N nel file originale. Ciò naturalmente non funzionerà se i file non condividono esattamente la stessa struttura.

Internamente, ogni parser po4a riporta il tipo di sintassi di ogni stringa estratta. Questo è il modo in cui la desincronizzazione viene rilevata durante la fase di gettext-izzazione. Per esempio, se i file hanno la seguente struttura, è molto improbabile che la quarta stringa nella traduzione (di tipo 'capitolo') sia la traduzione della quarta stringa nell'originale (di tipo 'paragrafo'), o che due paragrafi originali vengano fusi assieme nella traduzione.

    Originale        Traduzione
  capitolo           capitolo
    paragrafo          paragrafo
    paragrafo          paragrafo
    paragrafo        chapter
  capitolo             paragrafo
    paragrafo          paragrafo

po4a-gettextize will verbosely diagnose any detected structure desynchronization. When this happens, you should manually edit the files (this probably requires that you have some notions of the target language). You must add fake paragraphs or remove some content in one of the documents (or both) to fix the reported disparities, until the structure of both documents perfectly match. Some tricks are given in the next section.

Even when the document is successfully processed, undetected disparities and silent errors are still possible. That is why any translation associated automatically by po4a-gettextize is marked as fuzzy to require an manual inspection by humans. One has to check that each retrieved msgstr is actually the translation of the associated msgid, and not the string before or after.

As you can see, the key here is to have the exact same structure in the translated document and in the original one. The best is to do the gettextization on the exact version of master.doc that was used for the translation, and only update the PO file against the latest master file once the gettextization was successful.

Se si è abbastanza fortunati da avere le strutture di entrambi i documenti che combaciano perfettamente, si lavorerà senza intoppi e si otterranno risultati in pochi secondi. Altrimenti, si scoprirà perché questo processo ha un nome così brutto, e sarà meglio essere preparati ad un bel po' di lavoro. In ogni caso, è meglio ricordarsi che è il prezzo da pagare per ottenere in seguito la comodità di po4a. Una volta fatta la conversione, la sincronizzazione tra documenti master e le loro traduzioni sarà per sempre completamente automatica.

Anche se le cose dovessero andare male, la gettext-izzazione rimane molto più veloce che tradurre tutto nuovamente. Sono stato in grado di gettext-izzare l'esistente traduzione francese della documentazione Perl in un giorno, anche se la struttura di molti documenti era desincronizzata (2 milioni di caratteri): ripartire con una traduzione da zero avrebbe richiesto dei mesi di lavoro.

Suggerimenti e trucchi per il processo di gettext-izzazione¶

The gettextization stops as soon as a desynchronization is detected. In theory, it should probably be possible resynchronize the gettextization later in the documents using e.g. the same algorithm than the diff(1) utility. But a manual intervention would still be mandatory to manually match the elements that couldn't be automatically matched, explaining why automatic resynchronization is not implemented (yet?).

Quando ciò accade, il succo del lavoro consiste nel riallineare la struttura di questi file tramide modifiche manuali. Quando accade, po4a-gettextize è piuttosto prolisso nel descrivere cosa non ha funzionato. Indica le stringhe che non corrispondono, la loro posizione nel testo, e il tipo di ognuna di esse. Inoltre, il file PO generato fin lì verrà scaricato in gettextization.failed.po per consentirne l'analisi.

Ecco alcuni altri trucchi per alleviare in questo noioso lavoro:

• Rimuovere tutto il contenuto extra delle traduzioni, come per esempio la sezione riconoscimenti ai traduttori. Le si potranno riaggiungere in po4a in seguito, usando un'addenda (vedere po4a(7)).
• If you need to edit the files to align their structures, you should prefer editing the translation if possible. Indeed, if the changes to the original are too intrusive, the old and new versions will not be matched during the PO update, and the corresponding translation will be dumped anyway. But do not hesitate to also edit the original document if required: the important thing is to get a first PO file to start with.
• Do not hesitate to kill any original content that would not exist in the translated version. This content will be automatically reintroduced afterward, when synchronizing the PO file with the document.
• Si dovrebbe probabilmente informare l'autore originale di ogni cambiamento strutturale nella traduzione che sembra giustificato. Se ci sono problemi nell'originale, bisogna informarne l'autore. La correzione nella traduzione corregge solo per una parte della comunità. Inoltre è in pratica impossibile quando si usa po4a ;).
• A volte, il contenuto dei paragrafi corrisponde, ma i loro tipi no. La correzione è abbastanza dipendente dal formato. Nel POD e nelle pagine man, spesso deriva dal fatto che uno dei due paragrafi contiene una riga che inizia con uno spazio bianco mentre l'altro paragrafo no. In quei formati, tali paragrafi non possono essere mandati a capo e quindi diventare di un tipo diverso. In tal caso basta rimuovere lo spazio e si è a posto. Alle volte si tratta anche di un semplice refuso nel nome del marcatore XML.

  Allo stesso modo, due paragrafi possono venire uniti assieme nel POD quando la riga di separazione contiene alcuni spazi, o quando non c'è una riga vuota tra la riga =elemento e il contenuto dell'elemento stesso.

• A volte, il messaggio di desincronizzazione sembra strano perché la traduzione viene collegata al paragrafo originale sbagliato. È il segno di problema non rilevato prima nel processo. Controllare gettextization.failed.po per vedere quando inizia veramente il problema e correggerlo dov'è effettivamente.
• Con alcune impostazioni sfortunate, si ha forte sospetto che po4a abbia mangiato alcune parti del testo, nell'originale o nella traduzione. gettextization.failed.po indica che entrambi i file corrispondevano, come previsto, fino al paragrafo N. Ma poi, è stato effettuato un tentativo (fallito) di abbinare il paragrafo N+1 nel file originale non con il paragrafo N+1 nella traduzione come avrebbe dovuto, ma con il paragrafo N+2. Come se il paragrafo N+1 che vedi nel documento fosse semplicemente scomparso nel processo.

  Questa sfortunata situazione si verifica quando uno stesso paragrafo si ripete più volte nel documento. In questo caso nel file PO non viene creata nessuna voce aggiuntiva, ma viene invece aggiunto un nuovo riferimento all'esistente.

  So, the previous situation occurs when two similar but different paragraphs are translated in the exact same way. This will apparently remove a paragraph of the translation. To fix the problem, it is sufficient to slightly alter one of the translations in the document. You can also prefer to kill the second paragraph in the original document.

  All'opposto, se lo stesso paragrafo che appare due volte nel documento originale non viene tradotto allo stesso modo in entrambe le posizioni, si avrà la sensazione che un paragrafo dell'originale sia scomparso. Per risolvere il problema basta copiare la migliore traduzione sopra l'altra nel documento tradotto.

• As a final note, do not be too surprised if the first synchronization of your PO file takes a long time. This is because most of the msgid of the PO file resulting from the gettextization don't match exactly any element of the POT file built from the recent master files. This forces gettext to search for the closest one using a costly string proximity algorithm.

  For example, the first po4a-updatepo of the Perl documentation's French translation (5.5 MB PO file) took about 48 hours (yes, two days) while the subsequent ones only take a dozen of seconds.