Lingo.dev Bitbucketインテグレーション

Lingo.dev Bitbucket Pipelinesインテグレーションは、新しいコンテンツを自動的にローカライズし、不完全な翻訳がプロダクション環境に到達するのを防ぐ、安全でオープンソースのCI/CDインテグレーションです。チームのワークフロー要件に応じて、プルリクエストを作成するか、ブランチに直接コミットします。

また、リベースによる自動競合解決を実装しているため、手動介入なしに翻訳をコードと同期させることができます。

このインテグレーションは複数のワークフローシナリオをサポートしています：

  1. コンテンツ変更がプッシュされた際のブランチへの直接コミット
  2. 翻訳更新のためのブランチを対象としたプルリクエスト

このガイドを完了すると、以下のことができるようになります：

  1. コードプッシュによってトリガーされる自動ローカライゼーションのセットアップ
  2. リポジトリ変数を使用した安全な認証の設定
  3. 直接コミットまたはプルリクエストワークフローの選択
  4. 継続的なローカライゼーションが既存のプロセスにどのように適合するかの理解

それでは始めましょう！

前提条件

リポジトリのセットアップ

リポジトリには有効なi18n.jsonファイルで設定されたLingo.dev CLIが必要です。まだセットアップしていない場合は、先に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
  • 変数値：lingo.dev/appからのプロジェクトAPIキー

Bitbucketアクセストークンの追加（プルリクエストモード用）

プルリクエストモードを使用する予定がある場合は、アクセストークンを作成します：

  1. Repository settings → Access tokens → Create Repository Access Tokenに移動
  2. 以下のスコープを付与：
    • リポジトリの読み取りと書き込み
    • プルリクエストの読み取りと書き込み
  3. トークンをリポジトリ変数として追加：
    • 変数名：BB_TOKEN
    • 変数値：BitbucketアクセストークンN

ステップ 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統合は、チームのコードレビュー要件に応じて2つの操作モードをサポートしています。

直接コミットモード（デフォルト）

この統合は翻訳を直接ブランチにコミットします：

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アクセストークン（プルリクエストモードに必要）