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]

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