Lingo.dev GitLab 集成

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

它还通过重新基准化实现自动冲突解决，因此您的翻译可以与代码保持同步，无需人工干预。

该集成支持多种工作流程场景：

1. 当内容更改被推送时，直接提交到分支；
2. 针对翻译更新的分支创建合并请求。

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

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

让我们开始吧！

前置条件

存储库设置

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

第 1 步：认证设置

Lingo.dev GitLab 集成 需要访问您的翻译引擎和存储库。认证通过存储库变量进行，以确保您的凭据安全。

添加您的 API 密钥

导航到存储库的 设置 → CI/CD → 变量，然后添加您的翻译引擎凭据：

对于原始 LLM API 用户：

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

对于 Lingo.dev 引擎用户：

• 变量名称：LINGODOTDEV_API_KEY
• 变量值：从 lingo.dev/app 获取的项目 API 密钥

添加 GitLab 访问令牌

为存储库操作创建一个自定义访问令牌：

1. 转到 设置 → 访问令牌 → 添加新令牌
2. 授予以下权限范围：
   • api
   • read_repository
   • write_repository
3. 将令牌添加为存储库变量：
   • 变量名称：GL_TOKEN
   • 变量值：您的 GitLab 访问令牌

重要提示： 默认的 CI 作业令牌不足以满足需求。您必须 创建自定义访问令牌，因为默认令牌缺少执行 git 操作所需的权限。

注意： 对于受保护的分支，请确保您的变量也被标记为受保护。未受保护的变量在受保护分支的管道中将无法访问。

第 2 步：创建工作流

创建或更新您的 .gitlab-ci.yml 文件，使用以下基本配置：

lingodotdev:
  image: lingodotdev/ci-action:latest
  script:
    - echo "Done"

此配置使用最新的 Docker 镜像，并自动运行翻译引擎。

所需权限

GitLab CI/CD 需要访问存储库变量和 Git 操作：

存储库变量：

• LINGODOTDEV_API_KEY — Lingo.dev 引擎用户必需
• OPENAI_API_KEY 或 ANTHROPIC_API_KEY — 原始 LLM API 用户必需
• GL_TOKEN — 必需用于 Git 推送操作和创建合并请求

访问令牌范围：

• api — 创建和管理合并请求
• read_repository — 访问存储库内容
• write_repository — 推送提交并创建分支

这些权限允许集成读取您的内容、生成翻译并使用本地化内容更新您的存储库。

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

Lingo.dev GitLab 集成 支持两种操作模式，具体取决于您的团队代码审查要求。

直接提交模式（默认）

集成将翻译直接提交到您的分支：

lingodotdev:
  image: lingodotdev/ci-action:latest
  script:
    - echo "Done"

此模式最适合：

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

合并请求模式

集成为翻译更新创建合并请求：

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    LINGODOTDEV_PULL_REQUEST: "true"
  script:
    - echo "Done"

合并请求模式的必要设置

存储库变量： LINGODOTDEV_API_KEY 和 GL_TOKEN 必须配置为存储库变量。

访问令牌要求： 您的 GL_TOKEN 必须包含 api 范围以创建和管理合并请求。

此模式最适合：

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

第 4 步：工作流场景

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

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

触发条件： 推送到功能分支 操作： 将翻译更新直接提交到功能分支

lingodotdev:
  image: lingodotdev/ci-action:latest
  script:
    - echo "Done"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH = /^feat/

流程： 内容更改推送到功能分支 → 集成将翻译提交到同一分支

这使翻译更新保持在功能分支内，确保翻译与原始更改一起进行审查。

场景 2：更新的合并请求（合并请求模式）

触发条件： 推送到任何配置的分支 操作： 创建包含翻译更新的合并请求

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    LINGODOTDEV_API_KEY: $MY_LINGODOTDEV_API_KEY # 或 OPENAI_API_KEY/ANTHROPIC_API_KEY
    LINGODOTDEV_PULL_REQUEST: "true"
    LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
  script:
    - echo "Done"

流程： 内容更改推送到分支 → 集成创建包含翻译的合并请求

这为翻译更新维护了单独的审查流程。

高级配置

通过额外的变量自定义集成行为：

使用 Lingo.dev 引擎的示例：

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    LINGODOTDEV_API_KEY: $MY_LINGODOTDEV_API_KEY
    GL_TOKEN: $MY_GL_TOKEN
    LINGODOTDEV_PULL_REQUEST: "true"
    LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
    LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations via @lingodotdev"
    LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
    LINGODOTDEV_PROCESS_OWN_COMMITS: "true"
  script:
    - echo "Done"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH = /^feat/

使用原始 LLM API 的示例：

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    OPENAI_API_KEY: $MY_OPENAI_API_KEY # 或 ANTHROPIC_API_KEY
    GL_TOKEN: $MY_GL_TOKEN
    LINGODOTDEV_PULL_REQUEST: "true"
    LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
    LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations via @lingodotdev"
    LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
    LINGODOTDEV_PROCESS_OWN_COMMITS: "true"
  script:
    - echo "Done"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH = /^feat/

配置选项：

• LINGODOTDEV_API_KEY — 如果您使用的是 Lingo.dev 引擎，这是您的 Lingo.dev 引擎 API 密钥
• OPENAI_API_KEY — 如果您使用的是原始 LLM API，这是您的 OpenAI API 密钥
• ANTHROPIC_API_KEY — 如果您使用的是原始 LLM API，这是您的 Anthropic API 密钥
• LINGODOTDEV_PULL_REQUEST — 创建合并请求而不是直接提交（默认值：false）
• LINGODOTDEV_PULL_REQUEST_TITLE — 自定义合并请求标题（默认值：feat: update translations via @lingodotdev）
• LINGODOTDEV_COMMIT_MESSAGE — 自定义提交消息（默认值：feat: update translations via @lingodotdev）
• LINGODOTDEV_WORKING_DIRECTORY — 在子目录中运行集成（默认值：.）
• LINGODOTDEV_PROCESS_OWN_COMMITS — 处理由此集成生成的提交（默认值：false）

故障排除

常见错误及其解决方案：