unity-technologies/localization

Este guia abrange a configuração e a personalização da localização no Unity, incluindo locais, tabelas de String e Asset, integração com Addressables e suporte a fontes CJK por meio de tabelas de Asset.

0. Verificação da Instalação do Pacote

Antes de qualquer outra coisa, verifique se o pacote de Localização está instalado. Muitas APIs deste skill falharão silenciosamente ou gerarão erros confusos se o pacote não estiver presente.

1. Verifique lendo o projeto, não perguntando ao Gerenciador de Pacotes. Procure por com.unity.localization no Packages/packages-lock.json. Esse arquivo registra o que o Unity realmente resolveu, é JSON simples e sua leitura não precisa do Editor nem de chamada assíncrona. (Packages/manifest.json apenas registra o que foi solicitado, então verifique o arquivo de bloqueio.)
2. Instale se estiver faltando: UnityEditor.PackageManager.Client.Add("com.unity.localization").
3. Aguarde corretamente. Client.Add e Client.List são assíncronos: eles retornam uma solicitação que ainda está InProgress quando a chamada retorna, portanto, ler o resultado na mesma instrução não lhe diz nada. Não faça busy-wait em IsCompleted; isso bloqueia a thread principal em que você está rodando. Em vez disso, retorne após disparar a instalação e, em seguida, consulte packages-lock.json em uma chamada posterior até que o ID apareça. A instalação também aciona uma reinicialização do domínio, então espere que a primeira ou duas consultas falhem; uma instalação nova geralmente resolve em alguns segundos.
4. Confirme se os tipos foram realmente carregados antes de usá-los, já que o arquivo de bloqueio pode ser gravado antes que os assemblies estejam prontos:

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

   Prossiga apenas quando isso retornar ready.

1. Configurações de Localização e Locais

Se LocalizationEditorSettings.ActiveLocalizationSettings for nulo, você deve encontrar ou criá-lo:

1. Encontrar: Use AssetDatabase.FindAssets("t:LocalizationSettings", new[] { "Assets" }). Se encontrado, carregue o primeiro e atribua-o a LocalizationEditorSettings.ActiveLocalizationSettings.
   • Sempre passe as pastas de pesquisa. Um FindAssets sem escopo pesquisa todo o projeto, incluindo pacotes somente leitura, então pode retornar um ativo de um pacote e você acaba apontando o projeto para algo que não pode editar. Isso se aplica a toda chamada FindAssets neste skill.
2. Criar: Se não encontrado, crie uma nova instância e salve-a em Assets/Localization/LocalizationSettings.asset. Use ScriptableObject.CreateInstance<LocalizationSettings>() seguido por AssetDatabase.CreateAsset().
3. Ativar: Defina LocalizationEditorSettings.ActiveLocalizationSettings = settings.
4. Locais: Garanta que os locais (en, fr, de, etc.) existam. Crie-os se estiverem faltando e adicione-os às configurações usando LocalizationEditorSettings.AddLocale(locale).

2. Modificando Tabelas de Localização

Alterações programáticas em tabelas de String ou Asset exigem notificação ao Editor. Sempre crie as tabelas de ativos necessárias, a menos que já exista uma no projeto.

Padrão de População Seguro

Ao popular tabelas a partir de um conjunto de dados, corresponda pelo Locale.Identifier.Code explicitamente. A ordem de GetLocales() não é garantida para corresponder ao seu array de dados de entrada — supor que corresponderá causará incompatibilidades de dados silenciosas que são muito difíceis de depurar. Para Tabelas de Asset, use o GUID do ativo: table.GetEntry(sharedId) ?? table.AddEntry(sharedId, guid);.

Atualização e Notificação

Após qualquer modificação (adicionar chaves, atualizar valores), notifique o Editor para que ele possa atualizar seu estado interno. Pular isso deixará o Editor mostrando dados obsoletos até a próxima reimportação.

1. Chame EditorUtility.SetDirty(collection), EditorUtility.SetDirty(collection.SharedData), em cada Table modificada.
2. Notificação Unity 6+: LocalizationEditorSettings.EditorEvents.RaiseCollectionModified(sender, collection);
3. Sempre chame AssetDatabase.SaveAssets() no final.

3. Localização e Layout da UI

Namespacing e Conflitos

• Sempre qualifique os nomes: Use 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 é tanto um namespace quanto um contêiner de classe, então nomes não qualificados produzem CS0118 (namespace usado como um tipo). A qualificação completa evita isso inteiramente.
• Instância Única: Sempre verifique GameObject.Find("YourCanvasName") e destrua o antigo antes de criar um novo.
• Troca de local: use o pacote e mantenha visualização e tempo de execução separados. Estes são dois mecanismos diferentes, e confundi-los é a razão pela qual a troca de local geralmente acaba sendo feita manualmente.
  • Para visualizar um local durante a criação, use a janela Localization Scene Controls (Window > Asset Management > Localization Scene Controls). Isso é apenas para o Editor. Não é um recurso de tempo de execução, então não é a resposta quando o próprio jogo precisa de uma configuração de idioma.
  • Para trocar o local em tempo de execução, atribua LocalizationSettings.SelectedLocale. Esse é o ponto de entrada suportado, e tudo vinculado por meio de LocalizeStringEvent é atualizado a partir dele.
  • Para fixar em qual local o jogo inicia, configure um seletor de local de inicialização no ativo Localization Settings. SpecificLocaleSelector é o que força um local escolhido; a cadeia padrão, caso contrário, captura o idioma do sistema.
  • NUNCA gerencie o estado do local manualmente. Um menu de idioma real no jogo é aceitável e esperado, desde que defina SelectedLocale e deixe o pacote propagar a mudança. O que é proibido é um menu ou dropdown de depuração que rastreie sua própria variável "idioma atual", troque strings por conta própria ou contorne o pacote, porque nada mais no projeto o seguirá.

Eventos de String Localizados (Vinculação Robusta)

• Verifique o Tipo de Componente: Identifique se o alvo é TextMeshPro ou o legado UnityEngine.UI.Text.

• Vincule Corretamente: adicione o componente público UnityEngine.Localization.Components.LocalizeStringEvent e conecte-o você mesmo — defina StringReference para a entrada da tabela e, em seguida, adicione um ouvinte OnUpdateString que atribua o valor ao componente de texto (TMP_Text.text para TextMeshPro, UnityEngine.UI.Text.text para Text legado).

  Não reflita em UnityEditor.Localization.Plugins.TMPro.LocalizeComponent_TMPro ou seu equivalente UGUI. Esses são internal (medido no Localization 1.5.12), então acessá-los significa contornar o controle de acesso para alcançar uma API sobre a qual a Unity não faz nenhum compromisso de estabilidade — ela pode mudar ou desaparecer em qualquer versão do pacote. LocalizeStringEvent é público e faz o mesmo trabalho com a fiação explicitamente definida.

• Reconstrução de Layout: Após definir texto localizado ou popular uma lista, chame UnityEngine.UI.LayoutRebuilder.ForceRebuildLayoutImmediate(parentTransform) para garantir que as dimensões sejam atualizadas.

4. Suporte a Fontes para Idiomas Asiáticos (CJK)

Evite TMP Fallback Fonts para locais CJK. Use a Troca de Fontes por Tabela de Asset para cada local específico — fallbacks são não confiáveis e difíceis de depurar quando glifos estão faltando.

Pré-requisito: Recursos Essenciais do TMP devem ser importados

Verifique isso antes de tocar em qualquer API TMP. Em um projeto que nunca os importou, TMP_Settings.instance é null e as chamadas TMP falham com um simples NullReferenceException que não nomeia nada útil. TMP_FontAsset.CreateFontAsset é um deles, então a criação da fonte morre na primeira linha com um erro.