# Localization

## 模块概述

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

## 快速开始

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

```csharp
using AlicizaX;

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

## 架构说明

```text
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`

## 完整使用示例

```csharp
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 不存在却未做兜底
- 资源服务未注册时依赖资源路径表