Aller au contenu
SheetForge

Feuilles de localisation

Une seule feuille contient le texte de votre jeu dans toutes les langues : les lignes sont des clés, les colonnes sont des locales. Une feuille de localisation est une feuille SheetForge ordinaire à tous les égards qui comptent — elle s'importe, se valide, s'exporte, se pousse (Push) et fait l'aller-retour exactement comme une feuille de données — et lorsque le package Unity Localization (com.unity.localization) est installé, chaque import terminé remplit aussi les propres collections StringTable du package à partir d'elle. Votre runtime consomme ensuite des références LocalizedString standard tandis que la feuille reste la source unique de vérité.

Cette page traite du texte de votre jeu. L'interface en 10 langues du produit lui-même est un sujet distinct — voir Localisation.

La forme de la feuille (@loc)

Une feuille devient une feuille de localisation en portant une ligne de marqueur @loc. Comme @overlap et @style, elle peut se trouver n'importe où au-dessus des données ; sa cellule dans chaque colonne nomme le code de locale de cette colonne :

@loc     |            | en             | ko          |       |
@name    | codeName   | en             | ko          | smart | comment
@type    | RecordId   | string?        | string?     | bool? | string?
@desc    | key        | source text    | Korean      |       |
         | ui.ok      | OK             | 확인        | false | Confirm button
         | ui.cancel  | Cancel         | 취소        |       |
  • La colonne clé RecordId est obligatoire — la valeur de clé de chaque ligne (ui.ok) est la clé de localisation, et le nom de l'onglet est le nom de la collection StringTable : un onglet = une collection.
  • Une colonne de locale est une colonne de type chaîne dont la cellule @loc porte le code (en, ko, pt-BR — n'importe quelle étiquette de forme identifiant ; SheetForge valide la forme orthographique, pas l'existence du code, et deux colonnes dont les codes ne diffèrent que par la casse sont rejetées). Écrivez-les en string? : une cellule non traduite est alors un trou de couverture, pas une erreur d'import — voir Couverture ci-dessous.
  • La première colonne de locale est la locale source. Son texte est ce que la cellule de référence d'une feuille de données prévisualise en ligne, et ce que la génération automatique de clé écrit.
  • Deux colonnes optionnelles réservées, identifiées par leur nom : smart (un booléen — marque l'entrée comme Smart String Unity Localization) et comment (une chaîne — synchronisée dans les métadonnées de commentaire de l'entrée). Lorsqu'elles sont présentes, la feuille fait foi pour ces éléments ; lorsqu'elles sont absentes, le pont laisse intactes les métadonnées de table correspondantes. Une colonne réservée ne peut pas porter aussi un code de locale.
  • Au moins un code de locale est requis, et une feuille ne peut pas être à la fois une feuille d'enum et une feuille de localisation (@enum + @loc est une erreur de conflit, signalée une fois).

Tout le reste est une feuille ordinaire : la préparation et Ctrl+Z, l'édition de structure, le regroupement @style, les allers-retours xlsx et Google, Push, et l'application web traitent tout cela comme une table normale. Ce qui change, c'est la sortie : un onglet de localisation n'émet aucune classe d'enregistrement générée, aucun ScriptableObject de base de données, et aucune adresse Addressables. Il alimente à la place deux choses — les constantes de clé et le pont.

Référencer du texte depuis des feuilles de données (LocRef@Tab)

Une feuille de données pointe vers une entrée de localisation avec une colonne de référence LocRef :

@name    | codeName    | displayName
@type    | RecordId    | LocRef@Strings
@desc    | unique key  | shown in UI
         | item.sword  | item.sword.name

LocRef@Strings se comporte exactement comme les références intégrées que vous connaissez déjà (RecordId@Tab) :

  • Validée en intégrité à l'import — une clé qui n'existe pas dans l'onglet Strings est une erreur structurée avec une suggestion de correspondance la plus proche ; une faute de frappe meurt à l'import, pas à l'exécution. La cible doit être une feuille de localisation (LocRefTargetNotLocalizationSheet sinon), et un LocRef sans @Target est rejeté avec la bonne orthographe suggérée.
  • Rails de référence complets — le sélecteur de clé cherchable, la propagation de renommage de clé (renommer une clé réécrit chaque cellule qui la référence dans le même lot), les arêtes de graphe sur le canevas d'enregistrements, les règles de liste déroulante exportées, et la détection d'orphelins fonctionnent tous, aussi bien dans l'éditeur que dans l'application web.
  • Se compose comme n'importe quelle référence — List<LocRef@Strings> et la forme optionnelle LocRef@Strings? (une cellule vide est une référence vide) fonctionnent toutes les deux.
  • La cellule montre le texte, pas seulement la clé. Une cellule LocRef prévisualise en ligne le texte de la locale source de l'entrée, si bien qu'une feuille pleine de clés se lit toujours comme des phrases. Le canevas d'enregistrements fait de même : les lignes de référence portent le texte source en ligne, et une valeur tronquée garde toujours son texte complet dans l'infobulle.
  • Taper dans une cellule vide génère l'entrée. Tapez le texte source dans une cellule LocRef vide, et SheetForge prépare, comme un seul geste et une seule étape d'annulation : une nouvelle clé dans la feuille de localisation cible (suggérée à partir des noms de l'enregistrement et du champ — renommez-la librement ensuite, la propagation garde chaque référence intacte), le texte que vous avez tapé comme sa valeur de locale source, et la référence dans la cellule où vous avez tapé. Les deux hôtes.

Ce qui atterrit dans votre code

Le codegen émet le champ comme LocRef — une struct sérialisable simple (la table cible et la clé) qui vit dans l'assembly runtime de SheetForge et compile que le package Unity Localization soit installé ou non ; le code généré et les ScriptableObjects bakés ne contiennent jamais un type du package. Le package installé, un appel d'extension y fait le pont :

var text = definition.displayName.ToLocalizedString(); // UnityEngine.Localization.LocalizedString

ToLocalizedString() n'existe que lorsque le package est présent (un define de version, SHEETFORGE_LOCALIZATION, active la couche d'extension — le même mécanisme qu'utilise SHEETFORGE_ADDRESSABLES). Sans le package, le champ reste une paire table/clé bien formée que vous pouvez consommer vous-même.

Ce qu'un import génère

En plus des sorties habituelles, un import écrit un unique SheetForgeLocalizationKeys.cs pour tout le projet — une classe statique par onglet de localisation (StringsKeys, …) contenant un public const string par clé, si bien que le code de jeu peut écrire StringsKeys.ui_ok au lieu d'un "ui.ok" nu, et obtenir la sécurité à la compilation plus l'auto-complétion de l'IDE.

  • Les noms de membre sont les clés assainies en identifiants C# (les caractères hors des lettres ASCII, des chiffres et de _ deviennent _ ; les collisions reçoivent un suffixe numérique déterministe). Gardez les clés en ASCII si vous voulez des constantes utilisables — une clé entièrement non-ASCII s'assainit en une bouillie de traits de soulignement.
  • Comme le fichier d'enum défini par feuille, le fichier de constantes est une sortie au niveau du projet et atterrit toujours dans le dossier de code généré des paramètres — la même note d'assembly dans Capacités et limites s'applique.
  • Un onglet de localisation sans ligne garde une classe vide, si bien que vider une feuille ne casse pas le code qui référence le type.

Le pont Unity Localization

Le package installé, SheetForge maintient une collection StringTable par onglet de localisation — clés, valeurs, et les éléments smart/comment quand ces colonnes existent.

  • Quand il s'exécute : automatiquement, au moment où un import se termine — la même position permanente qu'Export et Push ont comme sorties — plus une action manuelle de resynchronisation pour l'exécuter à la demande.
  • Direction : à sens unique, feuille → tables. La feuille est canonique ; les tables sont la sortie.
  • Locales : une locale de feuille sans asset Locale correspondant dans le projet est créée automatiquement et nommée dans le rapport. Une locale qui n'existe que dans le projet est laissée intacte et signalée comme non couverte par la feuille.
  • Les renommages de clé gardent les références de scène vivantes. Renommer une clé dans le Data Studio passe par la même mécanique de renommage qu'utilise toute référence, et le pont renomme l'entrée de table sur place, en préservant son id interne — un LocalizedString dans une scène ou un prefab se lie à cet id, si bien qu'il survit au renommage. La frontière honnête : un renommage fait en dehors du Studio — en éditant la source de la feuille directement dans Google Sheets ou Excel — est indiscernable de la suppression d'une clé et de l'ajout d'une autre. Le pont créera une entrée neuve (nouvel id) et traitera l'ancienne comme orpheline ; les références de scène vers l'ancienne entrée continuent de pointer vers l'orpheline. Renommez les clés dans le Studio.
  • Les métadonnées que la feuille ne modélise pas sont toujours préservées. Les commentaires (quand il n'y a pas de colonne comment), les indicateurs d'exclusion, et toute autre métadonnée de table traversent chaque synchronisation intacts.

Les modifications externes font l'objet d'une question, jamais d'une fusion silencieuse

Le pont estampille les tables qu'il possède et se souvient d'une empreinte de la dernière synchronisation. Si une table a changé depuis — quelqu'un l'a modifiée dans la fenêtre Localization Tables, ou y a tiré du contenu avec l'extension Google Sheets propre à Unity — la prochaine synchronisation s'arrête et demande : écraser depuis la feuille, ou abandonner avec un rapport de différences. Il n'y a ni fusion silencieuse ni écrasement silencieux. Si vous voulez un flux à deux postes de pilotage, faites plutôt transiter l'autre poste par la feuille — c'est exactement à cela que sert l'export de traduction.

Les clés orphelines sont préservées par défaut

Une clé qui existe dans la table mais plus dans la feuille est une orpheline : elle est conservée, listée dans un rapport d'orphelines, et supprimable via une action de nettoyage explicite (toutes d'un coup ou une par une). Un interrupteur de paramètres bascule vers supprimer à la synchronisation si vous voulez que la table reflète exactement la feuille. Rien n'est jamais détruit comme effet de bord.

Sans le package

Le package Unity Localization est optionnel. Sans lui :

  • Les feuilles de localisation sont des feuilles complètes — la création, la validation, la couverture, Export, Push, xlsx, l'application web, les constantes de clé et les champs LocRef fonctionnent tous pleinement.
  • La seule chose qui attend est la sortie de synchronisation StringTable, qui affiche un avis d'installation (une fois par session) et s'arrête — le même patron de guidage qu'Addressables, et de même jamais installé de façon programmatique.
  • Chaque assembly et chaque ligne de code généré compile sans le package. Version de package prise en charge : 1.5 ou plus récente.

Migrer des tables existantes vers une feuille

Vous utilisez déjà Unity Localization ? Un importateur inverse transforme une collection StringTable existante en feuille de localisation, écrite directement dans votre source d'import et importée automatiquement — le même chemin que celui de la création de feuille. Révisez-la et modifiez-la ensuite comme n'importe quelle autre feuille. Si la source active ne peut pas être écrite depuis l'éditeur, le fichier atterrit à côté de votre sortie d'Export, accompagné d'une note vous demandant de le déplacer. Quand le pont synchronise plus tard cette feuille vers la même collection, les ids d'entrée sont hérités par correspondance de nom de clé — les références LocalizedString existantes dans les scènes et les prefabs survivent à la migration sans se casser.

Flux de traduction

Couverture : les cellules non traduites sont signalées, pas refusées

Une cellule de locale vide n'est pas une erreur — l'import signale la couverture par locale (combien de clés chaque locale a traduites, et lesquelles manquent), et chaque sortie reste ouverte. Le texte arrive de façon incrémentale ; la feuille ne bloque jamais sur une traduction inachevée.

La lentille de locale

Vous travaillez une langue à la fois ? Une lentille de locale bascule quelles colonnes de locale sont visibles. C'est une métadonnée d'affichage de la famille @style — elle ne touche jamais l'empreinte d'import, le codegen, ou une quelconque sortie. Les deux hôtes.

Export de traduction et réimport partiel

Pour confier une langue à un traducteur, exportez un classeur de traduction : choisissez les locales et obtenez un xlsx de clé + texte source + commentaire + une colonne de statut, où une entrée dont le texte source a changé depuis le dernier export est marquée obsolète. Quand le fichier revient, réimportez-le comme une fusion partielle : les lignes sont appariées par clé et seules les colonnes de locale sont écrites — la structure, les autres locales et tout le reste de la feuille restent intacts. Les deux hôtes. Une asymétrie honnête : la mémoire de statut vit dans un fichier local à la machine, à côté du projet Unity, donc un classeur exporté depuis le navigateur indique toujours new dans sa colonne de statut ; l'avis « traduit d'après un texte source plus ancien » au réimport compare avec le texte source que le fichier transporte lui-même, et fonctionne donc dans les deux hôtes.

XLIFF et pseudo-locales

SheetForge ne réimplémente délibérément pas XLIFF ni la pseudo-localisation — les tables que remplit le pont sont des tables Unity Localization ordinaires, si bien que le propre outillage d'export/import XLIFF et de pseudo-locale du package fonctionne dessus comme sur n'importe quel projet. Souvenez-vous cependant de l'autorité à sens unique : la sortie que ces outils écrivent dans les tables compte comme une modification externe que la prochaine synchronisation questionnera. Pour garder les traductions dans la source de vérité, ramenez-les via la feuille (le classeur de traduction ci-dessus) plutôt que vers les tables.

Deux frontières liées, énoncées honnêtement : le pont couvre uniquement les tables de chaînes — les tables d'assets sont un élément reconnu du backlog — et SheetForge ne livre aucun assistant Smart Format spécifique à une langue (la sélection des particules grammaticales du coréen, par exemple). La colonne smart marque les entrées comme des Smart Strings ; les formateurs au-delà de ce que fournit le package sont à écrire par vous-même via les propres points d'extension du package.

Dans l'application web

Une feuille de localisation est une feuille ordinaire dans le navigateur : la création, la validation, la couverture, le sélecteur LocRef avec texte source en ligne, la génération de clé, la lentille de locale, et le classeur de traduction fonctionnent tous sur web.sheetforge.workers.dev. La synchronisation StringTable est le travail de l'éditeur Unity — le navigateur n'a aucun projet Unity où écrire les tables, et ne prétend pas en avoir.

Pages associées