Co-op Translator 是一款开源的文档自动翻译工具，将它接入 GitHub Actions 后，仓库中的 Markdown、Jupyter notebook 和图片文本一旦变更，CI 就会自动重新翻译并直接创建一个翻译 PR（Pull Request），无需任何人工操作。本文将带你用最简单的方式完成这套 CI 集成的完整配置，新手照着做 10 分钟即可跑通。🚀

先看懂原理：一张图理解文档自动翻译流程

Co-op Translator 的翻译流程分为四步：扫描变更 → 调用模型翻译 → 保护结构并改写链接 → 生成元数据并审查。源码哈希和语言级元数据能识别哪些文件已过期，未变化的文件会被直接跳过，避免重复消耗 Token。

接入 GitHub Actions 后，这个流程会完整地跑在 CI 里：

最终，你的 README 会像下面这样在仓库中维护一张多语言表格，每行都是 CI 自动更新的：

准备工作：先配好 2 项前置条件

第 1 步：为仓库添加翻译服务商 Secrets

在目标仓库中打开Settings > Secrets and variables > Actions，点击New repository secret添加你选用的模型服务商密钥：

文本翻译三选一即可，按需添加：

如果还要翻译图片里的文字，额外需要 Azure AI Vision 的AZURE_AI_SERVICE_API_KEY和AZURE_AI_SERVICE_ENDPOINT。纯 Markdown 翻译则完全不需要 Vision 服务。详细配置说明见 docs/configuration.md 和 docs/azure-ai-setup.md。

第 2 步：开启工作流创建 PR 的权限

打开Settings > Actions > General，在 Workflow permissions 区域勾选Allow GitHub Actions to create and approve pull requests并保存：

最快上手：5 步拿到你的第一个 README 翻译 PR

官方提供了一份现成的工作流模板，从根目录的README.md和单一目标语言开始，最适合第一次尝试：

1. 复制模板：把 translate-readme.yml 复制到你仓库的.github/workflows/目录下并提交。模板通过根 action.yml 调用 Co-op Translator，建议固定到一个已审查的 commit 以保证可复现。
2. 先预览：进入Actions > Translate README > Run workflow，选择语言（如ko、ja、es），保持勾选Preview only运行。预览不调用模型、不写文件、不建 PR，只显示 Token 估算。
3. 补齐权限：确认上一步的两个 Secrets 已添加、PR 创建权限已开启。
4. 正式运行：取消勾选Preview only再运行。流程会依次执行：预览 → 翻译 →co-op-review --readme-only审查 → 全部成功后创建或更新翻译 PR，运行摘要里会直接附上 PR 链接。
5. 审查合并：检查 PR 中的措辞和文件改动，没问题再合并。PR 只包含translations/<语言>/README.md及其元数据文件，源 README 保持不变。

💡 组织策略如果限制了上述权限，可以请管理员评估使用 GitHub App 方案，详见官方文档 docs/github-actions.md 的 GitHub App Setup 章节。

进阶配置：让整仓 Markdown 自动翻译并开 PR

README 跑通之后，推荐切换为push 触发的标准工作流.github/workflows/co-op-translator.yml，核心逻辑如下：

name: Co-op Translator on: push: branches: [main] jobs: co-op-translator: runs-on: ubuntu-latest env: TARGET_LANGUAGES: "es fr de" permissions: contents: write pull-requests: write steps: - uses: actions/checkout@v4 with: { fetch-depth: 0 } - uses: actions/setup-python@v7 with: { python-version: "3.11" } - name: Install Co-op Translator run: | python -m pip install --upgrade pip pip install co-op-translator - name: Run Co-op Translator env: AZURE_OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }} # ……其余密钥按所用服务商配置 run: translate -l "$TARGET_LANGUAGES" -md -y - name: Create Pull Request with translations uses: peter-evans/create-pull-request@v5 with: token: ${{ secrets.GITHUB_TOKEN }} branch: update-translations base: main add-paths: | translations/

几个关键设计点：

• paths:过滤：大仓库建议在on.push下加paths:过滤器，只在文档变更时触发，节省 CI 分钟数
• 失败即停：翻译或审查任一步失败，作业会在开 PR 之前中止，不会产生"半成品" PR
• 笔记本与图片：给翻译命令加-nb（notebook）或-img（图片文字，需 Azure AI Vision），并相应调整审查与add-paths参数
• CLI 参数：-l指定语言、-md仅 Markdown、--readme-only只译 README，完整参数见 docs/cli.md

配置完成后，每次 main 分支有文档变更，Actions 都会跑完翻译与审查，然后自动生成一个结构清晰的翻译 PR：

看看效果：翻译结果长什么样

下面是一个真实案例：同一个 README 段落，英文版与 Co-op Translator 自动生成的韩文版对照。链接、代码和 Markdown 结构都被完整保留：

翻译后的文档会原样保存在仓库的translations/<语言>/目录中，可以像普通代码一样被审查、版本管理和持续更新：

实战避坑：4 个让 CI 更稳的建议

1. 📌 控制单次翻译量：GitHub 托管 Runner 有作业时长上限，语言太多或仓库太大时，可减少单次语言数、用-md/-nb/-img限定内容类型，或换用 self-hosted runner。
2. 📌 审查措辞再合并：工作流会整体重译变更过的源文件，人工改过的译文可能被覆盖。合并前务必审查 diff；如需在 Markdown 块级别保留人工编辑，可使用 Python API 的 translation state provider（见 docs/api.md）。
3. 📌 把co-op-review用于 PR 校验：它是确定性的审查命令，不写文件、不调用模型，适合在 PR 上验证生成结果：

   - name: Review translated outputs run: co-op-review --changed-from "origin/${{ github.base_ref }}" --format github

4. 📌 组织级场景用 GitHub App：如果组织要求 App 身份、或需要生成的 PR 自动触发下游 CI，可按官方文档配置 GitHub App，用 App Token 替代GITHUB_TOKEN创建 PR。

更多排障思路（如"没有生成 PR"、"Token 估算异常"）可参考 docs/troubleshooting.md。

常见问题 FAQ

Q1：为什么运行了却没有新 PR？翻译或审查任一步失败时不会创建 PR；源文件没有实际变化时同样不会开新 PR。查看 Workflow Summary 和失败步骤的日志即可定位。

Q2：PR 会自动合并吗？不会。无论哪种工作流，合并都由人来执行，确保机翻措辞经过人工把关。

Q3：第一次运行一定要配置 Azure 吗？不一定。Azure OpenAI、OpenAI、Anthropic 三选一即可翻译文本；只有翻译图片里的文字才需要 Azure AI Vision。

Q4：除了 GitHub Actions 还有哪些用法？Co-op Translator 提供 CLI、Python API、MCP Server、容器等多种接入方式，选择建议见 docs/workflows.md，容器快速运行方式见 Dockerfile。

小结与延伸资源

到这里，你的仓库已经具备了"文档变更 → 自动翻译 → 自动审查 → 自动开 PR"的完整闭环。核心要点回顾：

• 前置只需 2 项：模型服务商 Secrets + 允许 Actions 创建 PR 的权限
• 先跑 README 模板，再升级到整仓 push 工作流
• 失败即停、永不自动合并，安全性由工作流本身保证

把多语言文档交给 CI，把审查留给团队——这就是 Co-op Translator 的协作翻译之道。✨