Lingo.dev GitHub 連携

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

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

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

コンテンツの変更がマージされた際に、メインブランチへの直接コミット
PRがオープンまたは更新された際に、プルリクエストブランチへの直接コミット
翻訳更新のためのメインブランチを対象としたプルリクエスト
翻訳更新のための既存のプルリクエストブランチを対象としたプルリクエスト

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

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

それでは始めましょう！

前提条件

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

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

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

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

APIキーの追加

リポジトリの設定 → シークレットと変数 → アクションに移動し、翻訳エンジンの資格情報を追加します：

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

シークレット名：OPENAI_API_KEYまたはANTHROPIC_API_KEY
シークレット値：それぞれのプロバイダーからのAPIキー

Lingo.devエンジンユーザーの場合：

シークレット名：LINGODOTDEV_API_KEY
シークレット値：lingo.dev/appからのプロジェクトAPIキー

ステップ2. ワークフローの作成

リポジトリに.github/workflows/i18n.ymlを作成し、以下の基本設定を追加してください：

name: Lingo.dev i18n

on:
  workflow_dispatch:
  push:
    branches:
      - main
      - feat/*

permissions:
  contents: write
  pull-requests: write

jobs:
  i18n:
    name: Run i18n
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

代わりに、既存のワークフローにLingo.dev GitHub Actionをステップとして追加することもできます：

- name: Lingo.dev
  uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

必要な権限

ワークフローが適切に機能するには特定の権限が必要です。GitHub Actionsではワークフローファイルで明示的な権限宣言が必要です：

permissions:
  contents: write # 必須: 翻訳更新を含むコミットの作成
  pull-requests: write # オプション: プルリクエストモードを使用する場合のみ必要

contents: write権限により、アクションは以下のことが可能になります：

翻訳更新を含むコミットの作成
変更を直接リポジトリにプッシュ
リポジトリ内のファイルへのアクセスと変更

これらの権限は、ワークフローの一時的なGitHubトークン（${{ github.token }}）に付与されます。このトークンはワークフロー実行ごとにGitHubによって自動的に作成され、ワークフローファイルで指定した正確な権限を持ちます。

この設定は：

mainおよびフィーチャーブランチへのプッシュ時にトリガー
コミットとプルリクエストに必要な権限を付与
自動更新のために最新のアクションバージョンを使用
リポジトリシークレットを介してAPIキーに安全にアクセス

ボーナス：

Lingo.devでは、すべてのワークフローにworkflow_dispatchトリガーを追加することをお勧めしています。これにより、GitHub Actions UIから手動で（再）実行することができます。これは完全にオプションですが、非常に役立つことがわかっています。

ステップ3. ワークフローモードを選択する

Lingo.dev GitHub Actionsは、チームのコードレビュー要件に応じて2つの操作モードをサポートしています。

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

このアクションは翻訳を直接ブランチにコミットします：

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

このモードは以下の場合に最適です：

個人開発者または小規模チーム
マージ前にレビューされるフィーチャーブランチ
翻訳の更新に個別のレビューが不要なプロジェクト

プルリクエストモード

このアクションは翻訳の更新用にプルリクエストを作成します：

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true
    pull-request-title: "feat: update translations"

プルリクエストモードに必要な権限

プルリクエストモードには追加の権限とリポジトリ設定が必要です：

permissions:
  contents: write # 必須: リポジトリコンテンツへのアクセスとコミットの作成
  pull-requests: write # 必須: プルリクエストの作成と更新

GitHub トークン設定: GH_TOKEN環境変数は${{ github.token }}に設定する必要があります。これはGitHubが各ワークフロー実行ごとに自動的に作成する一時的なトークンです。このトークンはワークフローファイルのpermissionsセクションで指定された権限を持ちます。

リポジトリ設定: リポジトリ設定でGitHub Actionsがプルリクエストを作成できるようにする必要があります：

設定 → Actions → 一般に移動
ページの下部までスクロール
「ワークフロー権限」の下で、**「GitHub Actionsによるプルリクエストの作成と承認を許可する」**が有効になっていることを確認

リポジトリ設定でこのオプションが表示されない場合は、組織の設定を確認してください：

組織の設定 → Actions → 一般に移動
同じ「GitHub Actionsによるプルリクエストの作成と承認を許可する」設定を探す

このモードは以下の場合に最適です：

厳格なコードレビュー要件を持つチーム
翻訳の変更に個別の承認が必要なプロジェクト
すべての変更に明示的なレビューが必要なワークフロー

ステップ 4. ワークフローシナリオ

Lingo.dev GitHub Actionは異なる開発ワークフローに自動的に適応します。これらのシナリオを理解することで、チームに最適な構成を選択できます。

シナリオ 1: メインブランチの更新（直接コミット）

トリガー: メインブランチへのプッシュ（例：プルリクエストのマージ時） アクション: 翻訳の更新を直接メインブランチにコミット

on:
  push:
    branches: [main]

# アクションが直接メインブランチにコミット

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

フロー: mainにプッシュされたコンテンツの変更 → アクションが翻訳をmainにコミット

このシナリオでは、コンテンツの変更がマージされた直後に、メインブランチに常に最新の翻訳が含まれるようになります。

ヒント: これは推奨するモードです。完璧なローカライゼーションを確保するために適切に構成されたAIローカライゼーションエンジンが必要です。利点は、不足している翻訳が本番デプロイ前に自動的にチェックされ補完されるため、手動介入が一切不要になることです。

シナリオ 2: プルリクエストの更新（直接コミット）

トリガー: コンテンツ変更を含むプルリクエストのオープンまたは更新 アクション: 翻訳の更新を直接プルリクエストブランチにコミット

on:
  pull_request:
    types: [opened, synchronize]

# アクションが直接PRブランチにコミット

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

フロー: PRブランチのコンテンツ変更 → アクションが同じPRブランチに翻訳をコミット

これにより翻訳の更新がフィーチャーブランチ内に保持され、元の変更と一緒に翻訳もレビューされるようになります。

シナリオ 3: メインへのプルリクエスト（プルリクエストモード）

トリガー: メインブランチへのプッシュ（例：プルリクエストのマージ時） アクション: 翻訳の更新を含むプルリクエストを作成

on:
  push:
    branches: [main]

# アクションがPRを作成: main/lingo.dev → main

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true

フロー: コンテンツの変更がmainにプッシュされる → アクションがmain/lingo.devブランチを作成 → main/lingo.devからmainへのPRをオープン

シナリオ4: フィーチャーブランチへのプルリクエスト（プルリクエストモード）

トリガー: コンテンツ変更を含むプルリクエストがオープンまたは更新された場合 アクション: 翻訳更新を含むプルリクエストをフィーチャーブランチに向けて作成

on:
  pull_request:
    types: [opened, synchronize]

# アクションがPRを作成: feat/new-feature/lingo.dev → feat/new-feature

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true

フロー: feat/new-featureのコンテンツ変更 → アクションがfeat/new-feature/lingo.devブランチを作成 → feat/new-feature/lingo.devからfeat/new-featureへのPRをオープン

これにより、各フィーチャーブランチに対して個別の翻訳レビューが維持されます。

ブランチの命名規則

プルリクエストモードを使用する場合、Lingo.dev GitHub Actionは一貫した命名パターンに従います：

フォーマット: <ベースブランチ>/lingo.dev

例:

メインブランチの更新: main/lingo.dev → main
フィーチャーブランチの更新: feat/user-auth/lingo.dev → feat/user-auth
リリースブランチの更新: release/v2.0/lingo.dev → release/v2.0

この命名規則により、翻訳ブランチが明確に識別でき、自動的にソースブランチにリンクされます。

外部コントリビューションの処理

外部フォークを扱う場合、リポジトリのセキュリティを維持するために選択的チェックアウトを実装します：

jobs:
  i18n:
    name: Run i18n
    runs-on: ubuntu-latest
    permissions:
      actions: write
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - run: find locales/** -name "*.json" | xargs git checkout ${{ github.event.pull_request.head.sha }} --
        shell: bash
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

外部コントリビューションに必要な権限

外部フォークの処理には、コントリビューションを安全に処理するための昇格された権限が必要です：

permissions:
  actions: write # 必須：ワークフロー情報とアーティファクトへのアクセス
  contents: write # 必須：コミットの作成とリポジトリコンテンツへのアクセス
  pull-requests: write # 必須：外部フォークからのプルリクエストの更新

actions: write 権限は特に以下のために必要です：

外部フォークからのプルリクエストメタデータへのアクセス
セキュリティ検証のためのワークフローコンテキストの読み取り
アーティファクトとワークフロー状態の安全な処理

これらの昇格された権限により、アクションは選択的なファイルチェックアウトを通じてリポジトリのセキュリティを維持しながら、外部コントリビューターからの翻訳を安全に処理できます。

このアプローチ：

フォークから翻訳ファイルのみをチェックアウト
機密性の高いリポジトリコードの露出を防止
アクションに必要な書き込み権限を維持

高度な設定

追加パラメータを使用してアクションの動作をカスタマイズします：

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true
    commit-message: "feat: update translations via lingo.dev"
    working-directory: "apps/web"
    version: "latest"
    process-own-commits: false
    parallel: true

設定オプション：

commit-message — 翻訳コミット用のカスタムメッセージ
working-directory — サブディレクトリでアクションを実行
version — 特定のCLIバージョンに固定（非推奨）
process-own-commits — このアクションによって作成されたコミットを処理
parallel — ローカライゼーションタスクの並列処理を有効化（デフォルト：false）

並列処理

GitHub Actionは、大規模プロジェクトの翻訳ワークフローを大幅に加速するために、ローカライゼーションタスクの並列処理をサポートしています。parallel: trueを設定することでこの機能を有効化できます：

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    parallel: true

有効化すると、アクションは以下を実行します：

複数の同時ワーカーにローカライゼーションタスクを分散
スループットを最大化するためのインテリジェントなタスク分散アルゴリズムを使用
慎重な同時実行管理によるファイル破損と競合状態の防止
多数の翻訳ファイルを持つプロジェクトの処理時間を劇的に短縮

この機能は特に以下の場合に有益です：

広範な翻訳要件を持つ大規模プロジェクト
複数のロケールを同時に処理するワークフロー
より高速なCI/CDパイプライン実行を必要とするチーム

注意: 並列処理によりAPI使用量が増加する可能性があります。厳格なレート制限がある場合は使用状況を監視してください。

検証モード

本番デプロイメント前に、--frozenフラグを使用してすべての翻訳が最新であることを検証できます。

デプロイメントパイプラインで--frozenフラグを使用する例：

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx lingo.dev@latest i18n --frozen
      - run: npm run build
      - run: npm run deploy

--frozenフラグの機能：

すべての翻訳が最新であることを検証
ファイルに変更を加えない
翻訳が不足または古い場合にビルドを失敗させる