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

Unity ti offre tre modi per esportare le tue String Tables, e quello che scegli decide la forma di tutto il lavoro. Non la qualità, non il costo: la forma. Una strada ti fornisce un singolo file con una colonna per lingua. Un’altra ti fornisce un file per lingua. Scegliere quella sbagliata per il proprio metodo di lavoro è ciò che trasforma un compito di due ore in un lavoro di due settimane.

Questa è una guida a tutte e tre le opzioni, a cosa è effettivamente contenuto in ogni export e a come gestire la traduzione senza dover modificare manualmente nemmeno una riga.

Le tre opzioni per esportare una String Table Collection

Il pacchetto Localization di Unity esporta le String Table Collection in CSV, XLIFF e Google Sheets. Questo è l’elenco completo, e tutti e tre i formati sono letti nativamente da AI Glot, quindi nessuno di essi richiede una fase di conversione.

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.

L’XLIFF le divide. Per progetto, un file XLIFF accoppia una sorgente a un unico target, quindi Unity scrive un file separato per lingua e aggiunge il codice della lingua al nome: una collection chiamata MyGame viene esportata come MyGame-ru per il russo, MyGame-ja per il giapponese. Questa non è una limitazione di Unity, è la natura del formato. Unity supporta sia XLIFF 1.2 che 2.0, e AI Glot li legge entrambi.

Google Sheets è il formato CSV con un pulsante di sincronizzazione. Invia la tua collection a un foglio e recuperala quando è compilata. Se lavori già in questo modo, esporta il foglio in CSV o XLSX e il processo sarà identico a quello del CSV.

Quindi il consiglio sincero: scegli CSV a meno che qualcosa a valle richieda XLIFF. Dieci lingue in un unico file significano un solo lavoro da eseguire, un solo piano da leggere e un solo file da re-importare.

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 sono i punti di aggancio. Unity abbina le righe tramite questi valori durante il re-import e utilizza i nomi delle intestazioni delle colonne per trovarli. Una Key tradotta non genera un errore esplicito: la riga semplicemente smette di corrispondere e una stringa torna silenziosamente al suo fallback in ogni lingua. Specifica chiaramente quali colonne tradurre e quali lasciare invariate, e questo non accadrà.

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.

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 logica all’interno del testo. Un segnaposto vuoto è {}. Uno nominato fornisce contesto al traduttore, come {PlayerName}. I plurali seguono le regole Unicode CLDR tramite un formattatore, quindi una singola voce può apparire come {0:plural:is 1 item|are {} items}. Possono anche essere annidate: {User.Address:{Street}, {City}}.

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 l’altra regola genuinamente specifica per i giochi: un pulsante che sta bene in inglese potrebbe andare a capo in tedesco. Il testo tradotto è solitamente più lungo dal 15 al 30%, e un’istruzione a livello di stringa può richiedere un limite massimo, così la riga viene scritta per adattarsi invece di essere tagliata in seguito. Specificalo una volta per le voci che risiedono in una UI a 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 \
  --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.

Il comportamento di export di Unity descritto qui deriva dalla documentazione del pacchetto Localization per la versione 1.5: il layout delle colonne CSV, la corrispondenza di Key e Id, le colonne dei commenti, il supporto XLIFF 1.2 e 2.0 e la denominazione XLIFF per singola lingua. Verifica la versione del tuo pacchetto se l’export appare diverso: i limiti di file citati sono quelli in vigore al momento della scrittura.