Localisation de jeux Unity : les meilleures méthodes pour traduire vos String Tables

Unity exporte les tables de chaînes au format CSV, XLIFF ou JSON, et le format choisi détermine la forme de toute l’opération. Pas la qualité, ni le coût : la forme. Le CSV vous fournit un seul fichier, avec une colonne par langue. Le XLIFF vous fournit un fichier par langue. Si le format choisi ne correspond pas à votre méthode de travail, une tâche de deux heures peut se transformer en chantier de deux semaines.

Ce guide présente les deux formats qui comptent pour la traduction, le contenu réel de chaque export et la façon de lancer la traduction sans modifier manuellement une seule ligne. Google Sheets est également abordé, mais comme fonctionnalité de synchronisation et non comme format d’export.

Les formats d’export et la synchronisation avec Google Sheets

Le manuel Unity actuel répertorie le CSV, le XLIFF et le JSON comme formats d’export, ainsi qu’un export de jeu de caractères pour les polices. Google Sheets est à part : le package peut synchroniser une feuille avec une collection de tables de chaînes. Il s’agit d’une synchronisation, et non d’un fichier exporté. AI Glot prend en charge le CSV et le XLIFF nativement : aucune conversion n’est donc nécessaire.

Cependant, ils ne sont pas interchangeables, et c’est là que ces deux minutes d’attention sont utiles :

Le CSV regroupe vos langues. Un tableau peut contenir autant de colonnes que vous le souhaitez, donc un seul fichier contient l’anglais, le français, le japonais et tout le reste en même temps. Une seule tâche de traduction peut ainsi remplir toutes les colonnes vides en un seul passage.

Le XLIFF sépare les langues. Un fichier XLIFF associe par conception une source à une cible. Unity crée donc un fichier distinct pour chaque langue et ajoute son code au nom du fichier : une collection appelée MyGame est exportée sous le nom MyGame-ru pour le russe et MyGame-ja pour le japonais. Ce n’est pas une limitation d’Unity, c’est le fonctionnement du format. Unity prend en charge XLIFF 1.2 et 2.0, les normes OASIS 1.2 et 2.0, et AI Glot lit les deux versions. En version 1.2, chaque chaîne est un trans-unit contenant une source et une cible, sous cette forme :

<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 est une synchronisation, pas un format d’export. Vous synchronisez une feuille avec votre collection, puis vous la récupérez une fois remplie. Si c’est déjà votre méthode de travail, exportez la feuille au format CSV ou XLSX : le traitement est alors identique à celui de la procédure CSV. Interrogé sur l’export de toutes les tables au format CSV, un membre de l’équipe Unity a conseillé d’utiliser Google Sheets ou XLIFF. Le manuel précise également que l’export XLIFF permet de choisir les tables à inclure.

La recommandation est donc simple : choisissez le CSV, sauf si un système en aval exige le XLIFF. La section suivante explique pourquoi les Smart Strings renforcent encore cet argument. Dix langues dans un seul fichier, c’est une seule opération, un seul forfait à consulter et un seul fichier à réimporter.

Ce que contient réellement l’export CSV

Ouvrez-le une fois et tout le flux de travail devient limpide. Un export basique possède une colonne Key, une colonne Id, et une colonne par locale nommée selon la langue et son code, comme English(en) et French(fr). Si vous exportez avec les commentaires, vous obtenez également une colonne Shared Comments ainsi qu’une colonne par locale telle que French(fr) Comments.

Deux colonnes déterminent si votre import fonctionnera ou non.

Key et Id servent à faire la correspondance. Unity s’en sert pour associer les lignes lors de la réimportation et repère ces champs grâce au nom des en-têtes de colonne. Unity a besoin de Key ou de Id pour faire correspondre une ligne. Si une Key a changé, l’entrée est considérée comme différente. Une Key traduite ne correspond donc plus à l’entrée utilisée par vos autres langues. Précisez clairement les colonnes à traduire et celles à laisser telles quelles pour éviter ce problème.

Les colonnes de commentaires sont du contexte, pas du contenu. Si votre équipe écrit des notes pour les traducteurs dans Shared Comments, ces notes sont utiles à lire, mais elles ne doivent pas être traduites. Nommez-les.

Lorsque vous réimportez le fichier, Unity vous demande de choisir un mode d’importation. Merge met à jour les clés correspondantes, ajoute les nouvelles et conserve le reste. Replace fait correspondre la collection au contenu du fichier et supprime les clés qui n’y figurent pas. Utilisez donc Merge, sauf si vous souhaitez supprimer des éléments.

Ce que chaque format conserve

La même page de la version 6000.7 indique les éléments conservés lors de chaque export. Le XLIFF ne contient que les clés, les identifiants et les valeurs, sans les indicateurs Smart, les variantes ni les commentaires. Le CSV conserve les clés, les identifiants, les indicateurs Smart, les valeurs et les commentaires, tandis que le JSON conserve les clés, les identifiants, les indicateurs Smart, les valeurs et les variantes, mais pas les commentaires. Pour une table remplie de Smart Strings, le CSV est donc plus sûr pour l’aller-retour, car l’indicateur Smart accompagne chaque ligne. Si votre prestataire exige le XLIFF, gardez la collection d’origine comme référence et réimportez avec Merge.

Ce qui pose problème, et ce n’est pas le timing

Les Smart Strings de Unity sont le véritable danger dans la String Table d’un jeu, car elles sont invisibles pour tout outil qui traduit mot par mot.

Une Smart String intègre une logique au texte. Un espace réservé vide s’écrit {}. Un espace réservé nommé donne du contexte au traducteur, comme {PlayerName}. Les pluriels suivent les règles Unicode CLDR grâce au formateur de pluriel d’Unity. Une seule entrée peut donc prendre cette forme : {0:plural:is 1 item|are {} items}. Les espaces réservés peuvent aussi être imbriqués : {User.Address:{Street}, {City}}. Les langues ne requièrent pas le même nombre de formes plurielles : le japonais en a une, tandis que le russe en compte trois ou plus (one, few, many et other dans CLDR). Une entrée anglaise au pluriel prend donc une forme différente dans chaque langue.

Un traducteur qui ne connaît pas la syntaxe pourrait réorganiser les accolades, traduire le mot plural, ou transformer utilement {PlayerName} en {NomDuJoueur}. Chacun de ces changements provoquera un crash à l’exécution plutôt qu’une simple faute de frappe, et vous ne le découvrirez que lorsqu’un joueur vous enverra une capture d’écran.

Ceci doit faire l’objet d’une instruction au niveau de la chaîne, et maîtriser cette distinction est l’élément le plus utile de cet article.

Placer une règle sur les espaces réservés dans le plan ne servira à rien. Placer une règle de colonne dans l’emplacement dédié aux chaînes ne produira aucun effet, silencieusement, car aucun fichier n’est visible à ce stade. Ces deux erreurs sont discrètes, c’est pourquoi elles méritent trente secondes d’attention.

Tant que vous y êtes, pensez à cette autre règle propre aux jeux : un bouton qui tient en anglais déborde en allemand. Selon la paire de langues, le texte traduit est souvent plus long, et les chaînes courtes sont celles qui s’allongent le plus. L’article du W3C sur la longueur du texte cite les recommandations d’IBM : prévoir une longueur de 200 à 300 % pour les chaînes de 10 caractères ou moins. Une consigne pour chaque chaîne peut fixer une limite afin que le texte soit rédigé pour tenir dans l’espace prévu, plutôt que tronqué ensuite. Indiquez-la une seule fois pour les entrées qui s’affichent dans une interface de largeur fixe.

Option 1 : utiliser le navigateur

Téléchargez le CSV via le traducteur CSV ou dans l’application, puis décrivez la tâche en une phrase. Quelque chose comme ceci, et c’est volontairement très simple :

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.

Vous recevez un plan avant tout engagement de crédits : les colonnes détectées, la portée, le nombre de mots et le coût. S’il a mal interprété votre fichier, corrigez-le en une phrase et il génère un nouveau plan. Tout est gratuit jusqu’à l’approbation, donc une mauvaise lecture ne vous coûte rien d’autre que le temps de retaper une clause.

Ensuite, téléchargez le CSV, avec les mêmes colonnes, les mêmes Key et Id, et réimportez-le dans Unity.

Option 2 : votre agent gère tout le cycle

Si vous travaillez avec Claude, Cursor, Copilot ou tout agent capable d’exécuter des commandes dans votre projet, il peut tout faire sans que vous n’ayez à ouvrir de navigateur, et peut replacer les résultats là où Unity les attend.

Installez et connectez-vous une seule fois :

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

Voici un prompt que vous pouvez donner à votre agent. Il est conçu pour être copié-collé, et les points essentiels sont expliqués ci-dessous.

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.

Il demande à l’agent de lire l’aide d’abord. Un agent qui devine le nom des flags échoue dès le premier appel et invente ensuite une raison.

Il sépare explicitement les deux types d’instructions, ce qui est tout l’intérêt de la section précédente. Rédigé ainsi, l’agent place chaque élément au bon endroit au lieu de tout fusionner en un bloc semi-fonctionnel.

Il s’arrête avant la dépense. aiglot batches approve est la seule commande qui consomme des crédits. Tout ce qui précède est gratuit et répétable, donc un agent qui bouclerait sur vos locales sans surveillance ne peut pas vous surprendre avec une facture. C’est cette caractéristique qui rend l’usage d’un agent raisonnable plutôt que risqué.

Il se termine par un chiffre à vérifier. Demander le nombre de lignes vous permet d’effectuer un test de cohérence rapide avant la réimportation.

Pour référence, voici la séquence obtenue :

# 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

Il existe également un serveur MCP, aiglot mcp, si votre agent préfère les outils au shell. Commencez par le CLI : il fonctionne dans un script, dans la CI, et vous pouvez lire exactement ce qui a été exécuté.

Si vous avez choisi l’option XLIFF

Un fichier par langue signifie une tâche par langue, ce qui est acceptable jusqu’à ce qu’il y en ait dix. Voici deux façons de gérer cela.

Mettez-les dans un seul ZIP. Jusqu’à 200 fichiers et 20 Mo, avec 4 Mo par fichier. Chaque XLIFF de l’archive doit être de la même version, 1.2 ou 2.0, mais ils peuvent avoir des langues cibles différentes, ce qui correspond exactement au format d’exportation de Unity. Une seule tâche, une seule instruction et un seul glossaire appliqués à l’ensemble.

Ou bouclez avec le CLI, comme le fait le prompt ci-dessus, un batch par fichier. Cela fait plus de tâches, mais chaque plan peut être examiné séparément, ce que préfèrent certaines équipes pour un premier essai. Dans les deux cas, les fichiers reviennent au format XLIFF dans la version d’origine, avec les segments source intacts et seulement les cibles remplies.

Le facteur clé de la qualité : votre propre vocabulaire

Tout ce qui précède relève de la technique. La raison pour laquelle un jeu traduit se lit bien ou mal dépend de la cohérence de vos termes.

Renseignez une seule fois dans le glossaire de l’espace de travail les mots qui ne doivent pas varier : noms de personnages, d’objets et de sorts, noms de factions, ou la traduction officielle d’une réplique récurrente. Ce glossaire appartient à l’espace de travail et non à une seule tâche, il s’applique donc à chaque String Table envoyée ultérieurement, y compris l’exportation que vous ferez dans six mois quand le jeu aura grandi de quatre mille entrées. C’est ce qui permet au fichier numéro vingt d’être cohérent avec le fichier numéro un.

Laissez votre agent s’en charger. Le glossaire est accessible via MCP, avec des outils pour lister, lire et modifier les termes. Ainsi, l’agent qui vient de lire vos tables de chaînes peut extraire les noms propres et les mots inventés récurrents, vous soumettre la liste et inscrire les termes approuvés dans l’espace de travail avant le premier lancement de la traduction. Un glossaire que personne ne remplit ne sert à rien, et pour un jeu contenant un millier de termes inventés, le remplir à la main est la tâche que l’on repousse indéfiniment.

C’est là qu’un traducteur automatique généraliste échoue, et la raison est mécanique plutôt qu’une question de style. Son glossaire substitue un terme dès qu’il y a correspondance, sans reconsidérer la phrase environnante. Ici, le glossaire est intégré comme une donnée sémantique pendant l’écriture de la ligne, ainsi un nom s’inflette selon la grammaire au lieu d’être simplement parachuté au milieu de celle-ci.

La portée réelle de l’outil

Ne passez pas vos premières heures de jeu par cet outil pour les publier telles quelles. Les trente premières minutes d’un jeu, la page du magasin et tout ce qu’un joueur est susceptible de citer relèvent de l’écriture, et l’écriture mérite un humain. Il s’agit de quelques centaines de mots qui portent la majeure partie de votre risque réputationnel. Payer un expert natif pour cela ne coûte pas cher en termes absolus et en vaut évidemment la peine.

Les neuf mille autres entrées constituent un travail différent, et c’est cette distinction qu’il faut assimiler: le volume et l’importance ne sont pas corrélés. Les libellés de menus, les infobulles, les descriptions d’objets, les journaux de quêtes, les textes de succès, les chaînes d’erreur: c’est là que partent réellement les heures, et c’est misérable à la main et banal en une seule passe. Traitez le gros du volume ici, puis choisissez votre propre niveau d’exigence: injectez-le directement dans le build, ou ajoutez une révision professionnelle pour vos deux marchés principaux, ou seulement pour les textes de quêtes, et laissez le reste tel quel. Aucune de ces options n’est une réparation d’un premier passage raté, et toutes elles consacrent le temps de votre réviseur à la langue plutôt qu’aux feuilles de calcul.

Si vous voulez tester cela sur un vrai fichier avant de vous engager dans un pipeline, le traducteur CSV accepte un export sans compte. Pour une vision d’ensemble, consultez notre guide pour traduire un jeu vidéo, et la page de localisation de jeux couvre les formats au-delà de Unity si votre studio publie sur plusieurs moteurs.

Le comportement d’export d’Unity décrit ici provient de la documentation du package Localization, version 1.5 : organisation des colonnes CSV, correspondance à l’aide de Key et Id, colonnes de commentaires, prise en charge de XLIFF 1.2 et 2.0, nommage des fichiers XLIFF par langue, ainsi que contenu propre à chaque format et modes Merge et Replace du manuel actuel 6000.7. Vérifiez la version de votre package si votre export diffère. Les limites de fichiers indiquées sont celles en vigueur au moment de la rédaction.