Localizzazione giochi Unity: i modi migliori per tradurre le tue String Tables

Unity esporta le String Table in CSV, XLIFF o JSON, e il formato scelto determina l’impostazione dell’intero lavoro. Non la qualità né il costo, ma proprio l’impostazione. CSV ti dà un unico file con una colonna per lingua. XLIFF ti dà un file per lingua. Scegliere il formato sbagliato per il tuo modo di lavorare può trasformare un lavoro di due ore in uno di due settimane.

Questa guida illustra i due formati più importanti per la traduzione, cosa contiene ciascun export e come tradurre senza modificare manualmente nemmeno una riga. Parla anche di Google Sheets, ma come funzione di sincronizzazione, non come formato di export.

I formati di export e la sincronizzazione con Google Sheets

Il manuale Unity aggiornato elenca CSV, XLIFF e JSON tra i formati di export, oltre all’export Character Set per i font. Google Sheets è una cosa a parte: il pacchetto può sincronizzare un foglio con una String Table Collection, quindi si tratta di una sincronizzazione, non di un file da esportare. AI Glot legge nativamente CSV e XLIFF, perciò non serve convertirli.

Non sono comunque interscambiabili, ed è qui che vale la pena dedicare due minuti:

Il CSV tiene insieme le lingue. Una tabella può contenere tutte le colonne che desideri, quindi un singolo file trasporta contemporaneamente l’inglese, il francese, il giapponese e tutto il resto, e un unico lavoro di traduzione può compilare ogni colonna vuota in un solo passaggio.

XLIFF separa le lingue. Per definizione, un file XLIFF abbina una lingua di origine a una lingua di destinazione, quindi Unity crea un file distinto per ogni lingua e aggiunge il codice della lingua al nome: una collection chiamata MyGame viene esportata come MyGame-ru per il russo e MyGame-ja per il giapponese. Non è un limite di Unity: è proprio così che funziona il formato. Unity supporta XLIFF 1.2 e 2.0, gli standard OASIS 1.2 e 2.0, e AI Glot li legge entrambi. Nella versione 1.2, ogni stringa è un trans-unit con un elemento source e uno target, strutturati così:

<xliff version="1.2">
  <file source-language="en" target-language="fr" datatype="plaintext" original="MyGame">
    <body>
      <trans-unit id="4102">
        <source>Start game</source>
        <target>Commencer</target>
      </trans-unit>
    </body>
  </file>
</xliff>

Google Sheets è uno strumento di sincronizzazione, non un formato di export. Puoi mantenere un foglio sincronizzato con la tua collection e importarlo di nuovo una volta compilato. Se lavori già in questo modo, esporta il foglio in CSV o XLSX: il flusso di lavoro è identico a quello con CSV. Quando gli è stato chiesto come esportare tutte le tabelle in CSV, un membro dello staff di Unity ha suggerito di usare Google Sheets o XLIFF; inoltre, il manuale specifica che con l’export XLIFF puoi selezionare le tabelle da includere.

Quindi, per essere chiari: scegli CSV, a meno che un passaggio successivo del tuo flusso di lavoro non richieda XLIFF. La sezione seguente spiega perché le Smart String rendono CSV ancora più conveniente. Dieci lingue in un unico file significano un solo lavoro da avviare, un solo piano da consultare e un solo file da reimportare.

Cosa contiene effettivamente l’export CSV

Aprilo una volta e l’intero flusso di lavoro smette di essere misterioso. Un export di base ha una colonna Key, una colonna Id e una colonna per ogni locale nominata in base alla lingua e al suo codice, come English(en) e French(fr). Se esporti con i commenti, otterrai anche una colonna Shared Comments più una per locale, come French(fr) Comments.

Due colonne in questo file decidono se l’importazione funzionerà o meno.

Key e Id servono a collegare le righe. Al momento della reimportazione, Unity abbina le righe usando questi valori e li individua tramite i nomi delle colonne. Per abbinare una riga, Unity ha bisogno di Key o Id; se cambi Key, la voce viene considerata diversa. Di conseguenza, una Key tradotta non corrisponde più alla voce usata dalle altre lingue. Basta specificare chiaramente quali colonne tradurre e quali lasciare invariate per evitare questo problema.

Le colonne dei commenti sono contesto, non contenuto. Se il tuo team scrive note per i traduttori in Shared Comments, quelle note sono utili da leggere ma sbagliate da tradurre. Identificale correttamente.

Quando reimporti il file, Unity ti chiede di scegliere una modalità. Merge aggiorna le chiavi corrispondenti, aggiunge quelle nuove e conserva tutto il resto. Replace fa corrispondere la collection al contenuto del file ed elimina le chiavi che non vi compaiono. Usa Merge, a meno che tu non voglia eliminare delle voci.

Cosa conserva ciascun formato

La stessa pagina della versione 6000.7 elenca gli elementi conservati da ciascun export. XLIFF mantiene solo chiavi, ID e valori, senza flag Smart, varianti o commenti. CSV conserva chiavi, ID, flag Smart, valori e commenti, mentre JSON conserva chiavi, ID, flag Smart, valori e varianti, ma non i commenti. Se una tabella è piena di Smart String, CSV è quindi la scelta più sicura per il round trip, perché il flag Smart resta associato alla riga. Se il tuo fornitore richiede XLIFF, conserva la collection originale come versione master e reimporta usando Merge.

La cosa che rompe tutto, e non è il tempismo

Le Smart Strings di Unity sono il vero pericolo in una String Table di un gioco, e sono invisibili a chiunque traduca parola per parola.

Una Smart String contiene una logica all’interno del testo. Un segnaposto vuoto è {}. Un segnaposto con nome offre un contesto al traduttore, per esempio {PlayerName}. Le forme plurali seguono le regole Unicode CLDR tramite il formattatore Plural di Unity; una singola voce può quindi essere scritta così: {0:plural:is 1 item|are {} items}. È possibile anche annidare i segnaposto: {User.Address:{Street}, {City}}. Le lingue richiedono un numero diverso di forme plurali: il giapponese ne ha una, mentre il russo ne ha tre o più (one, few, many e other secondo CLDR). Perciò, una forma plurale inglese assume una struttura diversa in ogni lingua.

Un traduttore che non conosce la sintassi potrebbe riordinare le parentesi, tradurre la parola plural o, per fare un favore, trasformare {PlayerName} in {NomDuJoueur}. Ognuno di questi casi è un crash in fase di runtime piuttosto che un semplice refuso, e lo scoprirai quando un giocatore ne invierà uno screenshot.

Questo deve andare nelle istruzioni a livello di stringa, e comprendere questa distinzione è la cosa più utile di tutto l’articolo.

Se inserisci una regola per i segnaposto nel piano, non servirà a nulla. Se inserisci una regola per le colonne nello slot a livello di stringa, non accadrà assolutamente nulla, silenziosamente, perché in quel momento non c’è alcun file in vista. Entrambi i fallimenti sono silenziosi, ed è per questo che meritano trenta secondi di attenzione.

Già che ci sei, ecco un’altra regola specifica per i giochi: un pulsante che in inglese ci sta, in tedesco potrebbe risultare troppo largo. A seconda della combinazione linguistica, il testo tradotto è spesso più lungo; l’espansione è maggiore soprattutto per le stringhe brevi. L’articolo W3C sulle dimensioni del testo cita le linee guida IBM, che raccomandano un’espansione del 200 al 300% per le stringhe fino a 10 caratteri. Puoi indicare un limite nelle istruzioni per la singola stringa, così la traduzione viene scritta per rientrare nello spazio previsto, invece di essere accorciata in seguito. Specifica il limite una sola volta per le voci che devono stare in un’interfaccia con larghezza fissa.

Esecuzione, opzione uno: il browser

Carica il CSV nel traduttore CSV o nell’app, poi descrivi il lavoro in una frase. Qualcosa di simile a questo, deliberatamente semplice:

The source is the English(en) column. Fill the empty French(fr), German(de)
and Japanese(ja) columns. Leave Key, Id, English(en) and every Comments
column exactly as they are.

Riceverai un piano prima che venga consumato qualsiasi credito: le colonne trovate, l’ambito, il numero di parole e il costo. Se il file è stato letto male, correggilo con una frase e il piano verrà aggiornato. Tutto ciò che precede l’approvazione è gratuito, quindi un errore di lettura non ti costa nulla se non il tempo per riscrivere una clausola.

Poi scarica un CSV, con le stesse colonne e gli stessi Key e Id, e reimportalo in Unity.

Esecuzione, opzione due: il tuo agente gestisce l’intero ciclo

Se lavori con Claude, Cursor, Copilot o qualsiasi agente in grado di eseguire comandi nel tuo progetto, può fare tutto questo senza che tu debba aprire un browser, e può inserire i risultati esattamente dove Unity se li aspetta.

Installa ed effettua l’accesso una sola volta:

npm install --global @ai-glot/cli
aiglot auth login

Ecco un prompt che puoi dare al tuo agente. È scritto per essere incollato e le parti fondamentali sono spiegate sotto.

Our Unity String Table export is at Assets/Localization/Export/MyGame.csv.
Columns: Key, Id, English(en), and empty columns for French(fr), German(de)
and Japanese(ja).

Use the aiglot CLI to translate it. Run `aiglot batches create --help` and
`aiglot batches approve --help` first so you use the real flags.

Plan instruction: the source is English(en); fill only the empty French(fr),
German(de) and Japanese(ja) cells; leave Key, Id, English(en) and any
Comments column untouched.

Approval instructions: keep every curly-brace placeholder exactly as written,
including plural formatters and nested ones; never translate a placeholder
name; keep entries whose Key starts with MENU_ or HUD_ under 20 characters.

Use the lite quality tier. Show me the plan and the total cost BEFORE you
approve anything, then wait for me to confirm.

After I confirm, poll until it reaches a terminal status, download the result
over the original path, and tell me the row count so I can re-import in Unity.

Istruisce l’agente a leggere prima l’aiuto. Un agente che indovina i nomi dei flag fallisce alla prima chiamata e poi inventa una ragione per giustificarlo.

Separa esplicitamente i due tipi di istruzioni, che è proprio lo scopo della sezione precedente. Scritto in questo modo, l’agente inserisce ogni elemento nel posto giusto invece di fonderli in un unico blocco che funziona a metà.

Si ferma prima della spesa. aiglot batches approve è l’unico comando che consuma crediti. Tutto ciò che precede è gratuito e ripetibile, quindi un agente che cicla sulle tue lingue senza supervisione non potrà sorprenderti con un conto imprevisto. Questa caratteristica rende ragionevole, e non sconsiderato, affidare l’operazione a un agente.

Termina con un numero da controllare. Richiedere il numero di righe ti permette di fare un test di coerenza rapido prima di reimportare.

Per riferimento, ecco la sequenza che seguirà:

# 1. Create the job. Free. Returns a plan and an id.
id=$(aiglot batches create Assets/Localization/Export/MyGame.csv \
      --instruction "The source is English(en). Fill only the empty French(fr), German(de) and Japanese(ja) cells. Leave Key, Id, English(en) and Comments columns unchanged." \
      --json | jq -r '.data.id')

# 2. Read the plan for free, and only then commit.
aiglot batches get "$id" --json | jq '.data.plan'

# 3. The only step that spends credits.
aiglot batches approve "$id" --quality lite --yes \
  --instructions "Keep every curly-brace placeholder exactly as written. Never translate a placeholder name. Keep MENU_ and HUD_ entries under 20 characters."

# 4. Wait for a TERMINAL status, not for a specific one.
until status=$(aiglot batches get "$id" --json | jq -r '.data.status'); \
  [ "$status" = "completed" ] || [ "$status" = "failed" ] || [ "$status" = "cancelled" ]; do
  sleep 5
done

# 5. Back into the project.
[ "$status" = "completed" ] && \
  aiglot batches download "$id" --output Assets/Localization/Export/MyGame.csv

Esiste anche un server MCP, aiglot mcp, se il tuo agente preferisce gli strumenti a una shell. Inizia con la CLI: funziona in uno script, funziona in CI e puoi leggere esattamente cosa è stato eseguito.

Se hai scelto la strada XLIFF

Un file per lingua significa un lavoro per lingua, il che va bene finché non diventano dieci. Ci sono due modi per gestirlo.

Mettili in un unico ZIP. Fino a 200 file e 20 MB, con un massimo di 4 MB per file. Ogni XLIFF nell’archivio deve essere della stessa versione, 1.2 o 2.0, ma possono avere lingue di destinazione diverse, che è esattamente il formato prodotto dall’export di Unity. Un unico lavoro, un’unica istruzione, un unico glossario applicato all’intero set.

Oppure usa un ciclo con la CLI, come fa il prompt sopra, con un batch per file. Più lavori, ma ogni piano è revisionabile separatamente, cosa che alcuni team preferiscono per la prima esecuzione. In entrambi i casi, i file tornano come XLIFF nella versione originale, con i segmenti sorgente intatti e solo i target compilati.

La parte che decide la qualità: il tuo vocabolario

Tutto quanto sopra è solo infrastruttura. Il motivo per cui un gioco tradotto si legge bene o male dipende dalla coerenza dei tuoi termini.

Inserisci una sola volta nel glossario dello spazio di lavoro le parole che non devono cambiare: nomi dei personaggi, nomi di oggetti e incantesimi, nomi delle fazioni, la traduzione ufficiale di una frase ricorrente. Il glossario appartiene allo spazio di lavoro e non a un singolo lavoro, quindi si applica a ogni String Table che invierai in futuro, incluso l’export che farai tra sei mesi quando il gioco sarà cresciuto di quattromila voci. È questo che rende il file numero venti coerente con il file numero uno.

Lascia che sia il tuo agente a bozzarlo. Il glossario è accessibile tramite MCP, con strumenti per elencare, leggere e modificare i termini. Quindi, lo stesso agente che ha appena letto le tue String Tables può estrarre i nomi propri e i termini inventati ricorrenti, fornirti l’elenco e inserire quelli approvati nel workspace prima della prima traduzione. Un glossario che nessuno compila non protegge nulla e, per un gioco con mille termini inventati, compilarne uno a mano è il compito che viene rimandato a tempo indeterminato.

È qui che un traduttore automatico generico fatica, e il motivo è meccanico piuttosto che una questione di gusto. Il suo glossario sostituisce un termine ovunque corrisponda, senza riconsiderare la frase circostante. In questo caso, il glossario viene integrato come significato mentre la riga viene scritta, quindi un nome si flette secondo la grammatica invece di essere semplicemente inserito a metà frase.

L’ambito reale di questo strumento

Non far passare attraverso questo processo l’ora d’apertura del tuo gioco per poi pubblicarlo. I primi trenta minuti di un gioco, la pagina dello store e tutto ciò che un giocatore è probabile che citi sono scrittura, e la scrittura merita una persona. Si tratta di poche centinaia di parole che portano con sé la maggior parte del rischio reputazionale, quindi pagare un esperto madrelingua è economico in termini assoluti e ovviamente ne vale la pena.

Le altre novemila voci sono un lavoro diverso, e questa è la distinzione da interiorizzare: volume e importanza non sono correlati. Etichette dei menu, tooltip, descrizioni degli oggetti, log delle missioni, testi degli obiettivi, stringhe di errore: è qui che finiscono effettivamente le ore di lavoro, ed è un compito misero a mano e banale in un unico passaggio. Gestisci qui il grosso, poi scegli il tuo limite: inseriscilo direttamente nella build, oppure aggiungi una revisione professionale per i tuoi due mercati principali, o solo per i testi delle missioni, e lascia il resto così come torna. Nessuna di queste opzioni è la riparazione di un primo passaggio errato, e tutte permettono al tuo revisore di spendere il tempo sulla lingua invece che sui fogli di calcolo.

Se vuoi provarlo su un file reale prima di impegnarti in una pipeline, il traduttore CSV accetta un export senza account. Il quadro generale è nella nostra guida alla traduzione di un videogioco e la pagina sulla localizzazione dei giochi copre i formati oltre Unity se il tuo studio pubblica su più di un motore.

Le informazioni sul comportamento degli export Unity descritte qui provengono dalla documentazione della versione 1.5 del pacchetto Localization: layout delle colonne CSV, abbinamento tramite Key e Id, colonne dei commenti, supporto per XLIFF 1.2 e 2.0, convenzione per i nomi dei file XLIFF per lingua e contenuti specifici dei formati, nonché modalità Merge e Replace del manuale aggiornato alla versione 6000.7. Se il tuo export ha un aspetto diverso, verifica la versione del pacchetto in uso. I limiti dei file indicati sono quelli in vigore al momento della stesura.