企业官网建设流程全解析

Easydict Issue 翻译工作流固定版本升级实录：issues-translate-action v2.8.3 的 Markdown URL 误判修复

【免费下载链接】Easydict一个简洁优雅的词典翻译 macOS App。开箱即用，支持离线 OCR 识别，支持有道词典，🍎 苹果系统词典，🍎 苹果系统翻译，OpenAI，Gemini，DeepL，Google，Bing，腾讯，百度，阿里，小牛，彩云和火山翻译。A concise and elegant Dictionary and Translator macOS App for looking up words and translating text.项目地址: https://gitcode.com/gh_mirrors/ea/Easydict

导读

Easydict 仓库通过 GitHub Actions 中的issues-translate-action自动将中文 Issue、评论与 PR review comment 翻译为英文，同时将英文内容回译为简体中文。本文以 2026-09-04-issue-translator-v2.8.3.md 这份升级记录为骨架，完整还原 v2.8.3 的升级动机（语言识别阶段忽略 Markdown 图片/链接中的 HTTP(S) URL，避免中文正文被误判为英文而跳过翻译）、固定 tag 的依赖治理策略，以及 YAML 解析、diff 检查、引用范围审计的完整验证流程。读完本文，你将掌握 Easydict 的 Issue 翻译自动化现状、其"只固定引用已发布 patch tag、不依赖分支"的依赖升级规范，以及一套可复制的 GitHub Actions 依赖升级核验方法。

背景：Easydict 的 Issue 翻译自动化

Easydict 是一个开源的多语种词典与翻译 macOS App，仓库中通过 GitHub Actions 维护了多条自动化流水线。其中与社区协作最相关的是 Issue 翻译流水线，配置文件位于 .github/workflows/issue-translator.yml。该工作流调用上游第三方 Actiontisfeng/issues-translate-action，实现了 Issue 讨论区的自动双语化。

当前仓库中该工作流的实际内容如下（注意当前已演进至 v2.9.2，但整体骨架与 v2.8.3 时代一致）：

name: issue-translator on: issue_comment: types: [ created ] issues: types: [ opened ] pull_request_review_comment: types: [ created ] jobs: translate: runs-on: ubuntu-latest steps: - uses: tisfeng/issues-translate-action@v2.9.2 with: IS_MODIFY_TITLE: false PRIMARY_LANGUAGE: zh-CN SECONDARY_LANGUAGE: en CUSTOM_BOT_NOTE: Bot automatically translated this content.

触发事件与翻译范围

工作流通过三个事件触发，覆盖了社区讨论的全部入口：

从 2026-09-17-issue-translator-v2.9.2.md 与 2026-09-04-issue-translator-v2.8.2.md 等历史记录可以确认：Easydict 在历次升级中始终坚持"只更新uses:引用的 Action 版本号，不改动事件、表达式、权限与with输入配置"的约束，确保翻译行为语义稳定。

四个关键输入项

工作流中配置了四个 Action 输入，含义如下：

• IS_MODIFY_TITLE: false：不直接改写 Issue 标题原文。按 2026-09-05-issue-translator-v2.9.0.md 的记录，标题与正文会分别选择目标语言，原始标题不会被直接修改，翻译以评论形式呈现。
• PRIMARY_LANGUAGE: zh-CN：非首选语言内容的目标语言。即日文、韩文及无法识别的文本一律翻译为简体中文。
• SECONDARY_LANGUAGE: en：首选语言内容的目标语言。即中文内容翻译为英文。
• CUSTOM_BOT_NOTE：翻译评论中附加的 Bot 提示文案，使用与任意翻译方向一致的中性表述。

v2.8.3 核心变更：语言识别前的 Markdown URL 过滤

本次升级（关联文档）是一次纯版本钉扎（version pinning）更新：将.github/workflows/issue-translator.yml中固定的 Action 引用从v2.8.2更新为v2.8.3，事件、inputs 与node24运行时保持不变。

修复的问题场景

v2.8.3 的核心修复点在语言识别（language detection）环节。在升级前，Action 对评论内容执行语言识别时会把 Markdown 图片与链接中的 HTTP(S) URL 一并纳入判断。这带来一个典型的误判场景：

一条中文正文的评论中如果夹带了英文/URL 形式的 Markdown 链接（例如[查看截图](https://example.com/xxx.png)或直接粘贴的图片地址），URL 中大量的 ASCII 字符会显著拉高"英文"特征的权重，导致整条评论被误判为英文内容，从而被跳过翻译——但该评论的实际正文是中文，本应被翻译为英文。

修复策略：识别与翻译分离

v2.8.3 的处理方式体现了"识别用轻量文本、翻译用完整原文"的分离原则：

• 语言识别前：忽略（strip）Markdown 图片与链接中的 HTTP(S) URL，仅基于剩余正文做语言判断，从而让中文评论稳定地落入"需要翻译"的分支；
• 实际翻译时：仍使用完整原文（含 Markdown 标记），保证翻译结果保留原有链接与排版结构，不因识别阶段的过滤而丢失内容。

这意味着该修复对用户侧是透明的：评论中的链接与图片依然原样出现在翻译结果里，变化的只是"这条评论要不要翻译"的判定结果。

设计意图：固定 patch tag，拒绝分支依赖

Easydict 对第三方 Action 的依赖治理策略十分明确，从本记录的设计意图一节可以提炼出三条原则：

1. 只固定引用已验证的 Action tag。上游每次发布后，先在本地核验 tag 指向的提交与 Release 状态，确认无误后才更新引用；绝不直接依赖main等可变分支。
2. 明确 patch tag 为不可变部署边界。如 2026-09-04-issue-translator-v2.8.2.md 中所记："tag 是工作流依赖的不可变部署边界，必须先确认 tag 已推送才更新 Easydict 引用"。
3. 小步升级、一次一个 patch 版本。从 v2.8.1 → v2.8.2 → v2.8.3 → v2.9.0 → v2.9.1 → v2.9.2，每次只前进一个已发布版本，避免跨版本跳升引入不可控的破坏性变更。

这套策略的收益是：任何时刻仓库中运行的工作流行为都是可审计、可回溯的，出现问题时可以精确地定位到某个 tag 对应的行为变化，而非受上游分支漂移影响。

升级操作与验证流程（可复制的清单）

v2.8.3 升级记录中给出了完整的验证步骤，这套流程在后续 v2.9.0、v2.9.1、v2.9.2 的升级中被反复复用，可提炼为通用清单：

第 1 步：核验上游 tag 指向

在更新引用之前，先确认上游v2.8.3tag 已推送且指向预期提交。本次记录中，更新前v2.8.3^{}（peeled tag，即解引用后的最终提交）解析到fc86486959aad3c51b4903044534e6cdc09468a3。后续 v2.9.2 升级还进一步要求 Release 为非 draft、非 prerelease 状态，防止引用到未正式发布的版本。

第 2 步：核对运行时契约兼容性

确认上游action.yml的以下内容与当前引用版本兼容：

• inputs定义：IS_MODIFY_TITLE、PRIMARY_LANGUAGE、SECONDARY_LANGUAGE、CUSTOM_BOT_NOTE等参数名与默认值没有变更；
• runs.using: node24：运行时版本未变化；
• dist/index.js入口：打包产物结构与入口一致。

v2.8.3 记录明确"上游action.yml的 inputs、runs.using: node24与dist/index.js入口均与v2.8.2兼容"，这是决定能否只改一行引用的关键前提。

第 3 步：执行本地静态验证

升级记录中使用的本地验证手段包括：

• YAML 解析：对.github/workflows/issue-translator.yml执行 YAML 语法解析（如 RubyYAML.safe_load），确保修改后的工作流文件语法合法；
• git diff --check：检查 diff 中是否存在空白字符错误（trailing whitespace 等）；
• 引用范围审计：确认运行时 workflow 中的 Action 引用唯一且恰好为v2.8.3，不存在其他残留版本引用。

注意：v2.9.0 的验证记录中特别说明未运行actionlint（本机未安装该工具），原因是本次仅变更 Action 引用与with输入，未改事件、表达式或权限。可见验证工具的选用与变更范围相匹配。

第 4 步：控制变更范围

允许修改的路径被严格限定在工作流文件与文档记录：

• .github/workflows/issue-translator.yml
• docs/exec-plans/下的计划归档
• docs/histories/2026-09/下的 history 记录

禁止改动其他工作流、产品代码、Xcode 工程或用户内容，也禁止在升级过程中触发真实 workflow 运行。

第 5 步：记录并等待真实环境验证

升级完成后不执行推送或仅按约定推送，翻译行为的最终验证交给"下一次自然发生的中文 Issue、评论或 PR review comment"——由 GitHub 托管的 Runner 在真实网络环境中验证。这是因为本地验证无法替代 GitHub Runner 的真实网络连通性与运行环境（这一点在 v2.8.2 记录中针对 Google 网页翻译 batch RPC 的连通性亦有说明）。

升级脉络回顾：从 v2.8.2 到 v2.9.2

将本记录放入 Easydict 的升级时间线中可以更清楚地看到它的位置：

可以看出，Easydict 对 Issue 翻译工作流的维护遵循"小步、固定、可审计"的长期节奏：上游每个 patch 版本发布后，都经过 tag 核验、契约比对、静态检查三道关卡，再以一行引用的最小 diff 落入仓库，并留下对应的计划与 history 记录（计划归档见 docs/exec-plans/completed/2026-09/ 目录）。

边界与注意事项

• 适用前提：上述升级流程适用于"上游 Action 版本向后兼容"的场景（inputs 与运行时契约不变）。若上游发生破坏性变更（如输入项改名、Node 运行时升级、翻译后端更换），则需要在第 2 步的契约核对中识别出来，并同步调整with配置。
• 本地验证的局限：YAML 解析与 diff 检查只能保证配置静态正确，无法验证真实翻译行为；v2.8.2 记录明确指出"本地网络无法代替 GitHub 托管 Runner 的真实 Google 连通性验证"。因此真实环境验证依赖下一次自然触发的工作流运行。
• 配置的当前形态：截至本仓库当前状态，工作流已演进至v2.9.2，IS_MODIFY_TITLE: false、PRIMARY_LANGUAGE: zh-CN、SECONDARY_LANGUAGE: en、CUSTOM_BOT_NOTE的配置形态保持不变，v2.8.3 修复的语言识别逻辑随后续版本继续生效。

结语

Easydict 的 Issue 翻译流水线是一个"小依赖、大治理"的典型样本：一个看似只有一行的uses:引用，背后是 tag 核验、契约比对、静态检查、范围审计与文档归档的完整闭环。v2.8.3 的升级更是演示了一个值得借鉴的工程细节——语言识别阶段应使用剥离 URL 等噪声后的轻量文本，而翻译阶段应保留完整原文，这一"识别与翻译分离"的思路对任何基于文本分类的自动化管线都有普遍参考价值。若你在自己的仓库中维护第三方 GitHub Actions，本文的固定 tag 策略与验证清单可以直接复用。

【免费下载链接】Easydict一个简洁优雅的词典翻译 macOS App。开箱即用，支持离线 OCR 识别，支持有道词典，🍎 苹果系统词典，🍎 苹果系统翻译，OpenAI，Gemini，DeepL，Google，Bing，腾讯，百度，阿里，小牛，彩云和火山翻译。A concise and elegant Dictionary and Translator macOS App for looking up words and translating text.项目地址: https://gitcode.com/gh_mirrors/ea/Easydict