Localizzazione tramite gettext

Oltre a Importazione delle traduzioni in formato CSV, Godot supporta anche il caricamento di file di traduzione scritti nel formato GNU gettext (.po basato su testo, nonché .mo compilato a partire da Godot 4.0).

Nota

Per un'introduzione a gettext, dare un'occhiata a A Quick Gettext Tutorial <https://www.labri.fr/perso/fleury/posts/programming/a-quick-gettext-tutorial.html>`_. È scritto per i progetti in C, ma molti dei consigli sono validi anche per Godot (ad eccezione di ``xgettext).

Vantaggi

  • gettext è un formato standard, che può essere modificato attraverso qualsiasi editor di testo o editor di GUI come Poedit.

  • gettext è supportato da piattaforme di traduzione come Transifex e Weblate, il che rende più facile collaborare alla localizzazione.

  • Rispetto a CSV, gettext funziona meglio con i sistemi di controllo versioni come Git, poiché ogni localizzazione ha il proprio file di messaggi.

  • Le stringhe su più righe sono più comode da modificare nei file gettext rispetto ai file CSV.

Svantaggi

  • gettext è un formato più complesso del CSV e può essere più difficile da comprendere per chi non è esperto con la localizzazione di software.

  • Chi si occupa di gestire i file di localizzazione dovrà installare gli strumenti gettext sul proprio sistema. Tuttavia, poiché Godot supporta l'utilizzo di file di messaggi basati su testo (.po), i traduttori possono testare il proprio lavoro senza dover installare gli strumenti gettext.

Installare gli strumenti gettext

Gli strumenti gettext da riga di comando sono necessari per eseguire operazioni di manutenzione, come aggiornare i file di messaggi. Pertanto, si consiglia vivamente di installarli.

  • Windows: Scaricare un installer da questa pagina. Funziona con qualsiasi architettura e tipo di binario (condiviso o statico); in caso di dubbio, scegliere l'installer statico a 64 bit.

  • macOS: Installare gettext tramite Homebrew con il comando brew install gettext oppure tramite MacPorts con il comando sudo port install gettext.

  • Linux: Nella maggior parte delle distribuzioni, installare il pacchetto gettext dal gestore pacchetti della propria distribuzione.

Creare il modello PO

Generazione automatica utilizzando l'editor

A partire da Godot 4.0, l'editor può generare automaticamente un modello PO da file di scena e GDScript specificati. Questa generazione POT supporta anche i contesti di traduzione e la pluralizzazione se utilizzata in uno script, tramite il secondo argomento opzionale tr() e il metodo tr_n().

Aprire la scheda Localizzazione > Generazione POT delle Impostazioni del progetto, quindi premere il pulsante Aggiungi… per specificare il percorso alle scene e agli script nel progetto che contengono stringhe localizzabili:

Creazione di un modello PO nella scheda Localizzazione > Generazione POT delle Impostazioni del progetto

Creazione di un modello PO nella scheda Localizzazione > Generazione POT delle Impostazioni del progetto

Dopo aver aggiunto almeno una scena o uno script, fai clic su Genera POT nell'angolo in alto a destra, quindi specifica il percorso del file di output. Questo file può essere posizionato ovunque nella directory del progetto, ma è consigliabile salvarlo in una sottodirectory come locale, poiché ogni locale sarà definito in un file separato.

Vedere di seguito per informazioni su come aggiungere commenti per i traduttori o escludere alcune stringhe dall'aggiunta al modello PO per i file GDScript.

Si può quindi passare alla creazione di un file di messaggi da un modello PO.

Nota

Ricordare di rigenerare il modello PO dopo aver apportato modifiche alle stringhe localizzabili o dopo aver aggiunto nuove scene o script. Altrimenti, le stringhe nuovamente aggiunte non saranno localizzabili e i traduttori non saranno in grado di aggiornare le traduzioni per le stringhe obsolete.

Creazione manuale

Se l'approccio della generazione automatica non dovesse funzionare, è possibile creare manualmente un modello PO in un editor di testo. Questo file può essere situato ovunque nella cartella del progetto, ma è consigliabile mantenerlo in una sottocartella, poiché ogni localizzazione sarà definita in un file separato.

Creare una cartella denominata locale nella cartella del progetto. In questa cartella, salvare un file denominato messages.pot con il seguente contenuto:

# Don't remove the two lines below, they're required for gettext to work correctly.
msgid ""
msgstr ""

# Example of a regular string.
msgid "Hello world!"
msgstr ""

# Example of a string with pluralization.
msgid "There is %d apple."
msgid_plural "There are %d apples."
msgstr[0] ""
msgstr[1] ""

# Example of a string with a translation context.
msgctxt "Actions"
msgid "Close"
msgstr ""

I messaggi in gettext sono composti dalle coppie msgid e msgstr. msgid è la stringa sorgente (solitamente in inglese), msgstr sarà la stringa tradotta.

Avvertimento

Il valore msgstr nei file di modello PO (.pot) dovrebbe sempre essere vuoto. La localizzazione sarà invece effettuata nei file .po generati.

Creare un file di messaggi da un modello PO

Il comando msginit è utilizzato per trasformare un modello PO in un file di messaggi. Ad esempio, per creare un file di localizzazione in francese, utilizzare nella cartella locale il seguente comando:

msginit --no-translator --input=messages.pot --locale=fr

Il comando sopra riportato creerà un file denominato fr.po nella stessa cartella del modello PO.

In alternativa, è possibile fare ciò graficamente tramite Poedit oppure caricando il file POT su una piattaforma web a scelta.

Caricare un file di messaggi in Godot

Per registrare un file di messaggi come traduzione in un progetto, aprire le Impostazioni del progetto, quindi andare alla scheda Localizzazione. In Traduzioni, cliccare su Aggiungi…, quindi selezionare il file .po o .mo nella finestra di dialogo. La localizzazione verrà dedotta dalla proprietà "Language: <code>\n" nel file di messaggi.

Nota

Consultare Internazionalizzazione dei giochi per ulteriori informazioni sull'importazione e il test delle traduzioni in Godot.

Aggiornare i file di messaggi per seguire il modello PO

Dopo aver aggiornato il modello PO, sarà necessario aggiornare i file di messaggi in modo che contengano nuove stringhe, rimuovendo quelle non più presenti nel modello PO. Questa operazione si può effettuare automaticamente tramite lo strumento msgmerge:

# The order matters: specify the message file *then* the PO template!
msgmerge --update --backup=none fr.po messages.pot

Se si desidera conservare un backup del file di messaggi originale (che in questo esempio sarebbe salvato come fr.po~), rimuovere l'argomento --backup=none.

Nota

Dopo aver eseguito msgmerge, le stringhe modificate nella lingua di origine saranno precedute da un commento "fuzzy" nel file .po. Questo commento indica che la traduzione si deve aggiornare per corrispondere alla nuova stringa di origine, poiché la traduzione sarà molto probabilmente non accurata finché non verrà aggiornata.

Le stringhe con commenti "fuzzy" non verranno lette da Godot finché la traduzione non verrà aggiornata e il commento "fuzzy" non verrà rimosso.

Verificare la validità di un file o modello PO

È possibile verificare se la sintassi di un file gettext è valida eseguendo il comando seguente:

msgfmt fr.po --check

Se ci sono errori di sintassi o avvertimenti, questi saranno visualizzati nella console. Se no, msgfmt non produrrà alcun output.

Utilizzare file MO binari (utile solo per i grandi progetti)

Per progetti grandi con diverse migliaia di stringhe da tradurre o più, può essere utile utilizzare file di messaggi MO binari (compilati) invece di file PO testuali. I file MO binari sono più piccoli e più veloci da leggere rispetto ai file PO equivalenti.

È possibile generare un file MO con il comando seguente:

msgfmt fr.po --no-hash -o fr.mo

Se il file PO è valido, questo comando creerà un file fr.mo oltre al file PO. Questo file MO potrà quindi essere caricato in Godot come descritto sopra.

Il file PO originale dovrebbe essere mantenuto nel controllo versioni in modo che sia possibile aggiornare la traduzione in futuro. Nel caso in cui si perda il file PO originale e si desideri decompilare un file MO in un file PO testuale, è possibile farlo con:

msgunfmt fr.mo > fr.po

Il file decompilato non includerà commenti o stringhe "fuzzy", poiché questi non vengono mai compilati nel file MO.

Estrarre le stringhe localizzabili dai file GDScript

L'estensione integrata dell'editor riconosce una varietà di modelli nel codice sorgente per estrarre stringhe localizzabili dai file GDScript, inclusi ma non solo dai seguenti:

  • tr(), tr_n(), atr() e le chiamate a atr_n();

  • assegnare le proprietà text, placeholder_text e tooltip_text;

  • add_tab(), add_item(), set_tab_title() e altre chiamate;

  • Filtri dei FileDialog come "*.png ; PNG Images".

Nota

L'argomento o l'operando di destra deve essere una stringa costante, altrimenti l'estensione non sarà in grado di valutare l'espressione e la ignorerà.

Se l'estensione estrae stringhe non necessarie, è possibile ignorarle con il commento NO_TRANSLATE. È inoltre possibile fornire informazioni aggiuntive per i traduttori attraverso il commento TRANSLATORS:. Questi commenti si devono inserire sulla stessa riga del modello riconosciuto o precederla.

$CharacterName.text = "???" # NO_TRANSLATE

# NO_TRANSLATE: Language name.
$TabContainer.set_tab_title(0, "Python")

item.text = "Tool" # TRANSLATORS: Up to 10 characters.

# TRANSLATORS: This is a reference to Lewis Carroll's poem "Jabberwocky",
# make sure to keep this as it is important to the plot.
say(tr("He took his vorpal sword in hand. The end?"))