Lingo.dev GitHub 集成

Lingo.dev GitHub Action 是一个安全的开源 CI/CD 集成工具，可自动本地化新内容，并防止未完成的翻译进入生产环境。根据团队的工作流需求，它可以创建拉取请求或直接提交到您的分支。

它还实现了自动冲突解决功能，使您的翻译与代码保持同步，无需手动干预。

该操作支持多种工作流场景：

1. 当内容更改被合并时，直接提交到主分支；
2. 当拉取请求被打开或更新时，直接提交到拉取请求分支；
3. 针对主分支的翻译更新创建拉取请求；
4. 针对现有拉取请求分支的翻译更新创建拉取请求。

完成本指南后，您将能够：

1. 设置由代码推送触发的自动本地化；
2. 使用存储库密钥配置安全认证；
3. 在直接提交和拉取请求工作流之间进行选择；
4. 了解持续本地化如何融入您的现有流程。

让我们开始吧！

前置条件

存储库设置

您的存储库必须配置 Lingo.dev CLI 并包含有效的 i18n.json 文件。如果尚未完成此设置，请先完成 CLI 快速入门。

第 1 步：认证设置

Lingo.dev GitHub Actions 需要访问您的翻译引擎和存储库。认证通过存储库密钥进行，以确保您的凭据安全。

添加您的 API 密钥

进入您的存储库设置 → 密钥和变量 → Actions，然后添加您的翻译引擎凭据：

对于原始 LLM API 用户：

• 密钥名称：OPENAI_API_KEY 或 ANTHROPIC_API_KEY
• 密钥值：来自相应提供商的 API 密钥

对于 Lingo.dev 引擎用户：

• 密钥名称：LINGODOTDEV_API_KEY
• 密钥值：您的项目 API 密钥，获取自 lingo.dev/app

第 2 步：创建工作流

在您的代码库中创建 .github/workflows/i18n.yml 文件，并使用以下基本配置：

name: Lingo.dev i18n

on:
  workflow_dispatch:
  push:
    branches:
      - main
      - feat/*

permissions:
  contents: write
  pull-requests: write

jobs:
  i18n:
    name: Run i18n
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

或者，您可以将 Lingo.dev GitHub Action 添加为现有工作流中的一个步骤：

- name: Lingo.dev
  uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

所需权限

您的工作流需要特定权限才能正常运行。GitHub Actions 要求在工作流文件中显式声明权限：

permissions:
  contents: write # 必需：创建包含翻译更新的提交
  pull-requests: write # 可选：仅在使用拉取请求模式时需要

contents: write 权限允许操作：

• 创建包含翻译更新的提交
• 将更改直接推送到您的代码库
• 访问并修改代码库中的文件

这些权限授予工作流的临时 GitHub 令牌 (${{ github.token }})，该令牌由 GitHub 为每次工作流运行自动创建，并具有您在工作流文件中指定的确切权限。

此配置：

• 在推送到主分支和功能分支时触发
• 授予提交和拉取请求所需的权限
• 使用最新的操作版本 以实现自动更新
• 通过代码库密钥安全访问您的 API 密钥

附加：

• 在 Lingo.dev，我们喜欢为每个工作流添加一个 workflow_dispatch 触发器，这样我们可以从 GitHub Actions 界面手动（重新）运行它。这完全是可选的，但我们发现它非常有用。

第 3 步：选择您的工作流模式

Lingo.dev GitHub Actions 根据您的团队代码审查需求支持两种操作模式。

直接提交模式（默认）

此操作会将翻译直接提交到您的分支：

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

此模式最适合：

• 独立开发者或小型团队
• 在合并前会进行审查的功能分支
• 不需要单独审查翻译更新的项目

拉取请求模式

此操作会为翻译更新创建拉取请求：

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true
    pull-request-title: "feat: update translations"

拉取请求模式的必要权限

拉取请求模式需要额外的权限和仓库设置：

permissions:
  contents: write # 必需：访问仓库内容并创建提交
  pull-requests: write # 必需：创建和更新拉取请求

GitHub Token 设置： GH_TOKEN 环境变量必须设置为 ${{ github.token }}，这是 GitHub 为每次工作流运行自动生成的临时令牌。此令牌具有您工作流文件 permissions 部分中指定的权限。

仓库设置： 您必须在仓库设置中启用 GitHub Actions 创建拉取请求的权限：

1. 转到 Settings → Actions → General
2. 滚动到页面底部
3. 在“Workflow permissions”下，确保启用了 “Allow GitHub Actions to create and approve pull requests”

如果在仓库设置中未看到此选项，请检查您的组织设置：

1. 转到您的组织的 Settings → Actions → General
2. 查找相同的“Allow GitHub Actions to create and approve pull requests”设置

此模式最适合：

• 具有严格代码审查要求的团队
• 需要单独批准翻译更改的项目
• 需要对所有更改进行明确审查的工作流

第 4 步：工作流场景

Lingo.dev GitHub Action 会自动适应不同的开发工作流。了解这些场景有助于您为团队选择合适的配置。

场景 1：主分支更新（直接提交）

触发条件： 推送到主分支（例如，合并拉取请求时） 操作： 将翻译更新直接提交到主分支

on:
  push:
    branches: [main]

# 操作直接提交到主分支

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

流程： 内容更改推送到 main → 操作将翻译提交到 main

此场景确保主分支在内容更改合并后始终拥有最新的翻译。

提示：这是我们推荐您采用的模式。它需要一个配置良好的 AI 本地化引擎以确保完美的本地化。优点是实现了零人工干预，因为在每次生产部署之前会自动检查并填充缺失的翻译。

场景 2：拉取请求更新（直接提交）

触发条件： 打开或更新包含内容更改的拉取请求 操作： 将翻译更新直接提交到拉取请求分支

on:
  pull_request:
    types: [opened, synchronize]

# 操作直接提交到拉取请求分支

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

流程： 拉取请求分支中的内容更改 → 操作将翻译提交到相同的拉取请求分支

这会将翻译更新保留在功能分支中，确保翻译与原始更改一起进行审查。

场景 3：主分支的拉取请求（拉取请求模式）

触发条件： 推送到主分支（例如，合并拉取请求时） 操作： 创建一个包含翻译更新的拉取请求

on:
  push:
    branches: [main]

# 操作创建 PR：main/lingo.dev → main

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true

流程： 内容更改推送到 main → 操作创建 main/lingo.dev 分支 → 从 main/lingo.dev 打开 PR → main

场景 4：拉取请求到功能分支（拉取请求模式）

触发条件： 打开或更新带有内容更改的拉取请求 操作： 创建一个包含翻译更新的拉取请求，目标为功能分支

on:
  pull_request:
    types: [opened, synchronize]

# 操作创建 PR：feat/new-feature/lingo.dev → feat/new-feature

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true

流程： feat/new-feature 中的内容更改 → 操作创建 feat/new-feature/lingo.dev 分支 → 从 feat/new-feature/lingo.dev 打开 PR → feat/new-feature

这为每个功能分支维护了单独的翻译审查。

分支命名约定

在使用拉取请求模式时，Lingo.dev GitHub Action 遵循一致的命名模式：

格式： <base-branch>/lingo.dev

示例：

• 主分支更新：main/lingo.dev → main
• 功能分支更新：feat/user-auth/lingo.dev → feat/user-auth
• 发布分支更新：release/v2.0/lingo.dev → release/v2.0

这种命名约定确保翻译分支清晰可辨，并自动链接到其源分支。

处理外部贡献

在处理外部分叉时，实施选择性检出以维护存储库安全性：

jobs:
  i18n:
    name: Run i18n
    runs-on: ubuntu-latest
    permissions:
      actions: write
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - run: find locales/** -name "*.json" | xargs git checkout ${{ github.event.pull_request.head.sha }} --
        shell: bash
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

外部贡献所需权限

处理外部分支需要提升权限以安全地处理贡献：

permissions:
  actions: write # 必需：访问工作流信息和工件
  contents: write # 必需：创建提交并访问存储库内容
  pull-requests: write # 必需：更新来自外部分支的拉取请求

actions: write 权限特别需要用于：

• 访问来自外部分支的拉取请求元数据
• 读取工作流上下文以进行安全验证
• 安全地处理工件和工作流状态

这些提升的权限确保操作可以安全地处理来自外部贡献者的翻译，同时通过选择性文件检出维护存储库的安全性。

此方法：

• 仅检出来自分支的翻译文件
• 防止敏感存储库代码的暴露
• 保持操作所需的写权限

高级配置

使用附加参数自定义操作行为：

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true
    commit-message: "feat: update translations via lingo.dev"
    working-directory: "apps/web"
    version: "latest"
    process-own-commits: false
    parallel: true

配置选项：

• commit-message — 翻译提交的自定义消息
• working-directory — 在子目录中运行操作
• version — 固定到特定的 CLI 版本（不推荐）
• process-own-commits — 处理此操作生成的提交
• parallel — 启用本地化任务的并行处理（默认值：false）

并行处理

GitHub Action 支持本地化任务的并行处理，可以显著加速大型项目的翻译工作流。通过设置 parallel: true 启用此功能：

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    parallel: true

启用后，操作将：

• 将本地化任务分配给多个并发工作者
• 使用智能任务分配算法最大化吞吐量
• 通过精心的并发管理防止文件损坏和竞争条件
• 显著减少包含大量翻译文件的项目的处理时间

此功能特别适用于：

• 翻译需求广泛的大型项目
• 同时处理多个语言环境的工作流
• 需要更快 CI/CD 管道执行的团队

注意：并行处理可能会增加 API 使用量。如果您有严格的速率限制，请监控您的使用情况。

验证模式

使用 --frozen 标志，您可以在每次生产部署之前验证所有翻译是否是最新的。

以下是如何在部署管道中使用 --frozen 标志的示例：

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx lingo.dev@latest i18n --frozen
      - run: npm run build
      - run: npm run deploy

--frozen 标志的作用：

• 验证所有翻译是否是最新的
• 不对文件进行任何更改
• 如果翻译缺失或过时，则构建失败