unreal-plugin-localization

插件本地化

将 Unreal Engine 插件的编辑器 UI 文本翻译为目标语言。工作流使用 Python 辅助脚本完成所有重活（PO 解析、commandlet 调用），Agent 只负责翻译精简 JSON。

脚本路径

读取本 SKILL.md 时你已知其绝对路径，将文件名替换为 scripts/ue_localization.py 即为脚本路径。不要搜索或 glob 查找。

工作流

用户提供 .uplugin 路径和目标语言。在执行之前，先询问用户是否启用「语境增强模式」：

是否启用语境增强模式？该模式会扫描插件源码和蓝图资产，为每个待翻译条目附加代码上下文（所在文件、行号、周围注释、蓝图变量/函数的 DisplayName 和 Tooltip），帮助产出更准确的翻译。启用后需要更多时间和Token。

用户确认后，按以下三个阶段依次执行。

阶段 1 — 采集与导出

运行 gather 子命令。脚本自动从 .uplugin 向上查找 .uproject，通过 EngineAssociation + Windows 注册表推断引擎路径，确保 .uplugin 中存在 LocalizationTargets，然后一次 commandlet 调用完成采集 + 导出 PO，最后将可翻译条目提取为精简 JSON。

# 标准模式
python "<脚本路径>" gather --uplugin "<路径>.uplugin" --cultures zh-Hans

# 语境增强模式（加 --context）
python "<脚本路径>" gather --uplugin "<路径>.uplugin" --cultures zh-Hans --context

用户选择启用语境增强模式时，加上 --context 标志。

脚本通过 stdout 输出 JSON 结果：

• status: "ok" 或 "error"
• pending_files: pending_translation.json 路径列表（每个目标语言一个）
• context_enhanced: （仅语境增强模式）true
• context_entries: （仅语境增强模式）成功提取到上下文的条目总数（C++ + 蓝图）
• context_blueprint_entries: （仅语境增强模式且 UCP 可用）从蓝图资产中提取到上下文的条目数量

脚本支持增量翻译：PO 文件中已有 msgstr（非空翻译）的条目不会出现在 pending 列表中，同时已有翻译会保存到同目录的 existing_translations.json。因此 pending_translation.json 中的 total 可能为 0（表示无需翻译）。

阶段 2 — 翻译

先检查 pending_translation.json 的 total 字段：

• 若 total 为 0，跳过该文件的翻译，直接进入阶段 3
• 若 total > 0，对每个条目执行翻译

对每个需要翻译的 pending_translation.json：

1. 读取该文件，内容为精简条目数组：

{
  "source_lang": "en",
  "target_lang": "zh-Hans",
  "total": 42,
  "entries": [
    {"id": 0, "ctx": "Namespace.Key", "src": "Static Mesh"},
    {"id": 1, "ctx": "Namespace.Key2", "src": "Check resource usage",
     "hint": "[Utils/MeshValidator.cpp:45] | Validates static mesh LOD count"}
  ]
}

若启用了语境增强模式，部分条目会包含 hint 字段。hint 来源有两种：

• C++ 源码：格式为 [文件:行号] | 周围注释/代码摘要
• 蓝图资产（需 UCP 可用）：格式为 [BP_MyActor.Variable:Health] | ToolTip: Current health points

翻译时务必参考 hint 来判断术语在具体场景中的含义，从而选用更恰当的译法。例如同一个 "Instance" 在不同上下文中可能译为 "实例"（对象实例）或 "副本"（场景实例化）。