Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Localizzazione tramite gettext (file PO)

Oltre a importare le traduzioni in formato CSV, Godot supporta anche il caricamento di file di traduzione scritti nel formato GNU gettext (.po basato su testo e .mo).

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).

Per la documentazione completa, consultare GNU Gettext.

Vantaggi

gettext è un formato standard, che si può modificare attraverso qualsiasi editor di testo o editor di GUI come Poedit. Questo potrebbe importare, in quanto fornisce numerosi strumenti ai traduttori, come marcare stringhe obsolete, ricercare stringhe non ancora tradotte, ecc.
gettext è supportato da piattaforme di traduzione come Transifex e Weblate, il che rende più facile collaborare alla localizzazione.
Rispetto a CSV, i file gettext funzionano 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 PO rispetto ai file CSV.

Svantaggi

I file gettext PO hanno un formato più complesso dei CSV e possono essere più difficili 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.
I file PO di gettext solitamente usano l'inglese come lingua base. I traduttori useranno questa lingua base per tradurre in altre lingue. È comunque possibile usare altre lingue come lingua base, ma non è comune.

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.

Per uno strumento GUI, è possibile scaricare Poedit dal suo Sito web ufficiale. La versione base è open source e disponibile con la licenza MIT.

Creare il modello PO

Generazione automatica utilizzando l'editor

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 di modelli 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 di Modelli nelle Impostazioni del progetto

Dopo aver aggiunto almeno una scena o uno script, cliccare su Genera nell'angolo in alto a destra, quindi specificare il percorso del file di output. Questo file si può posizionare ovunque nella cartella del progetto, ma è consigliabile salvarlo in una sottocartella 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 su Localizzazione > 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.

Se aperto con Poeditor, verranno mostrati gli avvisi appropriati se ci sono errori di sintassi. Si può anche verificare eseguendo il seguente comando gettext:

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 si potrà quindi caricare in Godot come descritto qui 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?"))

Utilizzare il contesto

Il parametro context serve per distinguere la situazione in cui è utilizzata una traduzione o per differenziare parole polisemiche (parole con più significati).

Per esempio:

tr("Start", "Main Menu")
tr("End", "Main Menu")
tr("Shop", "Main Menu")
tr("Shop", "In Game")

In un file PO gettext, una stringa con un contesto può essere definita come segue:

# Example of a string with a translation context.
msgctxt "Main Menu"
msgid "Shop"
msgstr ""

# A different source string that is identical, but with a different context.
msgctxt "In Game"
msgid "Shop"
msgstr ""

Aggiornare i file PO

Prima o poi, saranno aggiunti nuovi contenuti al gioco e ci saranno nuove stringhe da tradurre. Quando ciò accadrà, sarà necessario aggiornare i file PO esistenti per includere le nuove stringhe.

Innanzitutto, generare un nuovo file POT contenente tutte le stringhe esistenti, più quelle appena aggiunte. Dopodiché, unire i file PO esistenti con il nuovo file POT. Ci sono due modi per farlo:

Utilizzare un editor di gettext, che dovrebbe avere un'opzione per aggiornare un file PO da un file POT.
Utilizzare lo strumento msgmerge di gettext:

# 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.

Estensione personalizzata di generazione POT

Se c'è un formato da gestire in più, è possibile scrivere una propria estensione per analizzare ed estrarre le stringhe dal file personalizzato. Questa estensione estrarrà le stringhe e le scriverà nel file POT quando si clicca su Genera POT. Per saperne di più su come creare le estensioni per i parser di traduzione, consultare EditorTranslationParserPlugin.