unity-technologies/localization

Dieser Leitfaden behandelt die Einrichtung und Konfiguration der Unity-Lokalisierung, einschließlich Gebietsschemata, Zeichen- und Asset-Tabellen, Addressables-Integration und CJK-Schriftartunterstützung über Asset-Tabellen.

0. Überprüfung der Paketinstallation

Bevor Sie irgendetwas anderes tun, überprüfen Sie, ob das Lokalisierungspaket installiert ist. Viele APIs in dieser Fertigkeit schlagen entweder stillschweigend fehl oder werfen verwirrende Fehler, wenn das Paket nicht vorhanden ist.

1. Überprüfen Sie durch Lesen des Projekts, nicht durch Fragen des Paket-Managers. Suchen Sie nach com.unity.localization in Packages/packages-lock.json. Diese Datei zeichnet auf, was Unity tatsächlich aufgelöst hat, sie ist einfaches JSON, und zum Lesen wird weder der Editor noch ein asynchroner Aufruf benötigt. (Packages/manifest.json zeichnet nur auf, was angefordert wurde, also überprüfen Sie die Sperrdatei.)
2. Installieren, falls fehlend: UnityEditor.PackageManager.Client.Add("com.unity.localization").
3. Richtig warten. Client.Add und Client.List sind asynchron: Sie geben eine Anforderung zurück, die bei der Rückkehr des Aufrufs immer noch InProgress ist, daher sagt das Lesen des Ergebnisses in derselben Anweisung nichts aus. Warten Sie auch nicht mit einer IsCompleted-Busy-Schleife; das blockiert den Hauptthread, auf dem Sie ausgeführt werden. Starten Sie stattdessen die Installation, kehren Sie zurück und überprüfen Sie packages-lock.json in einem späteren Aufruf, bis die ID erscheint. Die Installation löst auch einen Domain-Neulad aus, daher wird die erste oder zweite Überprüfung wahrscheinlich fehlschlagen; eine frische Installation wird normalerweise in wenigen Sekunden abgeschlossen.
4. Bestätigen Sie, dass die Typen tatsächlich geladen sind, bevor Sie sie verwenden, da die Sperrdatei geschrieben werden kann, bevor die Assemblies bereit sind:

   var t = System.Type.GetType(
       "UnityEngine.Localization.Settings.LocalizationSettings, Unity.Localization");
   return t != null ? "bereit" : "noch nicht geladen";
   

   Fahren Sie erst fort, wenn dies "bereit" zurückgibt.

1. Lokalisierungseinstellungen und Gebietsschemata

Wenn LocalizationEditorSettings.ActiveLocalizationSettings null ist, müssen Sie es finden oder erstellen:

1. Finden: Verwenden Sie AssetDatabase.FindAssets("t:LocalizationSettings", new[] { "Assets" }). Wenn gefunden, laden Sie das erste und weisen Sie es LocalizationEditorSettings.ActiveLocalizationSettings zu.
   • Übergeben Sie immer die Suchordner. Eine unbegrenzte FindAssets-Suche durchsucht das gesamte Projekt einschließlich schreibgeschützter Pakete, sodass sie ein Asset aus einem Paket zurückgeben kann und Sie das Projekt auf etwas verweisen, das Sie nicht bearbeiten können. Dies gilt für jeden FindAssets-Aufruf in dieser Fertigkeit.
2. Erstellen: Wenn nicht gefunden, erstellen Sie eine neue Instanz und speichern Sie sie unter Assets/Localization/LocalizationSettings.asset. Verwenden Sie ScriptableObject.CreateInstance<LocalizationSettings>() gefolgt von AssetDatabase.CreateAsset().
3. Aktivieren: Setzen Sie LocalizationEditorSettings.ActiveLocalizationSettings = settings.
4. Gebietsschemata: Stellen Sie sicher, dass Gebietsschemata (en, fr, de, usw.) vorhanden sind. Erstellen Sie sie, falls sie fehlen, und fügen Sie sie mit LocalizationEditorSettings.AddLocale(locale) zu den Einstellungen hinzu.

2. Ändern von Lokalisierungstabellen

Programmatische Änderungen an Zeichen- oder Asset-Tabellen erfordern eine Benachrichtigung des Editors. Erstellen Sie immer die erforderlichen Asset-Tabellen, es sei denn, es ist bereits eine vorhanden.

Sicheres Befüllungsmuster

Wenn Sie Tabellen aus einem Datensatz befüllen, gleichen Sie explizit mit Locale.Identifier.Code ab. Die Reihenfolge von GetLocales() ist nicht garantiert, dass sie mit Ihrem Eingabedatenarray übereinstimmt – die Annahme, dass dies der Fall ist, führt zu stillen Datenfehlzuordnungen, die nur sehr schwer zu debuggen sind. Verwenden Sie für Asset-Tabellen die GUID des Assets: table.GetEntry(sharedId) ?? table.AddEntry(sharedId, guid);.

Aktualisierung & Benachrichtigung

Nach jeder Änderung (Hinzufügen von Schlüsseln, Aktualisieren von Werten) benachrichtigen Sie den Editor, damit er seinen internen Zustand aktualisieren kann. Das Überspringen dieses Schritts führt dazu, dass der Editor bis zum nächsten Reimport veraltete Daten anzeigt.

1. Rufen Sie EditorUtility.SetDirty(collection), EditorUtility.SetDirty(collection.SharedData) für jede geänderte Table auf.
2. Unity 6+ Benachrichtigung: LocalizationEditorSettings.EditorEvents.RaiseCollectionModified(sender, collection);
3. Rufen Sie am Ende immer AssetDatabase.SaveAssets() auf.

3. UI-Lokalisierung und Layout

Namensräume & Konflikte

• Qualifizieren Sie Namen immer: Verwenden Sie UnityEngine.UI.Image, UnityEngine.UI.VerticalLayoutGroup, UnityEngine.UI.ScrollRect, UnityEngine.UI.Mask, UnityEngine.UI.CanvasScaler, UnityEngine.UI.GraphicRaycaster, UnityEngine.UI.ContentSizeFitter, UnityEngine.UI.LayoutRebuilder usw.
• UnityEngine.UI ist sowohl ein Namensraum als auch ein Klassencontainer, daher erzeugen unqualifizierte Namen CS0118 (Namensraum wie ein Typ verwendet). Die vollständige Qualifizierung vermeidet dies vollständig.
• Einzelne Instanz: Überprüfen Sie immer mit GameObject.Find("YourCanvasName") und zerstören Sie das alte, bevor Sie ein neues erstellen.
• Gebietsschema-Umschaltung: Verwenden Sie das Paket und trennen Sie Vorschau und Laufzeit. Dies sind zwei unterschiedliche Mechanismen, und ihre Vermischung ist der Grund, warum die Gebietsschema-Umschaltung oft selbst gestrickt wird.
  • Um ein Gebietsschema während der Erstellung in der Vorschau anzuzeigen, verwenden Sie das Localization Scene Controls-Fenster (Window > Asset Management > Localization Scene Controls). Dies ist nur für den Editor. Es ist kein Laufzeitfeature, daher ist es nicht die Antwort, wenn das Spiel selbst eine Spracheinstellung benötigt.
  • Um das Gebietsschema zur Laufzeit zu wechseln, weisen Sie LocalizationSettings.SelectedLocale zu. Das ist der unterstützte Einstiegspunkt, und alles, was über LocalizeStringEvent gebunden ist, wird davon aktualisiert.
  • Um festzulegen, mit welchem Gebietsschema das Spiel startet, konfigurieren Sie einen Start-Gebietsschema-Selektor auf dem Lokalisierungseinstellungs-Asset. SpecificLocaleSelector ist derjenige, der ein gewähltes Gebietsschema erzwingt; die Standardkette übernimmt ansonsten die Systemsprache.
  • Verwalten Sie NIEMALS den Gebietschema-Zustand selbst. Ein echtes Sprachmenü im Spiel ist in Ordnung und wird erwartet, solange es SelectedLocale setzt und das Paket die Änderung propagieren lässt. Was verboten ist, ist ein Debug-Dropdown oder -Menü, das eine eigene Variable für die "aktuelle Sprache" führt, Zeichenfolgen selbst austauscht oder das Paket umgeht, weil ihm sonst nichts anderes im Projekt folgt.

Lokalisierte Zeichenfolgen-Ereignisse (Robuste Bindung)

• Komponententyp prüfen: Identifizieren Sie, ob das Ziel TextMeshPro oder das alte UnityEngine.UI.Text ist.

• Richtig binden: Fügen Sie die öffentliche UnityEngine.Localization.Components.LocalizeStringEvent Komponente hinzu und verdrahten Sie sie selbst – setzen Sie StringReference auf den Tabelleneintrag und fügen Sie dann einen OnUpdateString-Listener hinzu, der den Wert an die Textkomponente zuweist (TMP_Text.text für TextMeshPro, UnityEngine.UI.Text.text für das alte Text).

  Verwenden Sie nicht UnityEditor.Localization.Plugins.TMPro.LocalizeComponent_TMPro oder dessen UGUI-Gegenstück per Reflection. Diese sind internal (gemessen in Lokalisierung 1.5.12), sodass der Zugriff auf sie bedeutet, die Zugriffskontrolle zu umgehen, um eine API zu erreichen, für die Unity keine Stabilitätszusicherung macht – sie kann sich in jeder Paketversion ändern oder verschwinden. LocalizeStringEvent ist öffentlich und erledigt dieselbe Aufgabe mit expliziter Verdrahtung.

• Layout-Neuaufbau: Rufen Sie nach dem Setzen von lokalisiertem Text oder dem Befüllen einer Liste UnityEngine.UI.LayoutRebuilder.ForceRebuildLayoutImmediate(parentTransform) auf, um sicherzustellen, dass die Abmessungen aktualisiert werden.

4. Asiatische Schriftartunterstützung (CJK)

Vermeiden Sie TMP-Fallback-Schriftarten für CJK-Gebietsschemata. Verwenden Sie stattdessen Asset-Tabellen-Schriftartaustausch für jedes spezifische Gebietsschema – Fallbacks sind unzuverlässig und schwer zu debuggen, wenn Glyphen fehlen.

Voraussetzung: TMP Essential Resources müssen importiert sein

Überprüfen Sie dies, bevor Sie eine TMP-API verwenden. In einem Projekt, das sie nie importiert hat, ist TMP_Settings.instance null und TMP-Aufrufe schlagen mit einer bloßen NullReferenceException fehl, die nichts Nützliches benennt. TMP_FontAsset.CreateFontAsset ist eine davon, daher schlägt die Schrifterstellung in der ersten Zeile mit einem Fehler fehl.