本地化与关键词

RitsuLib 将本地化明确分为两层：

• 游戏原版的 LocString 模型键管线 — 模型标题、描述等游戏内文本
• 框架自带的 I18N 辅助本地化 — Mod 自身的辅助文本

同时提供轻量关键词注册器，用来统一悬浮提示和关键词文本。

游戏原版模型本地化

游戏通过 LocString 和各本地化表来读取模型文本，常见表包括：

• cards、relics、powers、characters、card_keywords

这些键建立在 ModelId.Entry 之上。

RitsuLib 的作用仅限于让模型身份更稳定、更可预测，从而使键更容易编写。具体的模型 ID 规则见 内容注册规则。

---

CreateLocalization 与 CreateModLocalization

I18N 是 RitsuLib 提供的辅助文本本地化系统，独立于游戏的 LocString：

var i18n = RitsuLibFramework.CreateModLocalization(
    modId: "MyMod",
    instanceName: "MyMod-I18N",
    resourceFolders: ["MyMod.localization"],
    pckFolders: ["res://MyMod/localization"]);

---

资源合并顺序

I18N 支持三类来源：

1. 文件系统目录
2. 嵌入资源
3. PCK 目录

合并策略是"先到先得"：

• 先加载文件系统目录
• 嵌入资源只补缺失键
• PCK 再补剩余缺失键

---

语言代码归一化

I18N 在加载 JSON 之前会规范化语言代码：

输入	归一化结果
en、en_us、eng	eng
zh、zh_cn、zh_hans	zhs
ja、ja_jp	jpn

无法解析的语言默认回退到 eng。

---

关键词注册器

ModKeywordRegistry 用于统一定义关键词及其悬浮提示：

var keywords = RitsuLibFramework.GetKeywordRegistry("MyMod");

keywords.RegisterCardKeywordOwnedByLocNamespace(
    localKeywordStem: "brew",
    iconPath: "res://MyMod/ui/keywords/brew.png");

---

在代码里使用关键词

常用辅助方法：

方法	说明
ModKeywordRegistry.CreateHoverTip(id)	创建悬浮提示
ModKeywordRegistry.GetTitle(id)	获取标题
ModKeywordRegistry.GetDescription(id)	获取描述
keywordId.GetModKeywordCardText()	获取卡牌文本
enumerable.ToHoverTips()	批量转换为悬浮提示

---

Card pile 与顶栏按钮的悬浮提示

ModCardPileRegistry / ModTopBarButtonRegistry 注册的合格 id 分别由 GetQualifiedCardPileId、GetQualifiedTopBarButtonId 生成。static_hover_tips 中的键与关键词相同：以注册 id 为 stem，即 {id}.title、.description（card pile 另有 {id}.empty）。

---

Ancient 对话本地化

RitsuLib 内置了 AncientDialogueLocalization，它有两个作用：

• 提供从本地化键扫描对话的辅助 API
• 在游戏原版 AncientDialogueSet.PopulateLocKeys 之前，自动为已注册的 Mod 角色追加基于本地化定义的 Ancient 对话

键格式与原版保持一致：

键组件	说明
<ancientEntry>.talk.<characterEntry>.<dialogueIndex>-<lineIndex>.ancient	Ancient 台词
<ancientEntry>.talk.<characterEntry>.<dialogueIndex>-<lineIndex>.char	角色台词
可选后缀 r	重复对话
可选后缀 .sfx	音效
可选后缀 -visit	访问覆盖
可选后缀 -attack	Architect 专用攻击者覆盖

---

推荐分工

用途	工具
游戏模型的文本（标题、描述）	游戏原版 LocString 表
Mod 自有辅助文本（设置页、说明）	I18N
可复用关键词定义	ModKeywordRegistry
Ancient 对话	本地化键 + AncientDialogueLocalization

---