Lokalisierungstabellen

Eine einzige Tabelle enthält den Text Ihres Spiels in jeder Sprache: Zeilen sind Schlüssel, Spalten sind Sprachen. Eine Lokalisierungstabelle ist in jeder Hinsicht, die zählt, eine gewöhnliche SheetForge-Tabelle – sie wird importiert, validiert, exportiert, gepusht und im Round-Trip verarbeitet, genau wie eine Datentabelle –, und wenn das Paket Unity Localization (com.unity.localization) installiert ist, füllt jeder abgeschlossene Import daraus auch die eigenen StringTable-Collections des Pakets. Ihre Runtime konsumiert dann Standard-LocalizedString-Referenzen, während die Tabelle die einzige Quelle der Wahrheit bleibt.

Diese Seite behandelt den Text Ihres Spiels. Die 10-sprachige Oberfläche des Produkts selbst ist ein eigenes Thema – siehe Lokalisierung.

Die Tabellenform (`@loc`)

Eine Tabelle wird zur Lokalisierungstabelle, indem sie eine @loc-Markierungszeile trägt. Wie @overlap und @style steht sie an beliebiger Stelle über den Daten; ihre Zelle in jeder Spalte benennt den Sprachcode dieser Spalte:

@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         | 취소        |       |

Die Schlüsselspalte RecordId ist erforderlich – der Schlüsselwert jeder Zeile (ui.ok) ist der Lokalisierungsschlüssel, und der Tab-Name ist der Name der StringTable-Collection: ein Tab = eine Collection.
Eine Sprachspalte ist eine String-Spalte, deren @loc-Zelle den Code trägt (en, ko, pt-BR – ein beliebiges bezeichnerartiges Kürzel; SheetForge validiert die Schreibform, nicht die Existenz des Codes, und zwei Spalten, deren Codes sich nur in Groß-/Kleinschreibung unterscheiden, werden abgelehnt). Schreiben Sie sie als string?: Eine unübersetzte Zelle ist dann eine Abdeckungslücke, kein Importfehler – siehe Abdeckung weiter unten.
Die erste Sprachspalte ist die Quellsprache. Ihr Text ist es, was die Referenzzelle einer Datentabelle inline als Vorschau zeigt, und was das automatische Prägen schreibt.
Zwei reservierte optionale Spalten, per Namen zugeordnet: smart (ein Boolean – markiert den Eintrag als Unity-Localization-Smart-String) und comment (ein String – wird in die Kommentar-Metadaten des Eintrags synchronisiert). Sind sie vorhanden, ist die Tabelle die Wahrheit für diese Angaben; fehlen sie, lässt die Bridge die entsprechenden Tabellen-Metadaten unangetastet. Eine reservierte Spalte darf nicht zugleich einen Sprachcode tragen.
Mindestens ein Sprachcode ist erforderlich, und eine Tabelle kann nicht zugleich Enum-Definitionstabelle und Lokalisierungstabelle sein (@enum + @loc ist ein Konfliktfehler, der einmal gemeldet wird).

Alles andere ist eine gewöhnliche Tabelle: Staging und Strg+Z, Strukturbearbeitung, @style-Gruppierung, xlsx- und Google-Round-Trips, Push und die Web-App behandeln sie alle wie eine normale Tabelle. Was sich ändert, ist die Ausgabe: Ein Lokalisierungs-Tab gibt weder eine generierte Record-Klasse noch ein Database-ScriptableObject noch eine Addressables-Adresse aus. Stattdessen speist er zwei Dinge – die Schlüsselkonstanten und die Bridge.

Text aus Datentabellen referenzieren (`LocRef@Tab`)

Eine Datentabelle zeigt mit einer LocRef-Referenzspalte auf einen Lokalisierungseintrag:

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

LocRef@Strings verhält sich exakt wie die eingebauten Referenzen, die Sie bereits kennen (RecordId@Tab):

Beim Import integritätsgeprüft – ein Schlüssel, der im Tab Strings nicht existiert, ist ein strukturierter Fehler mit einem Vorschlag für die nächstliegende Übereinstimmung; ein Tippfehler stirbt beim Import, nicht zur Laufzeit. Das Ziel muss eine Lokalisierungstabelle sein (sonst LocRefTargetNotLocalizationSheet), und ein LocRef ohne @Target wird abgelehnt, mit der korrekten Schreibweise als Vorschlag.
Volle Referenz-Schienen – der durchsuchbare Schlüssel-Picker, die Umbenennungs-Propagation von Schlüsseln (das Umbenennen eines Schlüssels schreibt jede referenzierende Zelle im selben Batch um), Graph-Kanten auf der Record-Canvas, exportierte Dropdown-Regeln und Waisen-Erkennung funktionieren alle, im Editor wie in der Web-App.
Setzt sich wie jede andere Referenz zusammen – List<LocRef@Strings> und die optionale Form LocRef@Strings? (eine leere Zelle ist eine leere Referenz) funktionieren beide.
Die Zelle zeigt den Text, nicht nur den Schlüssel. Eine LocRef-Zelle zeigt den Text des Eintrags in der Quellsprache inline als Vorschau, sodass eine Tabelle voller Schlüssel dennoch wie Sätze zu lesen ist. Der Datensatz-Canvas macht dasselbe — Referenzzeilen tragen den Quelltext inline, und ein abgeschnittener Wert hält seinen vollen Text stets im Tooltip.
Das Eintippen in eine leere Zelle prägt den Eintrag. Tippen Sie den Quelltext in eine leere LocRef-Zelle, und SheetForge merkt, als eine Geste und einen Undo-Schritt, Folgendes vor: einen neuen Schlüssel in der Ziel-Lokalisierungstabelle (vorgeschlagen aus Record- und Feldnamen – benennen Sie ihn später frei um, die Propagation hält jede Referenz intakt), den von Ihnen eingetippten Text als Wert in der Quellsprache, und die Referenz in der Zelle, in die Sie getippt haben. Beide Hosts.

Was in Ihrem Code landet

Codegen gibt das Feld als LocRef aus – eine einfache serialisierbare Struct (Ziel-Tabelle und Schlüssel), die in der SheetForge-Runtime-Assembly lebt und kompiliert, ob das Unity-Localization-Paket installiert ist oder nicht; generierter Code und gebackte ScriptableObjects enthalten nie einen Pakettyp. Mit installiertem Paket überbrückt ein einziger Extension-Aufruf dorthin:

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

ToLocalizedString() existiert nur, wenn das Paket vorhanden ist (ein Versions-Define, SHEETFORGE_LOCALIZATION, schaltet die Extension-Schicht ein – derselbe Mechanismus, den SHEETFORGE_ADDRESSABLES verwendet). Ohne das Paket ist das Feld weiterhin ein wohlgeformtes Tabelle/Schlüssel-Paar, das Sie selbst konsumieren können.

Was ein Import erzeugt

Neben den regulären Ausgaben schreibt ein Import eine einzige SheetForgeLocalizationKeys.cs für das gesamte Projekt – eine statische Klasse pro Lokalisierungs-Tab (StringsKeys, …), die pro Schlüssel ein public const string enthält, sodass Spielcode StringsKeys.ui_ok statt eines nackten "ui.ok" schreiben kann und dabei Compile-Zeit-Sicherheit plus IDE-Vervollständigung erhält.

Membernamen sind die Schlüssel, zu C#-Bezeichnern bereinigt (Zeichen außerhalb von ASCII-Buchstaben, Ziffern und _ werden zu _; Kollisionen erhalten ein deterministisches numerisches Suffix). Halten Sie Schlüssel ASCII, wenn Sie brauchbare Konstanten wollen – ein vollständig nicht-ASCII-Schlüssel bereinigt sich zu einer Unterstrich-Suppe.
Wie die tabellendefinierte Enum-Datei ist die Konstantendatei eine projektweite Ausgabe und landet immer im Ordner für generierten Code der Einstellungen – derselbe Assembly-Hinweis in Möglichkeiten & Grenzen gilt entsprechend.
Ein Lokalisierungs-Tab ohne Zeilen behält eine leere Klasse, sodass das Leeren einer Tabelle Code, der den Typ referenziert, nicht bricht.

Die Unity-Localization-Bridge

Mit installiertem Paket pflegt SheetForge eine StringTable-Collection pro Lokalisierungs-Tab – Schlüssel, Werte sowie die smart-/comment-Angaben, wenn diese Spalten existieren.

Wann sie läuft: automatisch, in dem Moment, in dem ein Import abgeschlossen ist – derselbe Rang, den auch Export und Push als Ausgänge haben –, plus eine manuelle Neusynchronisierungs-Aktion, um sie auf Abruf auszuführen.
Richtung: einseitig, Tabelle → StringTables. Die Tabelle ist kanonisch; die StringTables sind Ausgabe.
Sprachen: Eine Sprache der Tabelle ohne passendes Locale-Asset im Projekt wird automatisch angelegt und im Bericht benannt. Eine Sprache, die nur im Projekt existiert, bleibt unangetastet und wird als von der Tabelle nicht abgedeckt gemeldet.
Schlüssel-Umbenennungen halten Szenen-Referenzen am Leben. Das Umbenennen eines Schlüssels im Data Studio durchläuft dieselbe Umbenennungs-Maschinerie, die jede Referenz nutzt, und die Bridge benennt den Tabelleneintrag an Ort und Stelle um, unter Erhalt seiner internen Id – ein LocalizedString in einer Szene oder einem Prefab bindet an diese Id, überlebt also die Umbenennung. Die ehrliche Grenze: Eine Umbenennung außerhalb des Studios – die Tabellenquelle direkt in Google Sheets oder Excel bearbeitet – ist nicht davon zu unterscheiden, einen Schlüssel zu löschen und einen anderen hinzuzufügen. Die Bridge legt einen frischen Eintrag an (neue Id) und behandelt den alten als Waise; Szenen-Referenzen auf den alten Eintrag zeigen weiterhin auf die Waise. Benennen Sie Schlüssel im Studio um.
Metadaten, die die Tabelle nicht abbildet, bleiben immer erhalten. Kommentare (wenn es keine comment-Spalte gibt), Excluded-Flags und alle anderen StringTable-Metadaten laufen bei jeder Synchronisierung unangetastet durch.

Externe Bearbeitungen werden erfragt, nie still zusammengeführt

Die Bridge markiert die Tabellen, die ihr gehören, und merkt sich einen Fingerabdruck der letzten Synchronisierung. Hat sich eine StringTable seither verändert – jemand hat sie im Localization-Tables-Fenster bearbeitet, oder mit Unitys eigener Google-Sheets-Erweiterung hineingezogen –, stoppt die nächste Synchronisierung und fragt nach: Überschreiben von der Tabelle aus, oder Abbruch mit einem Unterschiedsbericht. Es gibt kein stilles Zusammenführen und kein stilles Überschreiben. Wollen Sie einen Workflow mit zwei schreibenden Oberflächen, leiten Sie die andere Oberfläche stattdessen über die Tabelle – genau dafür gibt es den Übersetzungs-Export.

Verwaiste Schlüssel bleiben standardmäßig erhalten

Ein Schlüssel, der in der StringTable existiert, aber nicht mehr in der Tabelle, ist eine Waise: Er wird beibehalten, in einem Waisenbericht aufgeführt und ist über eine explizite Bereinigungsaktion entfernbar (alle auf einmal oder einzeln). Ein Einstellungs-Schalter wechselt zu Beim Synchronisieren löschen, wenn die StringTable die Tabelle exakt spiegeln soll. Nichts wird je als Nebeneffekt zerstört.

Ohne das Paket

Das Unity-Localization-Paket ist optional. Ohne es gilt:

Lokalisierungstabellen sind vollständige Tabellen – Authoring, Validierung, Abdeckung, Export, Push, xlsx, die Web-App, Schlüsselkonstanten und LocRef-Felder funktionieren alle vollständig.
Das Einzige, was wartet, ist der StringTable-Synchronisierungs-Ausgang, der einen Installationshinweis zeigt (einmal pro Sitzung) und stoppt – dasselbe Anleitungsmuster wie bei Addressables, und ebenso nie programmatisch installiert.
Jede Assembly und jede Zeile generierten Codes kompiliert ohne das Paket. Unterstützte Paketversion: 1.5 oder neuer.

Bestehende StringTables in eine Tabelle migrieren

Nutzen Sie bereits Unity Localization? Ein Rückwärts-Importer verwandelt eine bestehende StringTable-Collection in eine Lokalisierungstabelle, die direkt in Ihre Importquelle geschrieben und automatisch importiert wird – derselbe Weg, den auch das Erstellen eines Sheets nimmt. Prüfen und bearbeiten Sie sie danach wie jede andere Tabelle. Kann in die aktive Quelle vom Editor aus nicht geschrieben werden, landet die Datei neben Ihrer Export-Ausgabe, mit einem Hinweis, sie zu verschieben. Synchronisiert die Bridge diese Tabelle später zurück in dieselbe Collection, werden die Eintrags-Ids durch Abgleich der Schlüsselnamen übernommen – bestehende LocalizedString-Referenzen in Szenen und Prefabs überstehen die Migration unversehrt.

Übersetzungs-Workflows

Abdeckung: Unübersetzte Zellen werden gemeldet, nicht abgelehnt

Eine leere Sprachzelle ist kein Fehler – der Import meldet die Abdeckung pro Sprache (wie viele Schlüssel jede Sprache übersetzt hat und welche fehlen), und jeder Ausgang bleibt offen. Text trifft schrittweise ein; die Tabelle blockiert nie wegen einer unfertigen Übersetzung.

Die Sprachlinse

Arbeiten Sie jeweils in einer Sprache? Eine Sprachlinse schaltet um, welche Sprachspalten sichtbar sind. Sie ist Anzeigemetadaten aus der @style-Familie – sie berührt nie den Import-Fingerabdruck, Codegen oder irgendeine Ausgabe. Beide Hosts.

Übersetzungs-Export und Teil-Reimport

Um eine Sprache an einen Übersetzer zu übergeben, exportieren Sie eine Übersetzungs-Arbeitsmappe: Wählen Sie die Sprachen und erhalten Sie eine xlsx aus Schlüssel + Quelltext + Kommentar + einer Statusspalte, in der ein Eintrag, dessen Quelltext sich seit dem letzten Export geändert hat, als veraltet markiert wird. Kommt die Datei zurück, importieren Sie sie erneut als Teil-Merge: Zeilen werden per Schlüssel abgeglichen, und es werden nur die Sprachspalten geschrieben – Struktur, andere Sprachen und alles andere in der Tabelle bleiben unangetastet. Beide Hosts. Eine ehrliche Asymmetrie: Das Status-Gedächtnis lebt in einer maschinenlokalen Datei neben dem Unity-Projekt, daher steht in einer aus dem Browser exportierten Arbeitsmappe in der Statusspalte immer new; der Hinweis „gegen älteren Quelltext übersetzt" beim Reimport vergleicht mit dem Quelltext, den die Datei selbst mitbringt, und funktioniert daher in beiden Hosts.

XLIFF und Pseudo-Sprachen

SheetForge implementiert bewusst nicht erneut XLIFF oder Pseudo-Lokalisierung – die StringTables, die die Bridge füllt, sind gewöhnliche Unity-Localization-Tabellen, daher funktionieren der XLIFF-Export/-Import und die Pseudo-Sprachen-Werkzeuge des Pakets selbst auf ihnen wie in jedem Projekt. Denken Sie dennoch an die Einbahn-Autorität: Werkzeugausgabe, die in die StringTables geschrieben wird, ist eine externe Bearbeitung, nach der die nächste Synchronisierung fragen wird. Um Übersetzungen in der Quelle der Wahrheit zu halten, bringen Sie sie über die Tabelle zurück (die Übersetzungs-Arbeitsmappe oben), statt in die StringTables.

Zwei verwandte Grenzen, ehrlich benannt: Die Bridge deckt nur StringTables ab – AssetTables sind ein anerkannter Backlog-Punkt –, und SheetForge liefert keine sprachspezifischen Smart-Format-Helfer (koreanische grammatische Partikel zum Beispiel). Die Spalte smart markiert Einträge als Smart Strings; Formatter über das hinaus, was das Paket bietet, schreiben Sie selbst über die eigenen Erweiterungspunkte des Pakets.

In der Web-App

Eine Lokalisierungstabelle ist im Browser eine gewöhnliche Tabelle: Authoring, Validierung, Abdeckung, der LocRef-Picker mit Inline-Quelltext, das Prägen, die Sprachlinse und die Übersetzungs-Arbeitsmappe funktionieren allesamt unter web.sheetforge.workers.dev. Die StringTable-Synchronisierung ist Aufgabe des Unity-Editors – der Browser hat kein Unity-Projekt, in das er Tabellen schreiben könnte, und gibt das auch nicht vor.