Lingo.dev GitLab 連携

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

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

この連携は複数のワークフローシナリオをサポートしています：

1. コンテンツ変更がプッシュされた時の直接コミット
2. 翻訳更新のためのマージリクエスト

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

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

それでは始めましょう！

前提条件

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

リポジトリには有効なi18n.jsonファイルで設定されたLingo.dev CLIが必要です。まだセットアップしていない場合は、先にCLI クイックスタートを完了してください。

ステップ1. 認証のセットアップ

Lingo.dev GitLab 連携は翻訳エンジンとリポジトリへのアクセスが必要です。認証は資格情報を安全に保つリポジトリ変数を通じて行われます。

APIキーの追加

リポジトリの設定 → CI/CD → 変数に移動し、翻訳エンジンの資格情報を追加します：

生のLLM APIユーザーの場合：

• 変数名：OPENAI_API_KEYまたはANTHROPIC_API_KEY
• 変数値：それぞれのプロバイダーからのAPIキー

Lingo.dev Engineユーザーの場合：

• 変数名：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インテグレーションは、チームのコードレビュー要件に応じて2つの操作モードをサポートしています。

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

インテグレーションは翻訳を直接ブランチにコミットします：

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）

トラブルシューティング

一般的なエラーとその解決策：