CI/CD 本地化工作流

Lingo.dev 可在 CI/CD 中自动处理本地化。主要有两种方式：使用 GitHub App，在服务端响应你的 push 和 pull request；或者在你自己的流水线中运行 CLI。两种方式都会在每次变更时保持翻译同步，而且只处理真正发生变化的字符串——因此即使项目不断扩展，本地化依然快速且具成本效益。

方案 1：GitHub App（推荐）#

GitHub App 是实现持续本地化最简单的方式。它会监控你的仓库并在服务端完成翻译，因此无需在流水线中安装任何东西，也不用把 API 密钥存成 CI secret。

设置只需一次：

1. 在你的仓库中安装 Lingo.dev GitHub App。
2. 提交一个 .lingo/config.json，其中包含你的 orgId、engineId、源语言区域设置、目标语言区域设置，以及要翻译的文件。先在本地运行 lingo init 和 lingo link 生成它，再提交结果。
3. Push。

从那之后，App 会自动为你处理这两种工作流：

• 当代码 push 到默认分支时，它会把翻译结果直接提交回该分支。
• 在 pull request 中，它会将翻译添加到该 PR，方便你在合并前审查。

由于 App 会在服务端跟踪翻译状态，你的仓库里不会有可能引发冲突的 lockfile，也无需额外接入验证步骤——它只会持续让目标语言区域设置与你的源语言保持同步。

方案 2：在你自己的流水线中运行 CLI#

如果你不使用 GitHub，或者希望把本地化作为构建和测试任务之外的一个明确步骤来运行，就自己运行 CLI。它适用于任何使用 Node.js 22 或更高版本的 CI 环境——GitHub Actions、GitLab CI、Bitbucket Pipelines，或其他任何环境。

流程始终一致：

1. 安装 @lingo.dev/cli。
2. 通过 LINGO_API_KEY 环境变量，使用你的 API 密钥完成身份验证。
3. 运行 lingo push，翻译已变更的字符串。
4. 提交结果，或者由你的任务创建一个 pull request。

将你的 Lingo.dev API 密钥保存为 CI secret，并将其暴露为 LINGO_API_KEY。已提交的 .lingo/config.json 会告诉 CLI 要翻译哪些内容，而已提交的 .lingo/lock.json（由 lingo push 重新生成）会跟踪状态，因此只处理发生变更的字符串。

GitHub Actions 最简示例#

这个工作流会安装 CLI，在每次 push 到 main 时执行翻译，并将结果提交回去：

name: Localize
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  localize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install -g @lingo.dev/cli
      - run: lingo push
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
      - name: Commit translations
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add .
          git commit -m "chore: update translations" || echo "No changes"
          git push

同样的两行——先 npm install -g @lingo.dev/cli，再 lingo push——也可以直接放进 GitLab CI 的 script: 代码块，或 Bitbucket Pipelines 的某个步骤中。在这些平台上，将 LINGO_API_KEY 设置为 masked/protected CI 变量。

直接提交还是 pull request？#

无论你选择哪种方案，翻译结果如何落地，依然由你决定：

GitHub App 会自动同时支持这两种方式——对于 push 到默认分支的更改，它会直接提交；对于打开的 PR，它会把翻译添加进去。在你自己的流水线中，选择权则在你手上：可以像上面那样直接提交结果，或者让任务创建一个 pull request，而不是向分支 push。

部署前验证翻译#

为了确保不会发布任何未翻译内容，可以在部署步骤前添加 lingo check 作为门禁。只要还有字符串尚未翻译，它就会以非零状态码退出：

- name: Verify translations
  run: lingo check

GitHub App 会持续保持语言区域同步，因此专门的验证步骤主要适用于你自行运行 CLI 的场景。

Monorepo#

对于每个包都有自己 .lingo/config.json 的 monorepo，你可以通过传入 glob 将运行范围限定到某个包，或者直接在该包目录中运行 CLI：

lingo push "apps/web/**"

后续步骤#