Lingo.dev Bitbucket 集成

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

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

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

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

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

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

让我们开始吧！

先决条件

存储库设置

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

第 1 步：认证设置

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

添加您的 API 密钥

导航到您的存储库 Repository settings → Repository variables，然后添加您的翻译引擎凭据：

对于原始 LLM API 用户：

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

对于 Lingo.dev Engine 用户：

• 变量名称：LINGODOTDEV_API_KEY
• 变量值：您的项目 API 密钥，获取地址为 lingo.dev/app

添加 Bitbucket 访问令牌（用于拉取请求模式）

如果您计划使用拉取请求模式，请创建一个访问令牌：

1. 转到 Repository settings → Access tokens → Create Repository Access Token
2. 授予以下权限：
   • 读取和写入存储库
   • 读取和写入拉取请求
3. 将令牌添加为存储库变量：
   • 变量名称：BB_TOKEN
   • 变量值：您的 Bitbucket 访问令牌

第 2 步：创建工作流

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

script:
  - pipe: lingodotdev/lingo.dev:main

此配置使用 Lingo.dev 管道并自动运行翻译引擎。

必需的权限

Bitbucket Pipelines 需要访问存储库变量和 Git 操作的权限：

存储库变量：

• LINGODOTDEV_API_KEY — Lingo.dev 引擎用户必需
• OPENAI_API_KEY 或 ANTHROPIC_API_KEY — 原始 LLM API 用户必需

对于拉取请求模式：

• BB_TOKEN — 用于创建和管理拉取请求

访问令牌范围（使用拉取请求模式时）：

• 读取和写入存储库 — 访问和修改存储库内容
• 读取和写入拉取请求 — 创建和管理拉取请求

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

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

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

直接提交模式（默认）

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

script:
  - pipe: lingodotdev/lingo.dev:main

此模式最适合：

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

拉取请求模式

集成为翻译更新创建拉取请求：

script:
  - pipe: lingodotdev/lingo.dev:main
    variables:
      LINGODOTDEV_PULL_REQUEST: "true"

拉取请求模式的必需设置

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

访问令牌要求： 您的 BB_TOKEN 必须包含对存储库和拉取请求的读取和写入权限。

注意： 使用拉取请求模式时，BB_TOKEN 变量是必需的。

此模式最适合：

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

第 4 步：工作流场景

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

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

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

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main

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

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

场景 2：更新的拉取请求（拉取请求模式）

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

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main
              variables:
                LINGODOTDEV_API_KEY: "${MY_LINGODOTDEV_API_KEY}" # 或 OPENAI_API_KEY/ANTHROPIC_API_KEY
                BB_TOKEN: "${MY_ACCESS_TOKEN}"
                LINGODOTDEV_PULL_REQUEST: "true"
                LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
                LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations"
                LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
                LINGODOTDEV_PROCESS_OWN_COMMITS: "true"

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

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

高级配置

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

使用 Lingo.dev 引擎的示例：

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main
              variables:
                LINGODOTDEV_API_KEY: "${MY_LINGODOTDEV_API_KEY}"
                BB_TOKEN: "${MY_ACCESS_TOKEN}"
                LINGODOTDEV_PULL_REQUEST: "true"
                LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
                LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations"
                LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
                LINGODOTDEV_PROCESS_OWN_COMMITS: "true"

使用原始 LLM API 的示例：

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main
              variables:
                OPENAI_API_KEY: "${MY_OPENAI_API_KEY}" # 或 ANTHROPIC_API_KEY
                BB_TOKEN: "${MY_ACCESS_TOKEN}"
                LINGODOTDEV_PULL_REQUEST: "true"
                LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
                LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations"
                LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
                LINGODOTDEV_PROCESS_OWN_COMMITS: "true"

配置选项：

• 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）
• BB_TOKEN — Bitbucket 访问令牌（拉取请求模式所需）