Game-localisatie in Unity: de beste manieren om je String Tables te vertalen

Unity exporteert String Tables als CSV, XLIFF of JSON. Het formaat dat je kiest, bepaalt de opzet van de hele opdracht. Niet de kwaliteit of de kosten, maar de opzet. Met CSV krijg je één bestand met een kolom per taal. Met XLIFF krijg je één bestand per taal. Kies je een formaat dat niet bij je werkwijze past, dan kan een klus van twee uur zomaar twee weken duren.

Dit is een gids voor de twee formaten die ertoe doen bij vertalingen, wat er precies in elke export staat en hoe je de vertaling uitvoert zonder ook maar één rij handmatig te bewerken. Google Sheets komt ook aan bod, maar dan als synchronisatiefunctie en niet als exportformaat.

De exportformaten en de synchronisatie met Google Sheets

In de actuele Unity-handleiding staan CSV, XLIFF en JSON als exportformaten, plus een Character Set-export voor lettertypen. Google Sheets staat hier los van: het pakket kan een sheet synchroniseren met een String Table Collection. Dat is synchronisatie, geen bestand dat je exporteert. AI Glot kan CSV en XLIFF rechtstreeks lezen, dus daarvoor is geen conversiestap nodig.

Ze zijn echter niet onderling uitwisselbaar. Dit is het deel dat twee minuten aandacht verdient:

Met CSV houd je je talen bij elkaar. Een tabel kan zoveel kolommen bevatten als je wilt. Eén bestand bevat dus tegelijk Engels, Frans, Japans en alle andere talen. Met één vertaaltaak kun je in één keer alle lege kolommen invullen.

Met XLIFF houd je de talen gescheiden. Een XLIFF-bestand koppelt standaard één brontaal aan één doeltaal. Unity maakt daarom voor elke taal een apart bestand en voegt de taalcode toe aan de bestandsnaam: een collectie met de naam MyGame wordt geëxporteerd als MyGame-ru voor Russisch en MyGame-ja voor Japans. Dat is geen beperking van Unity, maar een kenmerk van het formaat. Unity ondersteunt zowel XLIFF 1.2 als 2.0, de OASIS-standaarden 1.2 en 2.0, en AI Glot kan beide versies lezen. In versie 1.2 is elke tekenreeks een trans-unit met een bron en een doel, in deze vorm:

<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 is een synchronisatie, geen exportformaat. Je houdt een spreadsheet synchroon met je verzameling en haalt die weer op zodra hij is ingevuld. Werk je al op die manier, exporteer de spreadsheet dan als CSV of XLSX. Dan verloopt het proces hetzelfde als bij CSV. Toen een medewerker van Unity werd gevraagd hoe je alle tabellen naar CSV exporteert, verwees die naar Google Sheets of XLIFF. In de handleiding staat bovendien dat je bij het exporteren naar XLIFF kunt selecteren welke tabellen je wilt opnemen.

Dus het eerlijke advies: kies CSV, tenzij een volgende stap in je workflow XLIFF vereist. In het volgende onderdeel lees je waarom Smart Strings de doorslag geven. Tien talen in één bestand betekent één opdracht om uit te voeren, één plan om te lezen en één bestand om opnieuw te importeren.

Wat er precies in de CSV-export staat

Open het bestand één keer en de hele workflow wordt meteen duidelijk. Een standaardexport bevat een kolom Key, een kolom Id en één kolom per locale, met de taal en taalcode als naam, zoals English(en) en French(fr). Exporteer je ook opmerkingen, dan krijg je daarnaast een kolom Shared Comments en een kolom per locale, bijvoorbeeld French(fr) Comments.

Twee kolommen bepalen of je import überhaupt werkt.

Key en Id vormen de koppeling. Unity gebruikt ze om regels te matchen wanneer je opnieuw importeert, en zoekt ze op aan de hand van de kolomkoppen. Unity heeft de Key of de Id nodig om een regel te matchen. Een gewijzigde Key wordt als een andere invoer gezien. Een vertaalde Key komt dus niet overeen met de invoer die in je andere locales wordt gebruikt. Geef duidelijk aan welke kolommen je moet vertalen en welke ongewijzigd moeten blijven, dan voorkom je dit probleem.

De opmerkingskolommen zijn context, geen inhoud. Als je team in Shared Comments opmerkingen voor vertalers zet, zijn die nuttig om te lezen, maar niet om te vertalen. Benoem dat expliciet.

Wanneer je het bestand terug importeert, vraagt Unity welke importmodus je wilt gebruiken. Merge werkt overeenkomende sleutels bij, voegt nieuwe toe en laat de rest staan. Met Replace wordt de verzameling gelijkgemaakt aan het bestand en worden sleutels verwijderd die er niet in staan. Gebruik dus Merge, tenzij je iets wilt verwijderen.

Welke gegevens elk formaat behoudt

Op dezelfde pagina voor 6000.7 staat wat bij elke export behouden blijft. XLIFF bevat alleen sleutels, ID’s en waarden, zonder Smart-vlaggen, varianten of opmerkingen. CSV behoudt sleutels, ID’s, Smart-vlaggen, waarden en opmerkingen. JSON behoudt sleutels, ID’s, Smart-vlaggen, waarden en varianten, maar geen opmerkingen. Voor een tabel vol Smart Strings is CSV daarom de veiligere keuze voor een heen-en-terugbewerking: de Smart-vlag blijft bij de regel. Als je leverancier XLIFF vereist, houd dan de oorspronkelijke verzameling als hoofdversie aan en importeer opnieuw met Merge.

Wat er misgaat, en het ligt niet aan de timing

Unity’s Smart Strings vormen het echte risico in de String Table van een game. Ze zijn onzichtbaar voor alles wat woord voor woord vertaalt.

Een Smart String bevat logica in de tekst. Een lege placeholder is {}. Een benoemde placeholder geeft de vertaler context, bijvoorbeeld {PlayerName}. Meervouden volgen de Unicode CLDR-regels via Unity’s Plural formatter. Daardoor kan één invoer er zo uitzien: {0:plural:is 1 item|are {} items}. Placeholders kunnen ook in elkaar worden genest: {User.Address:{Street}, {City}}. Talen verschillen in het aantal meervoudsvormen dat ze nodig hebben: het Japans heeft er één en het Russisch drie of meer (one, few, many en other in CLDR). Eén Engelse meervoudsinvoer krijgt dus in elke taal een andere vorm.

Een vertaler die de syntaxis niet kent, verplaatst de accolades, vertaalt het woord plural of maakt {PlayerName} er behulpzaam van {NomDuJoueur}. Elk van deze fouten veroorzaakt een probleem tijdens het uitvoeren, geen tikfout. Je ontdekt het pas wanneer een speler er een screenshot van deelt.

Dit hoort in de instructie op stringniveau, en het onderscheid goed maken is het nuttigste inzicht in dit artikel.

Zet een placeholderregel in het plan en die doet niets nuttigs. Zet een kolomregel in het vak voor instructies op stringniveau en die doet helemaal niets, zonder melding, omdat er op dat moment geen bestand in beeld is. Beide fouten blijven onopgemerkt. Daarom is het de moeite waard om er dertig seconden aan te besteden.

Nu je toch bezig bent, is er nog een regel die echt specifiek is voor games: een knop die in het Engels past, loopt in het Duits over. Vertaalde tekst is vaak langer, afhankelijk van het talenpaar, en korte strings worden het sterkst uitgebreid: in het artikel van W3C over tekstlengte wordt IBM-richtlijn aangehaald: 200 tot 300% voor strings van maximaal 10 tekens. Met een instructie op stringniveau kun je een maximumlengte instellen, zodat de regel meteen passend wordt geschreven in plaats van achteraf te worden ingekort. Vermeld dit één keer voor de items in een UI met vaste breedte.

Zo voer je het uit, route één: de browser

Upload de CSV via de CSV-vertaler of in de app en beschrijf de opdracht in één zin. Bijvoorbeeld dit, bewust zonder opsmuk:

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.

Voordat er iets wordt verbruikt, krijg je een plan met de gevonden kolommen, het bereik, het aantal woorden en de kosten. Heeft de tool je bestand verkeerd gelezen, corrigeer dat dan in één zin en er wordt een nieuw plan gemaakt. Alles tot aan je goedkeuring is gratis, dus een verkeerde interpretatie kost je alleen de tijd om een clausule opnieuw te typen.

Download daarna één CSV met dezelfde kolommen en dezelfde Key en Id, en importeer die opnieuw in Unity.

Zo voer je het uit, route twee: je agent doet de hele workflow

Werk je met Claude, Cursor, Copilot of een andere agent die opdrachten in je project kan uitvoeren, dan kan die dit allemaal doen zonder dat je een browser hoeft te openen. De agent kan de resultaten ook terugzetten op de plek waar Unity ze verwacht.

Installeer de tool en meld je één keer aan:

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

Hier is een prompt die je aan je agent kunt geven. Je kunt hem direct plakken. Hieronder leggen we de belangrijke onderdelen uit.

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.

De prompt vertelt de agent om eerst de helpinformatie te lezen. Een agent die de vlaggenamen gokt, loopt al bij de eerste aanroep vast en verzint daarna een reden waarom.

De prompt maakt expliciet onderscheid tussen de twee soorten instructies, en dat is precies het doel van het bovenstaande gedeelte. Zo zet de agent elke instructie op de juiste plek, in plaats van alles samen te voegen tot één geheel dat maar half werkt.

De prompt stopt vóór de uitgave. aiglot batches approve is de enige opdracht die credits kost. Alles daarvoor is gratis en kan steeds opnieuw worden uitgevoerd. Zo kan een agent je locales onbeheerd doorlopen zonder je onverwacht met een rekening op te zadelen. Daarom kun je dit redelijkerwijs aan een agent overlaten, zonder roekeloos te zijn.

De prompt eindigt met een aantal dat je kunt controleren. Als je naar het aantal rijen vraagt, kun je in één seconde controleren of alles klopt voordat je opnieuw importeert.

Ter referentie: de stappen die hiermee worden uitgevoerd:

# 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

Er is ook een MCP-server, aiglot mcp, als je agent liever tools dan een shell gebruikt. Begin met de CLI: die werkt in een script en in CI, en je kunt precies zien wat er is uitgevoerd.

Als je voor XLIFF hebt gekozen

Eén bestand per taal betekent één taak per taal. Dat is prima, tot je er tien hebt. Je kunt het op twee manieren aanpakken.

Zet ze in één ZIP-bestand. Maximaal 200 bestanden en 20 MB, met 4 MB per bestand. Alle XLIFF-bestanden in het archief moeten dezelfde versie hebben, 1.2 of 2.0, maar ze mogen verschillende doeltalen hebben. Dat is precies hoe Unity exporteert. Eén taak, één instructie en één woordenlijst voor alle bestanden.

Of gebruik een lus met de CLI, zoals in de prompt hierboven, met één batch per bestand. Dat zijn meer opdrachten, maar je kunt elk plan afzonderlijk controleren. Sommige teams geven daar de voorkeur aan voor een eerste keer. Hoe dan ook krijg je de bestanden terug als XLIFF, in de versie waarin ze zijn aangeleverd, met de bronteksten intact en alleen de vertalingen ingevuld.

Dit bepaalt de kwaliteit: je eigen terminologie

Alles hierboven is alleen de technische afhandeling. Of een vertaalde game goed of slecht leest, hangt af van de consistentie van je terminologie.

Voeg de woorden die niet mogen veranderen eenmalig toe aan een woordenlijst voor de werkruimte: personagenamen, namen van voorwerpen en spreuken, factienamen en de vaste vertaling van terugkerende zinnen. De lijst hoort bij de werkruimte, niet bij één opdracht. Daardoor geldt die voor elke String Table die je daarna verstuurt, ook voor de export die je over zes maanden maakt, wanneer de game vierduizend items groter is. Zo sluit bestand nummer twintig aan op bestand nummer één.

Laat je agent een eerste versie opstellen. De woordenlijst is via MCP beschikbaar, met tools om termen op te sommen, te bekijken en te bewerken. Dezelfde agent die je String Tables net heeft ingelezen, kan dus terugkerende eigennamen en verzonnen woorden eruit halen, de lijst aan je voorleggen en de goedgekeurde termen aan de werkruimte toevoegen voordat de eerste vertaling begint. Een woordenlijst die niemand invult, biedt nergens bescherming. En bij een game met duizend verzonnen termen wordt het handmatig invullen ervan een taak die steeds maar wordt uitgesteld.

Hier heeft een algemene machinevertaler moeite mee. Dat komt door de manier waarop die werkt, niet door een verschil in smaak. De woordenlijst vervangt een term overal waar die voorkomt, zonder rekening te houden met de rest van de zin. Hier wordt de woordenlijst als betekenis meegenomen tijdens het schrijven, zodat een naam zich aanpast aan de grammatica in plaats van er midden in de zin te worden geplakt.

Waarvoor dit wel en niet geschikt is

Vertaal niet het eerste uur van je game hiermee om het daarna meteen uit te brengen. De eerste dertig minuten, de winkelpagina en alles wat een speler waarschijnlijk citeert, zijn schrijfwerk. Daar hoort een mens aan te werken. Het gaat om een paar honderd woorden met het grootste reputatierisico. Een moedertaalspreker daarvoor betalen kost in absolute zin weinig en is het vanzelfsprekend waard.

De andere negenduizend items zijn een heel andere klus. Dit onderscheid moet je goed onthouden: volume en belang hangen niet met elkaar samen. Menu-items, tooltips, beschrijvingen van voorwerpen, questlogboeken, achievementteksten en foutmeldingen: daar gaan de uren in zitten. Handmatig is het een ellendige klus, maar in één keer vertalen is het weinig opvallend werk. Vertaal het bulkwerk hier en bepaal zelf waar je de grens legt: zet het rechtstreeks in de build, laat je twee grootste markten professioneel nakijken of laat alleen de questteksten controleren en gebruik de rest zoals die terugkomt. Geen van deze opties is een reparatie van een slechte eerste vertaling. Met allemaal besteed je de tijd van je reviewer aan taal in plaats van spreadsheets.

Wil je het eerst op een echt bestand uitproberen voordat je een workflow vastlegt? Met de CSV-vertaler kun je zonder account een exportbestand verwerken. Lees voor het bredere overzicht onze gids voor het vertalen van een videogame. Op de pagina over game-localisatie vind je informatie over andere bestandsindelingen dan Unity, voor als je studio op meerdere engines uitbrengt.

De hier beschreven exportfuncties van Unity zijn gebaseerd op de documentatie van het Localization-pakket voor versie 1.5: de kolomindeling van CSV, de koppeling via Key en Id, de commentaarkolommen, ondersteuning voor XLIFF 1.2 en 2.0, de naamgeving van XLIFF-bestanden per taal en de inhoud per bestandsindeling en de modi Merge en Replace uit de huidige handleiding voor 6000.7. Controleer je eigen pakketversie als je export er anders uitziet. De genoemde bestandslimieten zijn de limieten die golden toen dit werd geschreven.