《英灵神殿》模组的运行时翻译/本地化辅助工具。

本地化

本地化 是一个适用于英灵神殿模组的运行时翻译助手。它会在文本即将显示前进行拦截，并用JSON规则文件中的值替换它。

这个模组旨在帮助翻译模组中硬编码的UI文本。它本身不会生成翻译；翻译规则由你提供。

这个模组的作用

• 拦截最终UI文本分配，用于 TMPro.TMP_Text.text, TMPro.TMP_Text.SetText(字符串, 布尔值)，以及 UnityEngine.UI.Text.文本.
• 施加 精确 全字符串匹配规则及 模板 基于占位符的匹配规则。
• 通过规则引擎重新处理改写后的文本，使英语基线别名能够在应用当前语言翻译之前规范化非英语硬编码文本。
• 从截获的输入中移除支持的富文本标签后再进行匹配，并将精确规则与以下内容进行比较 忽略大小写序号.
• 从以下位置加载规则文件 BepInEx/config/com.paxton0505.localization/<LanguageCode>/*.json.
• 使用 英语/*.json 作为可选的共享基线。
• 当活动游戏语言更改时重新加载规则。
• 支持顶级 翻译已启用 本地运行时开关 config.yaml.
• 包含一个游戏内开发者工具覆盖层，用于在客户端上进行实时追踪、浏览器、性能和演练场工作流，默认启用，并带有 Ctrl + F1.
• 当服务器和客户端都运行该模组时，支持仅限会话的ServerSync覆盖。
• 仅在内存中保留服务器同步的规则，不写入客户端的本地 JSON 文件。

此模组不会做什么

• 它不会为你机器翻译文本。
• 它不会修改其他模组的源文件。
• 会话结束后不会将服务器叠加层保存到磁盘。
• 在专用服务器上，不会运行本地UI翻译补丁，因为没有本地UI可供修补。

之前 / 之后

安装

1. 从Thunderstore安装模组。已声明的依赖项将自动安装： BepInExPack_Valheim, 约顿，以及 JsonDotNET.
2. 如果你手动安装，请将 本地化.dll 在 BepInEx/plugins.
3. 启动一次游戏，以便 config.yaml、插件本地化文件以及语言文件夹已创建。
4. 在以下位置创建一个或多个规则文件： BepInEx/config/com.paxton0505.localization/<LanguageCode>/.
5. 如果你想要服务器提供的叠加层，请在服务器和客户端上都安装该模组。

本地化.dll 已包含此模组使用的ServerSync实现。你无需为此插件单独添加ServerSync DLL。

文件夹布局

示例结构：

BepInEx/ config/ com.paxton0505.localization/ config.yaml Localization-English.json Localization-Chinese_Trad.json English/ Common.json Chinese_Trad/ MyMod.json

• 英语 是可选的，可用作共享基线。
• 当前语言文件夹应与游戏的语言名称匹配，例如 繁体中文.
• 每个语言文件夹内的文件按文件名的字母顺序加载。
• 本地化-*.json 文件用于插件自身的覆盖层、状态文本和回退日志字符串。

可选运行时设置

插件创建 BepInEx/配置/com.paxton0505.localization/配置.yaml 启动时如果缺失。

翻译已启用：真
调试：假
整串最长匹配模式：按词
整串最长匹配最小长度：5
追踪信息最大条目数：1024
开发者工具已启用：真
开发者工具切换快捷键：左Ctrl + F1

设置 翻译已启用：否 绕过整个翻译流程。当此项为 false 时，拦截到的 UI 文本将保持不变，运行时也会跳过规则重载，直到翻译重新启用。

设置 调试：真 以启用运行时调试模式。

全字符串最长匹配模式 控件整串最长匹配精确替换：

• 每词： 只替换那些起始和结束都位于单词边界上的片段。
• 最小长度: 仅替换可见字母/数字数量至少为的连续文本 最长匹配最小长度.
• 关保持旧版不受限制的贪婪行为。

启用后，日志将包含翻译前拦截的UI字符串、缓存命中和未命中缓存的命中、最终匹配阶段、占位符解析详情以及逐文件规则加载诊断信息。

追踪信息最大条目数 控制 Trace 页面在清除最旧条目之前保留多少个唯一条目。

已启用开发者工具 开启或关闭游戏内覆盖层。

开发者工具切换快捷键 控制覆盖热键。配置文件使用原始键名，例如 左Control + F1，而游戏内界面显示的快捷键与 Ctrl + F1.

翻译已启用, 调试, 最長整體字串匹配_*, 最大记录条数，以及 开发工具_* 全都来自本地 config.yaml服务器同步不会覆盖运行时设置。

内置开发者工具叠加层

在客户端构建中， 本地化 包含一个默认启用的游戏内开发者工具覆盖层，可通过以下方式打开 Ctrl + F1 在界面中（左Control + F1 在……里 配置文件）。

• 插件 为翻译、调试模式、全字符串最长匹配设置、跟踪源容量和叠加快捷键提供实时开关。
• 性能 显示已加载规则数量、缓存大小、命中率、耗时，并可重置指标。
• 追踪 捕获独特的截获字符串，允许暂停和搜索信息流，并显示所选条目的分阶段翻译分析。
• 浏览器 按来源、语言和文件名加载了本地与服务器规则的分组。
• 游乐场 让你能够起草精确/模板规则，针对已保存和已加载的规则进行预览，并复制纯 JSON。

根级通过以下方式对叠加层和插件拥有的标签进行本地化 本地化-*.json 文件，这些文件会独立于翻译规则文件夹进行热重载。

规则文件格式

每个JSON文件包含两个顶级数组： 精确 和 模板.

{
  "exact": [
    {
      "match": "物品已被收藏，不会被存放",
      "replace": "物品已被收藏，不会被存放"
    },
    {
      "match": "格位已被收藏，不会被存放",
      "replace": "格位已被收藏，不会被存放"
    }
  ],
  "templates": [
    {
      "match": "已将 {{$total}} 个物品从你的背包存放到附近容器中",
      "replace": "已将 {{$total}} 个物品从你的背包存放到附近容器中"
    },
    {
      "match": "<color=red>附近容器中没有 {{localize($itemName)}}</color>",
      "replace": "<color=red>附近容器中没有 {{localize($itemName)}}</color>"
    }
  ]
}

规则行为

• 精确 规则优先尝试整串查找，若整串和模板均不匹配，则回退到整串最长匹配精确替换。
• 模板 将完整的显示字符串与占位符进行匹配，例如 {{$itemName}}, {{$count}}，或者像这样的受限占位符 {{$count:int}}, {{$weight:float(int=1..3,frac=0..2)}}, {{$itemName:words(count=1..3)}}，以及 {{$mode:oneof(关闭|开启|自动)}}.
• 匹配前，插件会从截取的输入中剥离支持的富文本标签。
• 与规范化输入进行精确规则比较，使用 序数忽略大小写.
• 全串最长匹配精确替换会先在整个规范化字符串中收集匹配项，优先选择最长的非重叠精确匹配，应用这些匹配，然后重复此过程，直到不再有精确匹配为止。
• 模板字面量片段也会以不区分大小写的方式与规范化输入进行比较。
• 如果一条规则将整个字符串重写为另一个可匹配的字符串，插件会再次评估重写后的结果，直到其稳定为止。
• 模板字面量匹配在剥离标签后对标点、空格和换行完全精确。
• 受约束的占位符仅在模板中有效 比赛 string. 那 替换 字符串仍在使用 {{$name}} 和 {{localize($name)}}.
• 整数 和 浮动 接受可选前置 + 或 - 默认情况下签名。 浮动 当前使用 . 作为小数分隔符。
• 数值谓词语法使用 哪里= 与 && 诸如 >0, ≥0, 小于10, ≤10, 五，或 不等于0.
• 使用 \n 在JSON字符串中用于换行。
• 显示的输出来自规则 替换 值。从截获的源文本中提取的旧标签不会自动重新应用。
• 如果没有规则匹配，则原文保持不变。

示例：

{ "templates": [ { "match": "缺少 {{$count:int(where=>0)}} 个 {{$itemName:words(count=1..3)}}", "replace": "缺少 {{$count}} 个 {{localize($itemName)}}" } ] }

本地化() 模板内部

你可以叫 {{localize($name)}} 在一个模板替换项内。

发生这种情况时，插件按以下顺序解析该值：

1. 此插件加载的规范化精确规则，包括链式精确别名。
2. 《英灵神殿》自带的本地化表。
3. 改写后的结果会再次按照插件的标准化精确规则进行检查。
4. 若无匹配项，则返回原值。

当模板中包含应通过现有精确规则翻译的物品名称或标签时，这很有用。

捕获的占位符值来自用于匹配的同一去标签输入。归一化精确匹配和模板匹配仅重新应用紧邻匹配可见范围外层包裹的标签。整串最长匹配精确替换仅保留完整截取字符串的最外层标签。

通过英语进行链式归一化

运行时可以安全地对同一个被拦截的字符串应用多次翻译处理。

这意味着你可以使用可选的 英语 将这一层作为其他语言硬编码文本的规范化步骤，然后让活动语言层将规范化后的英文文本翻译为最终目标语言。

例如 繁体中文 活跃：

BepInEx/config/com.paxton0505.localization/English/core.json

{ "exact": [ { "match": "Packesel", "replace": "驮马" } ], "templates": [] }

BepInEx/config/com.paxton0505.localization/Chinese_Trad/core.json

{ "exact": [ { "match": "Pack horse", "replace": "馱馬" } ], "templates": [] }

显示的字符串现在可以流式排列为 馱馬 在一次UI拦截检查中。

循环映射会被安全截断，因此当规则开始循环时链会停止。

如果拦截到的文本与规则仅在大小写或支持的富文本标签上有所不同，规范化匹配仍可将其匹配。例如， <color=orange>驮马</color> 可衔接至 驮马，然后继续翻译成当前语言，同时保留译文外层的颜色标签。

加载顺序与优先级

当非英语语言处于激活状态时，各层按从基线到最高覆盖的以下顺序应用：

1. 本地 英语 文件。
2. 已同步 英语 从服务器下载文件。
3. 本地活动语言文件。
4. 已从服务器同步活动语言文件。

如果当前语言为 英语，仅使用英文层。

客户端与专用服务器行为

客户端

• 对截获的界面文本应用运行时翻译。
• 当游戏语言更改时重新加载已编译的规则。
• 当 ServerSync 值变化时，立即应用同步的服务器快照。

专用服务器

• 仅以同步模式运行。
• 初始化 ServerSync 并监视本地配置文件夹。
• 不运行本地翻译运行时或UI Harmony补丁。
• 当它是ServerSync的真相来源时，将本地规则更改发布到已连接的客户端。

热重载

• 本地配置更改受监视于 BepInEx/配置/com.paxton0505.本地化.
• 本地翻译 JSON 更改会在启用翻译时重新加载当前语言的已编译规则并清除翻译缓存。
• 根层级 本地化-*.json 更改后还会重新加载插件自身的覆盖层/状态字符串，并在覆盖层打开时重建它。
• config.yaml 变更也会被监视。改变 翻译已启用, 调试、整串最长匹配设置、追踪馈送容量或开发者工具开关设置生效均无需重启游戏。
• 在数据源头侧，重复的文件事件会经过约500毫秒的防抖处理，然后才会发布快照。
• 在接收端，同步的规则快照在到达时即被应用；该路径不受文件监视器的防抖机制影响。

专用服务器会在热重载激活以及发布新快照时记录日志。示例消息：

服务器同步权威源已启用；本地配置热重载已激活。在本地配置防抖变更后已发布本地翻译快照：2 个语言文件夹，12 个文件。

故障排除

• 如果翻译没有显示，请先确认文件夹名称与当前游戏内语言一致。
• 如果翻译完全没有显示，请检查 翻译已启用：true 在本地 config.yaml 给那位客户的。
• 如果你需要在翻译前检查截获的原始字符串，请设置 调试：真 在 BepInEx/config/com.paxton0505.localization/config.yaml 然后查看客户端日志。
• 如果开发者工具覆盖层没有打开，请验证 开发者工具已启用：真 并确认 开发者工具切换快捷键 与你预期的按键组合一致。
• 如果模板不匹配，请移除支持的富文本标签后比较渲染文本，然后检查空格、标点和换行。
• 如果你想要服务器端叠加界面，请确保服务器和客户端都安装了此模组。
• 无效的 JSON 文件或无效的模板规则会被记录并跳过。
• 客户端日志还会报告为当前语言加载了多少条确切规则和模板。

好的用例

• 翻译其他模组中硬编码的UI字符串。
• 正在为当前会话与客户端共享服务端翻译覆盖层。
• 在模板中复用精确规则翻译，其中 本地化().

自定义本地化

如果你需要为单个模组或整个模组包、私人或公共服务器、任何游戏内语言进行委托本地化，请通过Discord联系我，讨论范围、可用性和细节。

此工作流由AI辅助，因此当前覆盖率通常在90%到95%左右，无法保证100%翻译通过。