CI/CD 本地化工作流

Lingo.dev CLI 可运行在任何支持 Node.js 的 CI/CD 环境中。把它加入流水线步骤后，即可在每次推送时自动翻译；lockfile 会确保只处理变更过的字符串，因此即使项目不断增长，翻译依然快速且具备成本效益。

在 GitHub 上？有两种运行方式

如果你使用 GitHub，GitHub App 是最省心的选择——安装一次后，它就会自动响应推送和拉取请求。无需 runner、无需 API key secret，也不需要 lockfile；你只需用 .lingo/config.json 和一个 engineId 配置仓库即可。

GitHub Action 以及下方其他集成方式，会在你自己的流水线中运行 CLI，并使用 i18n.json、i18n.lock lockfile 和一个 LINGODOTDEV_API_KEY secret。如果你希望翻译与其他 CI 步骤一起运行，或者并不使用 GitHub，这条路径更适合你。

本指南接下来的内容将重点介绍 GitHub Action 和 CLI。

工作原理#

CI/CD 流水线会在 checkout 之后，将 CLI 作为一个步骤运行。CLI 会读取你的 i18n.json 配置，将源文件与 lockfile 对比以识别变更，通过已配置的本地化引擎翻译增量内容，并将结果写入目标语言环境文件。随后，流水线会根据你偏好的工作流，提交已翻译文件或发起一个拉取请求。

选择适合你的工作流#

这四种工作流模式覆盖了大多数团队形态。建议先从最简单的方式开始，随着团队发展再逐步升级。

工作流	工作方式	适用场景	取舍
直接提交到 main	翻译后直接提交到 main	小团队，几乎零摩擦	翻译没有审核环节
从 main 发起 PR	翻译后创建 PR 供审核	需要审核翻译的团队	需要手动批准 PR
提交到功能分支	在功能分支推送时执行翻译	长期存在的功能分支	翻译提交会保留在分支历史中
从功能分支发起 PR	翻译后从功能分支发起 PR	希望按功能获得最大控制力	每个功能会产生多个 PR

推荐起步方式

对大多数团队来说，直接提交到 main 是个很好的起点。翻译会随每次推送一同发布，lockfile 能确保一致性，而本地化引擎中的术语表和品牌语调规则则负责把控质量。只有在需要人工审核翻译时，再切换到基于 PR 的工作流即可。

快速配置#

将你的 Lingo.dev API key 存储为 CI/CD secret，然后把翻译步骤加入流水线。

Lingo.dev 提供了一个官方 GitHub Action，可处理 checkout、翻译，以及提交或创建 PR。

不想维护工作流文件、API key secret 或 lockfile？GitHub App 可以在 GitHub 上持续进行本地化，完全不需要这些——安装一次并配置 .lingo/config.json 即可。

直接提交到 main：

yaml

name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

从 main 发起 PR——添加 pull-request: true 和一个 GH_TOKEN：

yaml

name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
  pull-requests: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
          pull-request: true
        env:
          GH_TOKEN: ${{ github.token }}

想了解功能分支工作流、自定义提交信息、monorepo 支持和 GPG 签名，请参阅完整的 GitHub Actions 集成指南。

翻译校验#

--frozen 标志和 lockfile 适用于 GitHub Action 与 CLI。GitHub App 会在服务端跟踪翻译状态，因此没有 lockfile，也没有与 --frozen 对应的机制。

可将 --frozen 标志用作部署门禁，确保未翻译内容不会进入生产环境。只要还有任何字符串需要翻译，CLI 就会以非零状态码退出。

bash

npx lingo.dev@latest run --frozen

可将其作为独立的流水线步骤，并在部署前运行：

yaml

- name: Verify translations
  run: npx lingo.dev@latest run --frozen

Monorepo 工作流#

如果你的 monorepo 包含多个 package，且每个 package 都有各自的翻译文件，可使用 working-directory 选项来指定目标 package：

yaml

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

合并冲突#

这一部分适用于 GitHub Action 和 CLI。GitHub App 不使用 lockfile，因此也不存在需要解决的 i18n.lock 冲突。

当包含翻译变更的分支合并时，lockfile（i18n.lock）可能产生冲突。解决方法很简单——删除冲突的 lockfile，完成合并，然后重新生成它：

bash

git merge feature-branch
rm i18n.lock
git add .
git merge --continue
npx lingo.dev@latest lockfile --force

lockfile --force 命令会根据当前源文件状态重建 lockfile，而不会触发新的翻译。关于基于 rebase 的解决方式和冲突预防策略，请参阅高级集成模式指南。

后续步骤#

GitHub App

GitHub 上的托管式持续本地化——无需 runner、secret 或 lockfile

GitHub Actions

完整的 GitHub Actions 配置，支持 GPG 签名和自定义设置

GitLab CI

完整的 GitLab CI/CD 配置，支持 access token 和合并请求

Bitbucket Pipelines

完整的 Bitbucket Pipelines 配置，支持 pipe 和拉取请求

高级模式

工作流选择、冲突解决与部署门禁

在 GitHub 上？有两种运行方式

本指南接下来的内容将重点介绍 GitHub Action 和 CLI。

工作原理#

选择适合你的工作流#

这四种工作流模式覆盖了大多数团队形态。建议先从最简单的方式开始，随着团队发展再逐步升级。

工作流	工作方式	适用场景	取舍
直接提交到 main	翻译后直接提交到 main	小团队，几乎零摩擦	翻译没有审核环节
从 main 发起 PR	翻译后创建 PR 供审核	需要审核翻译的团队	需要手动批准 PR
提交到功能分支	在功能分支推送时执行翻译	长期存在的功能分支	翻译提交会保留在分支历史中
从功能分支发起 PR	翻译后从功能分支发起 PR	希望按功能获得最大控制力	每个功能会产生多个 PR

推荐起步方式

快速配置#

将你的 Lingo.dev API key 存储为 CI/CD secret，然后把翻译步骤加入流水线。

Lingo.dev 提供了一个官方 GitHub Action，可处理 checkout、翻译，以及提交或创建 PR。

不想维护工作流文件、API key secret 或 lockfile？GitHub App 可以在 GitHub 上持续进行本地化，完全不需要这些——安装一次并配置 .lingo/config.json 即可。

直接提交到 main：

yaml

name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

从 main 发起 PR——添加 pull-request: true 和一个 GH_TOKEN：

yaml

name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
  pull-requests: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
          pull-request: true
        env:
          GH_TOKEN: ${{ github.token }}

想了解功能分支工作流、自定义提交信息、monorepo 支持和 GPG 签名，请参阅完整的 GitHub Actions 集成指南。

翻译校验#

--frozen 标志和 lockfile 适用于 GitHub Action 与 CLI。GitHub App 会在服务端跟踪翻译状态，因此没有 lockfile，也没有与 --frozen 对应的机制。

可将 --frozen 标志用作部署门禁，确保未翻译内容不会进入生产环境。只要还有任何字符串需要翻译，CLI 就会以非零状态码退出。

bash

npx lingo.dev@latest run --frozen

可将其作为独立的流水线步骤，并在部署前运行：

yaml

- name: Verify translations
  run: npx lingo.dev@latest run --frozen

Monorepo 工作流#

如果你的 monorepo 包含多个 package，且每个 package 都有各自的翻译文件，可使用 working-directory 选项来指定目标 package：

yaml

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

合并冲突#

这一部分适用于 GitHub Action 和 CLI。GitHub App 不使用 lockfile，因此也不存在需要解决的 i18n.lock 冲突。

当包含翻译变更的分支合并时，lockfile（i18n.lock）可能产生冲突。解决方法很简单——删除冲突的 lockfile，完成合并，然后重新生成它：

bash

git merge feature-branch
rm i18n.lock
git add .
git merge --continue
npx lingo.dev@latest lockfile --force

lockfile --force 命令会根据当前源文件状态重建 lockfile，而不会触发新的翻译。关于基于 rebase 的解决方式和冲突预防策略，请参阅高级集成模式指南。

后续步骤#

GitHub App

GitHub 上的托管式持续本地化——无需 runner、secret 或 lockfile

GitHub Actions

完整的 GitHub Actions 配置，支持 GPG 签名和自定义设置

GitLab CI

完整的 GitLab CI/CD 配置，支持 access token 和合并请求

Bitbucket Pipelines

完整的 Bitbucket Pipelines 配置，支持 pipe 和拉取请求

高级模式

工作流选择、冲突解决与部署门禁