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 diagnostica in modo prolisso qualsiasi desincronizzazione della struttura rilevata. Quando ciò accade, è necessario modificare manualmente i file (ciò probabilmente richiede avere alcune nozioni sulla lingua di destinazione). È necessario aggiungere paragrafi falsi o rimuovere alcuni contenuti in uno dei documenti (o entrambi) per correggere le disparità segnalate, fino a quando la struttura di entrambi i documenti non corrisponde perfettamente. Alcuni trucchi sono forniti nella sezione successiva.

Anche quando il documento viene elaborato correttamente, sono ancora possibili disparità non rilevate ed errori silenziosi. Questo è il motivo per cui qualsiasi traduzione associata automaticamente da po4a-gettextize viene contrassegnata come fuzzy per richiedere un'ispezione manuale. È necessario verificare che ogni msgstr recuperato sia effettivamente la traduzione del msgid associato e non la stringa prima o dopo.

Come si può vedere, è fondamentale avere la stessa identica struttura nel documento tradotto e in quello originale. La cosa migliore è eseguire la "gettext-izzazione" sulla versione esatta di master.doc utilizzata per la traduzione e aggiornare il file PO rispetto al file master più recente solo una volta che la "gettext-izzazione" abbia avuto successo.

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¶

La gettextization si interrompe non appena viene rilevata una desincronizzazione. In teoria, dovrebbe probabilmente essere possibile risincronizzare la "gettext-izzazione" più avanti nei documenti usando ad es. lo stesso algoritmo di diff(1). Ma un intervento manuale sarebbe comunque obbligatorio per abbinare manualmente gli elementi che non possono essere abbinati automaticamente, spiegando perché la risincronizzazione automatica non è stata implementata (ancora?).

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)).
• Se è necessario modificare i file per allineare le loro strutture, è preferibile modificare la traduzione, se possibile. Infatti, se le modifiche all'originale sono troppo invadenti, la vecchia e la nuova versione non verranno abbinate durante l'aggiornamento del PO e la traduzione corrispondente verrà comunque scaricata. Ma non si esitati a modificare anche il documento originale, se necessario: l'importante è ottenere un primo file PO con cui iniziare.
• Non fatevi problemi a eliminare qualsiasi contenuto originale che non esisterebbe nella versione tradotta. Questo contenuto verrà reintrodotto automaticamente in seguito, durante la sincronizzazione del file PO con il documento.
• 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.
• In some case, po4a adds a space at the end of either the original or the translated strings. This is because every string must be deduplicated during the gettextize process. Imagine that a string appearing several times unmodified in the original, but is translated in differing way, or that different paragraphs are translated in the exact same way.

  Without deduplication, such case would break the gettexization algorithm, as it is a simple one to one pairing between the msgids of both the master and the localized files. Since one of the PO files would miss an entry (that would be reported as duplicate, with two references), the pairing would fail.

  Since po4a uses the entry type ("title" or "plain paragraph", etc) to detect whether the parsing streams got desynchronized, similar issues could occur if two identical entries (same content but differing type) of the master file are translated in the exact same way in the localized file. po4a would detect a fake desyncronization in such case.

  In most cases, the extra space added by po4a to deduplicate the strings has no impact on the formatting. Strings are fuzzied anyway, and msgmerge will probably match the strings accordingly afterward.

• Come nota finale, non siate troppo sorpresi se la prima sincronizzazione del file PO richiede molto tempo. Questo perché la maggior parte del msgid del file PO risultante dalla "gettext-izzazione" non corrisponde esattamente a nessun elemento del file POT creato dai file master recenti. Questo costringe gettext a cercare quello più vicino utilizzando un pesante algoritmo di prossimità di stringhe.

  Ad esempio, il primo po4a-updatepo della traduzione francese della documentazione Perl (file PO da 5,5 MB) ha impiegato circa 48 ore (sì, due giorni) mentre i successivi solo una dozzina di secondi.