LocalizationModule 多语言

LocalizationModule 提供文本、语言切换和运行时字体管理。制作端由 Tools/LocalizationBuilder 把 CSV 模板构建为按语言拆分的二进制表与 Manifest；运行时只通过完整文本 Key 查询。

子功能

• 文本加载与 Group 生命周期
• 构建模式与源文件规则
• LocalizationBuilder 配置
• Unity 运行时配置
• UI 文本绑定
• 运行时字体

快速使用

在 Localization/Templates 中创建模板，例如 Shop!.csv：

key,value,En-US
Shop.title,商店,Shop
Shop.buy,购买,Buy
Shop.price,价格：{0},Price: {0}

上例适用于 Manual 模式。运行：

Tools\LocalizationBuilder\build_localization.bat

或打开 SuperCoreKit -> Configs -> LocalizationCfg，单击 Build。

业务读取：

string title = UtilFunc.Loc("Shop.title");
string price = UtilFunc.Loc("Shop.price", 100);

UtilFunc.SetLanguage("En-US", success =>
{
    if (!success)
        return;

    // LocalizedText 会收到 LanguageChanged 并自动刷新。
});

直接使用 Module：

LocalizationModule localization = LocalizationModule.Get();
if (localization == null)
    return;

localization.TryGetText("Shop.title", out string text);
IReadOnlyList<string> languages = localization.GetLanguages();
Font mainFont = localization.GetFont(UIFontType.Main);

构建产物与设计思路

默认产物：

Assets/@ResourcePackage/Core/Localization/
├─ Loc_RuntimeManifest.bytes
├─ Zh-CN/Loc_ShopZhCN.bytes
└─ En-US/Loc_ShopEnUS.bytes

Manifest 保存语言列表、逻辑表和语言到资源 Address 的映射、Key 所属逻辑表、Group 与预加载信息。语言目录只组织文件，不进入业务 Address。

文本以逻辑表拆分，使启动常用文本可预加载，大型玩法文本可随场景或玩法 Group 加载和释放。当前语言与回退语言同时准备，使缺失翻译能够稳定回退，但不掩盖构建期的空文本或 Key 集合错误。

HotUpdateModule 在正式 LocalizationModule 初始化前还会读取 Builtin 中的启动多语言 XML，用于资源更新界面。它与正式二进制文本表职责不同：XML 只承载启动更新阶段所需的极少量文案。

注意事项

• Translate 和 Build 是两个独立步骤。Automatic 翻译后应人工复核语言 CSV，再执行 Build。
• Manual 新增语言时要同步修改所有有效模板的语言列；Automatic 新增语言时修改 language 列表并重新 Translate。
• 切换 Manual / Automatic 不会迁移或删除模板的人工语言列。
• Group 只管理 LocalizationModule 缓存，不改变资源所属 YooAsset Package。
• 占位符（如 {0}、{1:N2}）、显式转义和 Unity Rich Text 标签必须在所有语言中保持一致。
• 修改模板或语言文件后需要重新 Build，并重新收集或构建 YooAsset 资源。
• 不要在业务中硬编码 Loc_ShopZhCN；只保存完整文本 Key，并由 Manifest 定位资源。
• 字体 Prefab 不应保留直接 Font 引用；应使用 LocalizedText 或 UIFontBinding。