AlicizaX/Client/Assets/Books/Framework/Runtime/Localization.md

Localization

模块概述

Localization 模块负责语言管理、本地化表装载、键值查询与格式化输出。它支持启动时加载内置表与资源表，也支持运行时异步切换语言。

快速开始

1. 挂载 LocalizationComponent
2. 设置默认语言
3. 配置启动表或资源路径
4. 使用 GameApp.Localization.GetString()

using AlicizaX;

public sealed class LocalizationQuickStart
{
    public string GetTitle()
    {
        return GameApp.Localization.GetString("UI_Title");
    }
}

架构说明

LocalizationComponent
  └─ LocalizationService
      ├─ GameLocaizationTable
      ├─ LocalizationLanguage
      └─ LocalizationChangeEvent

核心类与接口

ILocalizationService

公开能力：

• Language
• Initialize(string language)
• ChangedLanguage(string language)
• SwitchLanguageAsync(string language, CancellationToken cancellationToken = default)
• GetString(...)
• TryGetRawString(...)
• CoverAddLocalizationConfig(...)
• IncreAddLocalizationConfig(...)
• ReloadLocalizationConfig(...)

API 参考

Initialize(string language)

• 必填参数：language
• 返回值：无

SwitchLanguageAsync(string language, CancellationToken cancellationToken = default)

• 必填参数：language
• 可选参数：cancellationToken
• 返回值：UniTask

GetString(string key, params object[] args)

• 必填参数：key
• 可选参数：args
• 返回值：string

完整使用示例

using AlicizaX;
using Cysharp.Threading.Tasks;
using UnityEngine;

public sealed class LocalizationExample : MonoBehaviour
{
    private async void Start()
    {
        Debug.Log(GameApp.Localization.GetString("UI_Start"));
        await GameApp.Localization.SwitchLanguageAsync("English");
        Debug.Log(GameApp.Localization.GetString("UI_Start"));
    }
}

最佳实践

• 统一 Key 命名规则
• 语言切换事件中只做刷新，不做重资源初始化

常见错误

• Key 不存在却未做兜底
• 资源服务未注册时依赖资源路径表