unreal-plugin-localization

name	unreal-plugin-localization
description	翻译 UE 插件本地化 PO 文件。当用户要求本地化、翻译或国际化 Unreal Engine 插件时使用。 处理 GatherText 采集、PO 导出、AI 翻译、PO 导入和 locres 编译的完整流程。

插件本地化

将 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" 在不同上下文中可能译为 "实例"（对象实例）或 "副本"（场景实例化）。

2. 翻译每个 src 值，遵循下方翻译规范。

3. 在 pending 文件同目录下写入 translated.json：

{
  "translations": [
    {"id": 0, "dst": "静态网格体"},
    {"id": 1, "dst": "检查资源使用情况"}
  ]
}

pending 文件中的每个 id 都必须出现在输出中，不可遗漏。

翻译规范

• 保留 UE 专有名词不翻译：Actor、Blueprint、Widget、Texture2D、StaticMesh、SkeletalMesh、Material、Level、World、HLOD、LOD、Nanite、Lumen、Niagara、PCG 等
• 保留格式占位符原样：{0}、{1}、{Arg}、%s、%d 等
• 保留文件路径、资产路径、类名原样
• 使用 UE 中文编辑器标准术语（如 "Static Mesh" -> "静态网格体"）
• 简洁 — UI 标签应尽量简短
• 若 src 为空，dst 也设为空字符串

阶段 3 — 注入与编译

运行 compile 子命令。脚本自动合并 existing_translations.json（已有翻译）和 translated.json（新翻译），新翻译优先覆盖已有翻译，然后将合并结果写回 PO 文件的 msgstr 字段，最后一次 commandlet 调用完成导入 + 编译 .locres。

python "<脚本路径>" compile --uplugin "<路径>.uplugin" --cultures zh-Hans

脚本通过 stdout 输出 JSON 结果，包含 status 和详情。

完整示例

# 阶段 1：采集源文本并导出 PO（语境增强模式加 --context）
python "<脚本路径>" gather --uplugin "C:/Project/Plugins/MyPlugin/MyPlugin.uplugin" --cultures zh-Hans --context

# 阶段 2：Agent 读取 pending_translation.json（含 hint 字段），参考上下文翻译后写入 translated.json

# 阶段 3：注入翻译并编译 locres
python "<脚本路径>" compile --uplugin "C:/Project/Plugins/MyPlugin/MyPlugin.uplugin" --cultures zh-Hans

补充说明

• 脚本从 .uplugin 目录向上遍历自动查找 .uproject
• 引擎路径通过 .uproject 的 EngineAssociation 经 Windows 注册表解析
• 可指定多个目标语言：--cultures zh-Hans ja ko
• 源语言默认为 en，可通过 --native en 覆盖
• INI 配置由脚本内置模板生成，无需外部模板目录
• 标准模式独立运行，不依赖 UCP 或其他 Unreal Skill
• 语境增强模式（--context）会额外通过 UCP 读取蓝图资产中的变量/函数 DisplayName 和 Tooltip；UCP 不可用时自动跳过蓝图扫描，仅使用 C++ 上下文