98 lines
2.1 KiB
Markdown
98 lines
2.1 KiB
Markdown
|
# 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 不存在却未做兜底
|
||
|
|
- 资源服务未注册时依赖资源路径表
|