ComfyUI 全中文汉化实战笔记

原创于 2026-09-22 10:45:25 发布 · 260 阅读

4 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

收录于

大模型

COMfyUI

ComfyUI 全中文汉化实战笔记

日期：2026-09-22
环境：AutoDL 容器 connect.westd.seetacloud.com:38657，ComfyUI 0.35.0 + 前端 comfyui_frontend_package 1.52.7，RTX PRO 6000 Blackwell
结论：10 个自定义节点包共 561 个节点 100% 中文化，0 残留，核心节点随界面语言一并切换。

文章目录

ComfyUI 全中文汉化实战笔记

一、问题现象

ComfyUI 界面里节点名称中英文混杂：

核心节点（KSampler、VAE 加载器等）和 MiniMax H3 时间线导演台 显示中文
其余 9 个自定义节点包（KJNodes、WanVideoWrapper、VHS、controlnet_aux 等 561 个节点）全部英文

二、原因：两套互相独立的翻译机制

1. 前端内置语言包（管核心节点）

前端 1.52.7 自带 en / zh / zh-TW / ru / ja / ko / fr / es / ar / tr / pt-BR / fa / he / it 语言包
核心节点（nodes.py 65 个 + comfy_extras 约 700 个 + comfy_api_nodes 约 370 个）的翻译全部内置在前端 bundle 里，不需要任何外部文件
语言由用户设置 Comfy.Locale 控制。若不设置，前端 getDefaultLocale() 回落到 navigator.languages（浏览器语言）——所以换浏览器/换机器可能出现"有的中文有的英文"

2. 自定义节点翻译（管插件节点）

后端 app/custom_node_manager.py 的 /i18n 端点：build_translations()（带 lru_cache，改文件必须重启才生效）扫描所有 custom_nodes/*/locales/<语言代码>/ 目录，合并返回
收集的文件：main.json + nodeDefs.json + commands.json + settings.json
前端渲染节点时按类名查 nodeDefs.{类名}.display_name / inputs.{参数名}.name / outputs.{序号}.name，查不到就显示英文原文
插件不带 locales/zh/ 就是英文——这就是混杂的根源

3. nodeDefs.json 的格式（关键）

{
  "WanVideoModelLoader": {
    "display_name": "WanVideo 模型加载器",
    "inputs":  { "model": {"name": "模型"}, "seed": {"name": "随机种子"} },
    "outputs": { "0": {"name": "模型"}, "1": {"name": "优化器状态"} }
  }
}

顶层键是节点类名（object_info 里的 name，不是 display_name）
outputs 的键是输出序号字符串 "0"/"1"...，不是输出名
只写需要覆盖的键，缺的自动回落英文，不用全量翻译
参考：MiniMaxH3-TimelineDirector 自带的 locales/zh/nodeDefs.json 是现成范例

三、实施步骤（可复现）

第 1 步：枚举节点清单

从 /object_info 解析，用 python_module 字段区分核心与插件：

curl -s http://127.0.0.1:6006/object_info -o /tmp/oi.json
python - <<'EOF'
import json
d = json.load(open('/tmp/oi.json'))
for name, info in d.items():
    if info.get('python_module','').startswith('custom_nodes.'):
        print(info['python_module'], name, info.get('display_name'))
EOF

本次盘点结果：KJNodes 261、WanVideoWrapper 147、VHS 40、controlnet_aux 64、Frame-Interpolation 16、TimelineDirector 15、Spectrum 6、segment-anything-2 6、WanAnimatePreprocess 5、websocket_image_save 1。

第 2 步：借力 AIGODLIKE 社区翻译（覆盖 5 个包）

GitHub 访问不了就用 ghfast 镜像（AutoDL 也可 source /etc/network_turbo）：

cd /tmp
git clone --depth 1 https://ghfast.top/https://github.com/AIGODLIKE/AIGODLIKE-ComfyUI-Translation.git
# 有用文件：zh-CN/Nodes/<插件名>.json

AIGODLIKE 的格式是 {类名: {title, inputs:{原名:中文}, widgets:{...}, outputs:{原名:中文}}}，
转换思路：以 object_info 为骨架（谁有哪些输入、输出按什么顺序），把 AIGODLIKE 的 title/inputs/widgets/outputs 按 class_name + 原参数名对号入座，合成每个插件的 locales/zh/nodeDefs.json。outputs 的原名要对照 object_info 的 output_name 列表换算成序号键。

社区包实际命中率：controlnet_aux 63/64、segment-anything-2 6/6、VHS 36/40、Frame-Interpolation 14/16、KJNodes 仅 114/261（社区包滞后，新版节点没翻）。

第 3 步：手工补齐剩余标题（约 300 个）

KJNodes 社区没翻的 147 个 + VHS 4 个 + 插帧 2 个
WanVideoWrapper 全部 147 个（社区完全没有）
WanAnimatePreprocess 5 个、Spectrum 6 个、websocket_image_save 1 个
TimelineDirector 自带翻译漏掉的 6 个内部节点
纯英文专名加中文说明：RIFE VFI → RIFE 视频插帧、MagCache → MagCache 缓存加速

翻译原则：专有名词保留（WanVideo、VACE、LoRA、CLIP、T5、SageAttention…），动作/角色词翻译（Loader→加载器、Sampler→采样器、Embeds→嵌入、Block Swap→分块交换）。

第 4 步：固定界面语言

user/default/comfy.settings.json 加：

"Comfy.Locale": "zh"

第 5 步：重启验证

curl -s http://127.0.0.1:6006/i18n | python -m json.tool   # 确认 zh.nodeDefs 已合并

统计覆盖率：对照 object_info 与 /i18n，凡 display_name 翻译存在且与原文不同即计为已翻译 → 最终 561/561。

浏览器 Ctrl+F5 强刷一次（前端缓存），即可看到全中文。

四、踩坑记录（重要）

坑	现象	解法
`pkill -f` 自匹配	paramiko `exec_command` 里执行 `pkill -9 -f 'main.py --listen'`，当前 bash 的命令行本身就含该字符串，把自己 SIGKILL，退出码 127，后续命令全部没执行	模式写成 `'[m]ain.py --listen'`（正则技巧避免匹配字面自身）
ssh 会话退出杀后台进程	`nohup python main.py ... &` 后断开连接，进程没活下来（容器 sshd 清理会话进程组）	服务器上放启动脚本，用 `setsid nohup ... < /dev/null &` 完全脱离会话进程组
heredoc 嵌套转义	外层双引号包 heredoc 再含 JSON 中文引号，bash 报 `unexpected EOF while looking for matching '"'`	别硬写 heredoc——本地写好文件用 SFTP put 上传，再远程执行合并脚本
`/i18n` 有 `lru_cache`	改了 locales 文件不生效	必须重启 ComfyUI
社区翻译包滞后	AIGODLIKE 的 KJNodes 只覆盖 114/261	社区包打底 + 手工覆盖字典补齐，两者按类名合并，后者优先
工作流残留英文	个别节点仍显示英文	那是节点手动设过 title，title 优先于翻译；右键清除标题即可

五、后续维护

插件更新后新增节点会回落英文：往对应 custom_nodes/<包>/locales/zh/nodeDefs.json 补条目，重启即可
想翻 tooltip 长描述：同文件节点条目里加 "description": "..."，输入/输出加 "tooltip"
想翻菜单/命令/设置项：同目录 main.json / commands.json / settings.json
检查某节点为什么没翻：先 curl /object_info/{类名} 确认类名，再对照 nodeDefs.json 键名（键是类名不是显示名）

六、本地辅助脚本（同目录，可复用）

文件	用途
`ssh_run.py`	paramiko 执行远程命令（密码登录，无交互）
`zh_overrides.json`	手工翻译覆盖字典（按 `插件包 → {类名: 中文标题}` 组织）
`zh_step2.py`	SFTP 上传覆盖字典 + 远程合并进各包 nodeDefs.json
`zh_step3.py`	上传并执行 `setsid` 重启脚本（解决后台进程存活）
`comfyui_全中文汉化经验.md`	本文档

七、远程改动清单（服务器上留了什么）

/root/autodl-tmp/ComfyUI/user/default/comfy.settings.json → 加了 "Comfy.Locale": "zh"
各插件包内新增 locales/zh/nodeDefs.json（10 个包；TimelineDirector 的是原带文件补了 6 条）
/root/restart_comfy_zh.sh → setsid 安全重启脚本
/tmp/oi.json、/tmp/zh_overrides.json、/tmp/gen_zh_nodefs.py、/tmp/AIGODLIKE-ComfyUI-Translation/ → 中间产物，可删