TranslatePress 编辑器翻译

用途

通过浏览器自动化操作 TranslatePress 的翻译编辑器，把 WordPress 站点的英文内容逐条译成中文。适用于以下场景：

• 用户要求「翻译这个站的中文版」「把 /zh/ 下没译的页面补齐」
• 用户要求检查某页面还有哪些英文没翻译
• 已有译文需要按新术语批量纠正

前置条件

1. 用户已在浏览器中登录目标站点的 WordPress 后台（编辑器依赖登录态）。
2. bsk CLI 可用，且浏览器扩展已连接。
3. 站点已启用 TranslatePress，且目标语言已添加（通常是 zh_CN）。
4. 先读 references/chinese-tech-glossary.md 确定术语口径；用户若指定过术语，以用户的为准。

工作流程

1. 建立会话并定位页面

export MSYS_NO_PATHCONV=1
S=$(BSK_AUTO_START=0 bsk session start --json | grep -oE '"session_id": "[a-z0-9]+"' | cut -d'"' -f4)
echo "$S" > /tmp/tp_sid
TAB=$(BSK_AUTO_START=0 bsk tab create --url "https://站点/zh/目标页/" --session $S | grep -oE "tab_id=[0-9]+" | cut -d= -f2)
echo "$TAB" > /tmp/tp_tab

若守护进程未启动，先以 run_in_background 方式执行 BSK_AUTO_START=0 bsk daemon start --foreground，再执行 bsk status --json 确认就绪。

2. 打开翻译编辑器

R=$(BSK_AUTO_START=0 bsk observe --session $S --tab-id $TAB | grep -oE '@e[0-9]+ menuitem "翻译页面"' | head -1 | cut -d' ' -f1)
BSK_AUTO_START=0 bsk click "$R" --session $S --tab-id $TAB
sleep 14

等待时间不可省。编辑器要扫描页面字符串，过早操作会拿到空列表。

菜单项找不到时：页面可能未加载完或登录态失效。执行 bsk reload 后重试，最多 6 次。

3. 确认编辑器就绪

BSK_AUTO_START=0 bsk evaluate --session $S --tab-id $TAB \
  '(() => { const s=document.getElementById("trp-string-categories"); return "opts="+(s?s.options.length:"-"); })()'

opts 应大于 0（通常 70~200）。为 0 说明字符串尚未扫描完，再等几秒。

4. 扫描待译内容

先读预览 iframe 里的英文，确认要译哪些。把 scripts/scan_remaining.js 内容作为 evaluate 参数执行（__TP_SCOPE__ 设为 "iframe"）。输出格式为 REMAIN=n 加若干 --- 分隔的段落。

据此准备译文对照数组 [[英文原文, 中文译文], ...]。

5. 逐条填写译文

把 scripts/fill_pairs.js 的内容作为 evaluate 参数执行。执行前设置全局变量：

window.__TP_PAIRS__ = JSON.stringify([[ "原文1", "译文1" ], [ "原文2", "译文2" ]]);
window.__TP_FROM__  = 0;    // 起始索引
window.__TP_TAKE__  = 2;    // 每批条数，务必 ≤3
window.__TP_FORCE__ = 0;    // 1 = 覆盖已有中文

每批只处理 2~3 条，避免单次 evaluate 超过 30 秒 RPC 上限，也降低下拉卡死概率。

节奏要求：脚本已内置「填入 → 等 1 秒 → 保存 → 等 1 秒」，与人工操作一致，不要为了提速删掉等待。用户明确不要批量导入时，全程只用这个脚本，不要改用接口批量写。

6. 处理脚本返回的状态

7. 处理特殊字符串

遇到 NO / MISMATCH 且重试无效时，改用按 ID 精确写入：

1. 在预览 iframe 里定位该文本，读取其 data-trp-translate-id：

const d = document.querySelector("iframe").contentDocument;
const els = [...d.querySelectorAll("[data-trp-translate-id]")]
  .filter(e => e.textContent.indexOf("目标片段") >= 0);
return [...new Set(els.map(e => e.getAttribute("data-trp-translate-id")))].join(",");

2. 若一句话被拆成多段（常见于含加粗、链接的句子），逐段列出：

const p = [...d.querySelectorAll("p")].find(e => e.textContent.indexOf("Welcome to") >= 0);
return [...p.querySelectorAll("translate-press")]
  .map(x => x.getAttribute("data-trp-translate-id") + " ::: " + JSON.stringify(x.textContent)).join("\n");

3. 用 scripts/save_by_id.js 分别写入各片段：

window.__TP_ID_PAIRS__ = JSON.stringify([["3337", "欢迎访问 "], ["10212", "东营柏创管道科技有限公司"], ["3338", "。我们致力于保护您的隐私……"]]);

注意：该接口只能更新已有记录，不能创建新记录。若读接口返回 NO_ROW，说明字符串未入库，见「无法处理的情况」。

8. 验证结果

重新 navigate 到页面（不要带 trp-edit-translation 参数），再执行扫描脚本确认 REMAIN=0。

必要时用 ?v=时间戳 绕过缓存。

9. 结束会话

BSK_AUTO_START=0 bsk tab close $TAB --session $S
BSK_AUTO_START=0 bsk session stop $S

常见故障

Select2 下拉卡死

症状：点击箭头后选项数恒为 0，.select2-container--open 不出现，但底层 select 的 options.length 正常。

处理：重新 navigate 页面 → 重新点「翻译页面」→ 等 14 秒。这是唯一解法，脚本层面所有 retry 都无效。

预防：每批 2~3 条；不要在一次 evaluate 里连续处理多条。

写入后不生效

依次排查：

1. 是否用了 execCommand('insertText')？直接赋值和派发 input 事件都不会触发 Vue 3 的 v-model。
2. 保存按钮是否真的被点到？用 bsk observe 确认按钮的可见文字（界面语言可能是英文的 Save）。
3. 字符串是否在数据库中有记录？用接口读一次，返回空数组即为未入库。
4. 缓存是否生效？换 ?v=时间戳 再试。

字符串永远存不进去

若某页大量字符串都呈现「能选中、能填、但保存无效」，说明该页在 TranslatePress 中缺少字符串记录。此时应建议用户先在后台跑一次自动翻译生成记录行，再回来逐条改准。人工在界面上操作同样存不进去，不是操作方式的问题。

无法处理的情况

参考文档

• references/editor-dom-and-api.md — 编辑器 DOM 结构、Select2 操作、TranslatePress 读写接口、接口限制
• references/chinese-tech-glossary.md — 工业管件类术语表、保留原文规则、中文技术写作规范

脚本

• scripts/fill_pairs.js — 按「选中 → 填入 → 等 1 秒 → 保存 → 等 1 秒」处理一批译文
• scripts/save_by_id.js — 按字符串 ID 精确写入（应对拆分段、同名多条、匹配失败）
• scripts/scan_remaining.js — 扫描页面剩余英文，用于翻译前后核对