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

Internazionalizzazione dei giochi

Introduzione

Mentre i giochi indie o di nicchia solitamente non hanno bisogno di localizzazione, i giochi rivolti a un mercato più ampio spesso sì. Godot offre molti strumenti per rendere questo processo più semplice, quindi questo tutorial è più tipo una raccolta di suggerimenti e trucchi.

La localizzazione è solitamente effettuata da studi specifici incaricati per questo lavoro. Nonostante l'enorme quantità di software e formati di file disponibili, il metodo più comune per la localizzazione rimane ancora oggi tramite fogli di calcolo. Il processo di creazione e importazione dei fogli di calcolo è già trattato nel tutorial Importazione delle traduzioni. Se non hai ancora letto questa pagina, consigliamo di farlo prima di continuare a leggere.

Nota

Utilizzeremo la demo ufficiale come esempio; puoi scaricarla dalla Libreria dei contenuti.

Configurazione della traduzione importata

È possibile aggiornare e reimportare le traduzioni quando cambiano, ma devono comunque essere state aggiunte al progetto. Ciò si fa in Project > Project Settings > Localization > Translations:

La finestra soprastante consente di aggiungere o rimuovere traduzioni in tutto il progetto.

Localizzazione delle risorse

È anche possibile istruire Godot a utilizzare versioni alternative di risorse a seconda della lingua attuale. Questo si può utilizzare per immagini localizzate, come cartelloni, o voci localizzate.

La scheda Remaps si può utilizzare per questo:

Selezionare la risorsa da rimappare, quindi aggiungere alcune alternative per ogni lingua.

Nota

Il sistema di rimappatura delle risorse non è supportato per i DynamicFont. Per utilizzare font diversi a seconda dell'alfabeto della lingua, è possibile usare invece il sistema di alternative di DynamicFont, che consente di definire tutti i font di riserva desiderati.

Il vantaggio del sistema di alternative di DynamicFont è che funziona a prescindere dalla lingua attuale, il che lo rende ideale per attività come la chat multigiocatore, in cui la lingua del testo potrebbe non corrispondere alla lingua del client.

Impostazione automatica di una lingua

Si consiglia di impostare come predefinita la lingua preferita dall'utente, ricavabile tramite OS.get_locale_language(). Se il gioco non è disponibile in quella lingua, sarà utilizzata l'Alternativa in Project > Project Settings > General > Internationalization > Locale, oppure en se vuota. Ad ogni modo, consentire ai giocatori di cambiare la lingua nel gioco è consigliato per vari motivi (ad esempio, per la qualità della traduzione o per le preferenze del giocatore).

var language = "automatic"
# Load here language from the user settings file
if language == "automatic":
   var preferred_language = OS.get_locale_language()
   TranslationServer.set_locale(preferred_language)
else:
   TranslationServer.set_locale(language)

Localizzazione vs. lingua

Una localizzazione è solitamente una combinazione di una lingua con una regione o un paese, ma può anche contenere informazioni come un alfabeto o una variante.

Esempi:

en: Lingua inglese
en_GB: inglese in Gran Bretagna / inglese britannico
en_US: inglese negli Stati Uniti / inglese americano
en_DE: inglese in Germania

In genere, i giochi indie devono preoccuparsi solo della lingua, ma continua a leggere per maggiori informazioni.

Il motivo per cui le localizzazioni esistono si può illustrare prendendo come esempio gli Stati Uniti e la Gran Bretagna. Entrambi parlano la stessa lingua (inglese), ma differiscono in molti aspetti:

Ortografia: gray (USA), grey (GB)
Uso delle parole: eggplant (USA), aubergine (GB)
Unità di misura o valute: feet/inches (USA), metres/cm (GB)

Tuttavia, il tutto può diventare più complesso. Immagina di offrire contenuti diversi in Europa e in Cina (ad esempio, in un MMO). Dovrai tradurre ciascuna di queste varianti di contenuto in diverse lingue, memorizzandole e caricandole appropriatamente.

Conversione delle chiavi in testo

Alcuni controlli, come Button e Label, recupereranno automaticamente una traduzione se il loro testo corrisponde a una chiave di traduzione. Ad esempio, se il testo di un'etichetta è MAIN_SCREEN_GREETING1 e quella chiave esiste nella traduzione attuale, il testo sarà tradotto automaticamente.

Questo comportamento di traduzione automatica potrebbe essere indesiderato in certi casi. Ad esempio, quando si utilizza un'etichetta per visualizzare il nome di un giocatore, molto probabilmente non si desidera che il nome del giocatore sia tradotto se corrisponde a una chiave di traduzione. Per disabilitare la traduzione automatica su un nodo specifico, imposta la proprietà Auto Translate > Mode su Disabled nell'ispettore.

Nel codice, è possibile utilizzare la funzione Object.tr(). Questa funzione recupererà il testo nelle traduzioni e, se trovato, lo convertirà:

level.text = tr("LEVEL_5_NAME")
status.text = tr("GAME_STATUS_%d" % status_index)

level.Text = Tr("LEVEL_5_NAME");
status.Text = Tr($"GAME_STATUS_{statusIndex}");

Nota

Se nessun testo è visualizzato dopo aver cambiato lingua, prova a utilizzare un font diverso. Il font predefinito del progetto supporta solo un sottoinsieme dei caratteri Latin-1, che non consente di visualizzare lingue come il russo o il cinese.

Una buona risorsa per font multilingue è Noto Fonts. Assicurati di scaricare la variazione adeguata se utilizzi una lingua meno comune.

Una volta scaricato il font, carica il file TTF in una risorsa DynamicFont e usalo come font personalizzato del tuo nodo Control. Per riusarlo meglio, associa una nuova risorsa Theme al tuo nodo Control radice e definisci il DynamicFont come font predefinito nel tema.

Segnaposto

Per includere i segnaposto nelle stringhe tradotte, usa Stringe di formato in GDScript o la funzionalità equivalente in C#. Ciò consente ai traduttori di spostare liberamente la posizione dei segnaposto nella stringa, rendendo le traduzioni più naturali. È consigliato utilizzare i segnaposto denominati tramite la funzione String.format() ove possibile, poiché consentono anche ai traduttori di scegliere l'ordine in cui appaiono i segnaposto:

# The placeholder's locations can be changed, but not their order.
# This will probably not suffice for some target languages.
message.text = tr("%s picked up the %s") % ["Ogre", "Sword"]

# The placeholder's locations and order can be changed.
# Additionally, this form gives more context for translators to work with.
message.text = tr("{character} picked up the {weapon}").format({character = "Ogre", weapon = "Sword"})

Contesti di traduzione

Se si utilizza l'inglese chiaro come stringhe originali (anziché i codici di messaggi COME_QUESTO), si potrebbero verificare ambiguità quando la stessa stringa inglese si deve tradurre in stringhe diverse in certe lingue di destinazione. È possibile specificare facoltativamente un contesto di traduzione per risolvere questa ambiguità e consentire alle lingue di destinazione di utilizzare stringhe diverse, anche se la stringa originale è identica:

# "Close", as in an action (to close something).
button.set_text(tr("Close", "Actions"))

# "Close", as in a distance (opposite of "far").
distance_label.set_text(tr("Close", "Distance"))

// "Close", as in an action (to close something).
GetNode<Button>("Button").Text = Tr("Close", "Actions");

// "Close", as in a distance (opposite of "far").
GetNode<Label>("Distance").Text = Tr("Close", "Distance");

Pluralizzazione

La maggior parte delle lingue richiede stringhe diverse a seconda che un oggetto sia in forma singolare o plurale. Tuttavia, codificare la condizione "è plurale" in modo rigido a seconda che ci sia più di un oggetto non è buono in tutte le lingue.

Alcune lingue hanno più di due forme plurali e le regole sul numero di oggetti richiesti per ciascuna forma plurale variano. Godot offre supporto per la pluralizzazione in modo che le localizzazioni finali possano gestirle automaticamente.

La pluralizzazione è adatta solo con numeri interi positivi (o nulli). I valori negativi e in virgola mobile rappresentano solitamente entità fisiche per le quali singolare e plurale non sono chiaramente applicabili.

var num_apples = 5
label.text = tr_n("There is %d apple", "There are %d apples", num_apples) % num_apples

int numApples = 5;
GetNode<Label>("Label").Text = string.Format(TrN("There is {0} apple", "There are {0} apples", numApples), numApples);

Questo si può abbinare a un contesto, se necessario:

var num_jobs = 1
label.text = tr_n("%d job", "%d jobs", num_jobs, "Task Manager") % num_jobs

int numJobs = 1;
GetNode<Label>("Label").Text = string.Format(TrN("{0} job", "{0} jobs", numJobs, "Task Manager"), numJobs);

Rendere i controlli ridimensionabili

Lo stesso testo in lingue diverse può variare notevolmente in lunghezza. Per questo, assicurati di leggere il tutorial su Dimensioni e ancore, poiché potrebbe aiutare adattare le dimensioni dei controlli dinamicamente. Container può essere utile, così come le opzioni di testo a capo disponibili in Label.

Per verificare se la propria interfaccia utente supporta traduzioni con stringhe più lunghe dell'originale, è possibile abilitare la pseudolocalizzazione nelle Impostazioni avanzate del progetto. Questa sostituirà tutte le stringhe localizzabili con versioni più lunghe di se stesse, sostituendo anche alcuni caratteri nelle stringhe originali con versioni accentate (pur rimanendo leggibili). I segnaposto sono lasciati così come sono, affinché continuino a funzionare quando la pseudolocalizzazione è abilitata.

Ad esempio, la stringa Hello world, this is %s! diventa [Ĥéłłô ŵôŕłd́, ŧh̀íš íš %s!] quando la pseudolocalizzazione è abilitata.

Anche se a prima vista può sembrare strano, la pseudolocalizzazione ha diversi vantaggi:

Permette di individuare rapidamente le stringhe non localizzabili, in modo da poterle riguardare e renderle localizzabili (se ha senso farlo).
Permette di individuare gli elementi dell'interfaccia utente che non possono contenere stringhe lunghe. Molte lingue presentano traduzioni molto più lunghe del testo originale, quindi è importante assicurarsi che l'interfaccia utente si possa adattare a stringhe più lunghe del solito.
Permette di verificare se il proprio font contiene tutti i caratteri necessari per supportare diverse lingue. Tuttavia, poiché l'obiettivo della pseudolocalizzazione è mantenere leggibili le stringhe originali, non è un test efficace per verificare se un font supporta CJK o le lingue con scrittura da destra a sinistra.

Le impostazioni del progetto consentono di regolare il comportamento della pseudolocalizzazione, in modo da poterne disattivare in parti se lo si desidera.

TranslationServer

Godot fornisce un server che gestisce le traduzioni di basso livello chiamato TranslationServer. Le traduzioni si possono aggiungere o rimuovere durante l'esecuzione; anche la lingua attuale si può cambiare durante l'esecuzione.

Testo bidirezionale e rispecchiamento dell'interfaccia

L'arabo e l'ebraico si scrivono da destra a sinistra (eccetto per i numeri e le parole latine incluse), e anche l'interfaccia utente di queste lingue dovrebbe essere invertita. In alcune lingue, la forma di un glifo cambia a seconda dei caratteri circostanti.

Il supporto per i sistemi di scrittura bidirezionali e il rispecchiamento dell'interfaccia utente è trasparente: solitamente non è necessario apportare modifiche o avere alcuna conoscenza di un particolare sistema di scrittura.

Per le lingue RTL, Godot apporterà automaticamente le seguenti modifiche all'interfaccia utente:

Rispecchia le ancore e i margini sinistro/destro.
Inverte l'allineamento del testo a sinistra e a destra.
Rispecchia l'ordine orizzontale dei controlli figlio nei contenitori, e degli elementi nei controlli Tree/ItemList.
Utilizza l'ordine rispecchiato degli elementi interni dei controlli (ad esempio, il pulsante a discesa in OptionButton, l'allineamento in CheckBox/CheckButton, l'ordine delle colonne in List, le icone e l'allineamento delle linee di collegamento in TreeItem). In alcuni casi, i controlli rispecchiati utilizzano stili di tema separati.
Il sistema di coordinate non è rispecchiato.
I nodi non dell'UI (sprite, ecc.) non sono influenzati.

È possibile sovrascrivere la direzione del testo e del layout in un controllo attraverso le seguenti proprietà:

text_direction imposta la direzione base del testo. Se impostata su "auto", la direzione dipende dal primo carattere direzionale forte nel testo, secondo l'algoritmo bidirezionale Unicode.
language, sovrascrive la lingua attuale del progetto.
La proprietà structured_text_bidi_override e il callback _structured_text_parser consentono di gestire particolarmente il testo strutturato.
layout_direction, sostituisce il rispecchiamento del controllo.

Vedi anche

È possibile osservare il funzionamento della composizione da destra a sinistra attraverso il progetto demo BiDI and Font Features.

Adding break iterator data to exported project

Alcune lingue sono scritte senza spazi. In queste lingue, I ritorni a capo tra parole e tra righe richiedono più che regole sulle sequenze di caratteri. Godot include regole ICU e dati basati su un dizionario di iteratori sui ritorni, ma questi dati non sono inclusi nei progetti esportati per impostazione predefinita.

Per includerli, vai su Progetto → Impostazioni del progetto > Generale > Internazionalizzazione > Impostazioni locali e abilita Includi dati sul server di testo, quindi esporta il progetto. I dati dell'iteratore di ritorni a capo hanno una dimensione di circa 4 MB.

Sostituzione del BiDi di testo strutturato

L'algoritmo Unicode BiDi è progettato per funzionare con testo naturale e non è in grado di gestire testo con ordine di livello superiore, come nomi di file, URI, indirizzi e-mail, espressioni regolari o codice sorgente.

Ad esempio, il percorso della struttura di cartelle qui sopra verrà visualizzato incorrettamente (controllo "LineEdit" in alto). La sostituzione di testo strutturato di tipo "File" suddivide il testo in segmenti, quindi l'algoritmo BiDi è applicato a ciascuno di essi individualmente per visualizzare correttamente i nomi delle cartelle in qualsiasi lingua e preservare l'ordine corretto delle cartelle (controllo "LineEdit" in basso).

I callback personalizzati forniscono un modo per sovrascrivere il BiDi per gli altri tipi di testo strutturato.

Localizzare i numeri

I controlli progettati specificamente per inserire o mostrare numeri (ad esempio ProgressBar, SpinBox) useranno automaticamente il sistema di numerazione localizzato, mentre per l'altro controllo TextServer.format_number(string, language) si può usare per convertire i numeri arabi occidentali (0..9) nel sistema di numerazione localizzato e TextServer.parse_number(string, language) per riconvertirli.

Localizzare le icone e immagini

Icone con frecce rivolte a sinistra e a destra che forse si dovrebbero invertire per le lingue araba ed ebraica, nel caso in cui indichino movimento o direzione (ad esempio, pulsanti avanti/indietro). Altrimenti, possono rimanere invariate.

Testare le traduzioni

Potresti voler testare la traduzione di un progetto prima di pubblicarlo. Godot fornisce tre modi per farlo.

Sotto Progetto → Impostazioni del progetto > Generale > Internationalization > Locale (con le impostazioni avanzate abilitate), è presente la proprietà Test. Imposta questa proprietà sul codice della lingua che desideri testare. Godot eseguirà il progetto con quella lingua quando il progetto è eseguito (dall'editor o all'esportazione).

Tieni presente che, essendo un'impostazione del progetto, apparirà nel controllo versione quando è impostata su un valore non vuoto. Pertanto, è consigliabile reimpostarla su un valore vuoto prima effettuare il commit delle modifiche nel controllo versione.

Successivamente, dall'editor vai alla barra in alto e clicca su View nella barra in alto, poi vai su Preview Translation e seleziona la lingua che desideri mostrare in anteprima.

../../_images/locale_editor_preview.webp

Ora tutto il testo nelle scene nell'editor si dovrebbe visualizzare nella lingua selezionata.

È possibile testare le traduzioni anche eseguendo Godot dalla riga di comando. Ad esempio, per testare un gioco in francese, è possibile fornire il seguente argomento:

godot --language fr

Tradurre il nome del progetto

Il nome del progetto diventa il nome dell'app quando si esporta su sistemi operativi e piattaforme diversi. Per specificare il nome del progetto in più lingue, andare su Progetto > Impostazioni del progetto > Generale > Applicazione > Configurazione. Da qui, cliccare sul pulsante Stringa localizzabile (dimensione 0). Ora dovrebbe esserci un pulsante sottostante con la scritta Aggiungi traduzione. Cliccandoci sopra si accederà a una pagina in cui è possibile scegliere la lingua (e il paese, se necessario) per la traduzione del nome del progetto. Dopodiché, si può digitare il nome localizzato.

Se non si è sicuri del codice di lingua da utilizzare, fare riferimento alla lista di codici lingua.