unity-technologies/localization

Ce guide couvre la configuration et la mise en place de la localisation Unity, y compris les paramètres régionaux, les tables de chaînes et d'actifs, l'intégration Addressables et la prise en charge des polices CJK via les tables d'actifs.

0. Vérification de l'installation du package

Avant toute chose, vérifiez que le package de localisation est installé. De nombreuses API de ce skill échoueront silencieusement ou lanceront des erreurs confuses si le package n'est pas présent.

1. Vérifiez en lisant le projet, pas en interrogeant le gestionnaire de packages. Recherchez com.unity.localization dans Packages/packages-lock.json. Ce fichier enregistre ce qu'Unity a réellement résolu, c'est du JSON simple, et sa lecture ne nécessite ni l'éditeur ni un appel asynchrone. (Packages/manifest.json enregistre uniquement ce qui a été demandé, vérifiez donc le fichier de verrouillage.)
2. Installez si absent : UnityEditor.PackageManager.Client.Add("com.unity.localization").
3. Attendez correctement. Client.Add et Client.List sont asynchrones : ils renvoient une requête qui est encore InProgress lorsque l'appel se termine, donc lire le résultat dans la même instruction ne vous apprend rien. N'attendez pas en boucle sur IsCompleted non plus ; cela bloquerait le thread principal sur lequel vous vous exécutez. Au lieu de cela, revenez après avoir déclenché l'installation, puis interrogez packages-lock.json dans un appel ultérieur jusqu'à ce que l'identifiant apparaisse. L'installation déclenche également un rechargement de domaine, attendez-vous donc à ce que les première ou deuxième vérifications échouent ; une nouvelle installation se résout généralement en quelques secondes.
4. Confirmez que les types sont réellement chargés avant de les utiliser, car le fichier de verrouillage peut être écrit avant que les assemblys ne soient prêts :

   var t = System.Type.GetType(
       "UnityEngine.Localization.Settings.LocalizationSettings, Unity.Localization");
   return t != null ? "ready" : "not loaded yet";
   

   Ne continuez que lorsque cela renvoie ready.

1. Paramètres de localisation et paramètres régionaux

Si LocalizationEditorSettings.ActiveLocalizationSettings est nul, vous devez le trouver ou le créer :

1. Trouver : Utilisez AssetDatabase.FindAssets("t:LocalizationSettings", new[] { "Assets" }). Si trouvé, chargez le premier et assignez-le à LocalizationEditorSettings.ActiveLocalizationSettings.
   • Passez toujours les dossiers de recherche. Un FindAssets sans portée recherche dans tout le projet, y compris les packages en lecture seule, il peut donc renvoyer un actif d'un package et vous vous retrouvez à pointer le projet vers quelque chose que vous ne pouvez pas modifier. Cela s'applique à chaque appel FindAssets dans ce skill.
2. Créer : Si non trouvé, créez une nouvelle instance et enregistrez-la dans Assets/Localization/LocalizationSettings.asset. Utilisez ScriptableObject.CreateInstance<LocalizationSettings>() suivi de AssetDatabase.CreateAsset().
3. Activer : Définissez LocalizationEditorSettings.ActiveLocalizationSettings = settings.
4. Paramètres régionaux : Assurez-vous que les paramètres régionaux (en, fr, de, etc.) existent. Créez-les si manquants et ajoutez-les aux paramètres en utilisant LocalizationEditorSettings.AddLocale(locale).

2. Modification des tables de localisation

Les modifications programmatiques des tables de chaînes ou d'actifs nécessitent une notification à l'éditeur. Créez toujours les tables d'actifs requises, sauf s'il en existe déjà une dans le projet.

Modèle de remplissage sécurisé

Lors du remplissage des tables à partir d'un ensemble de données, faites correspondre explicitement par Locale.Identifier.Code. L'ordre de GetLocales() n'est pas garanti de correspondre à votre tableau de données d'entrée — supposer qu'il le fera entraînera des discordances de données silencieuses très difficiles à déboguer. Pour les tables d'actifs, utilisez le GUID de l'actif : table.GetEntry(sharedId) ?? table.AddEntry(sharedId, guid);.

Rafraîchir et notifier

Après toute modification (ajout de clés, mise à jour de valeurs), notifiez l'éditeur pour qu'il puisse rafraîchir son état interne. Sauter cette étape laissera l'éditeur affichant des données obsolètes jusqu'au prochain réimport.

1. Appelez EditorUtility.SetDirty(collection), EditorUtility.SetDirty(collection.SharedData), sur chaque Table modifiée.
2. Notification Unity 6+ : LocalizationEditorSettings.EditorEvents.RaiseCollectionModified(sender, collection);
3. Appelez toujours AssetDatabase.SaveAssets() à la fin.

3. Localisation et disposition de l'interface utilisateur

Espaces de noms et conflits

• Qualifiez toujours les noms : Utilisez UnityEngine.UI.Image, UnityEngine.UI.VerticalLayoutGroup, UnityEngine.UI.ScrollRect, UnityEngine.UI.Mask, UnityEngine.UI.CanvasScaler, UnityEngine.UI.GraphicRaycaster, UnityEngine.UI.ContentSizeFitter, UnityEngine.UI.LayoutRebuilder, etc.
• UnityEngine.UI est à la fois un espace de noms et un conteneur de classe, donc les noms non qualifiés produisent CS0118 (espace de noms utilisé comme un type). La qualification complète évite cela entièrement.
• Instance unique : Vérifiez toujours GameObject.Find("YourCanvasName") et détruisez l'ancienne avant d'en créer une nouvelle.
• **Changement de langue : utilisez le package et gardez l'aperçu et l'exécution séparés. */ Ce sont deux mécanismes différents, et les confondre est la raison pour laquelle le changement de langue finit souvent par être fait à la main.
  • Pour prévisualiser une langue pendant la création, utilisez la fenêtre Contrôles de scène de localisation (Window > Asset Management > Localization Scene Controls). Ceci est réservé à l'éditeur. Ce n'est pas une fonctionnalité d'exécution, ce n'est donc pas la réponse lorsque le jeu lui-même a besoin d'un paramètre de langue.
  • Pour changer de langue à l'exécution, assignez LocalizationSettings.SelectedLocale. C'est le point d'entrée pris en charge, et tout ce qui est lié via LocalizeStringEvent se met à jour à partir de celui-ci.
  • Pour fixer la langue de démarrage du jeu, configurez un sélecteur de langue de démarrage sur l'actif de paramètres de localisation. SpecificLocaleSelector est celui qui force une langue choisie ; la chaîne par défaut récupère autrement la langue du système.
  • NE JAMAIS gérer manuellement l'état de la langue. Un vrai menu de langue dans le jeu est bien et attendu, tant qu'il définit SelectedLocale et laisse le package propager le changement. Ce qui est interdit, c'est une liste déroulante ou un menu de débogage qui suit sa propre variable de "langue actuelle", échange lui-même les chaînes, ou contourne le package, car rien d'autre dans le projet ne le suivra.

Événements de chaîne localisée (liaison robuste)

• Vérifiez le type de composant : Identifiez si la cible est TextMeshPro ou le texte hérité UnityEngine.UI.Text.

• Liez correctement : ajoutez le composant public UnityEngine.Localization.Components.LocalizeStringEvent et câblez-le vous-même — définissez StringReference sur l'entrée de la table, puis ajoutez un écouteur OnUpdateString qui assigne la valeur au composant de texte (TMP_Text.text pour TextMeshPro, UnityEngine.UI.Text.text pour le texte hérité).

  Ne faites pas de réflexion sur UnityEditor.Localization.Plugins.TMPro.LocalizeComponent_TMPro ou son homologue UGUI. Ceux-ci sont internal (mesuré sur Localization 1.5.12), donc y accéder signifie contourner le contrôle d'accès pour atteindre une API pour laquelle Unity ne fait aucune promesse de stabilité — elle peut changer ou disparaître dans n'importe quelle version du package. LocalizeStringEvent est public et fait le même travail avec un câblage explicite.

• Reconstruction de la disposition : Après avoir défini du texte localisé ou rempli une liste, appelez UnityEngine.UI.LayoutRebuilder.ForceRebuildLayoutImmediate(parentTransform) pour garantir la mise à jour des dimensions.

4. Prise en charge des polices pour les langues asiatiques (CJK)

Évitez les polices de secours TMP pour les langues CJK. Utilisez plutôt l'échange de polices via les tables d'actifs pour chaque langue spécifique — les polices de secours sont peu fiables et difficiles à déboguer lorsque des glyphes sont manquants.

Prérequis : Les ressources essentielles TMP doivent être importées

Vérifiez cela avant de toucher à toute API TMP. Dans un projet qui ne les a jamais importées, TMP_Settings.instance est null et les appels TMP échouent avec une simple NullReferenceException qui ne nomme rien d'utile. TMP_FontAsset.CreateFontAsset en fait partie, donc la création de police échoue dès la première ligne avec une erreur.