Lingo.dev は翻訳をコードと常に同期された状態に保ちます。変更のたびに、どのコンテンツが変わったかを検出し、接続済みのローカライゼーションエンジンで翻訳します。用語集ルール、ブランドボイス、ロケールごとのモデル設定も一貫して適用され、結果はコミットされるか、プルリクエストとして作成されます。未完了の翻訳が本番環境に入り込むことはありません。
連携方法を選ぶ#
各連携にはそれぞれ専用ガイドがあります。セットアップに合うものを選んでください。
| 連携 | 実行方法 |
|---|---|
| GitHub App | 一度インストールするだけ。Lingo.dev がデフォルトブランチへの push 時にローカリゼーションを実行し、有効化すればプルリクエストでも動作します。runner も API キーのシークレットも lockfile も不要です。 |
| GitHub Actions | @lingo.dev/cli をインストールし、GitHub Actions パイプラインで lingo push を実行して、結果をコミットするか PR を作成します。 |
| GitLab CI/CD | @lingo.dev/cli をインストールし、GitLab パイプラインのジョブで lingo push を実行します。 |
| Bitbucket Pipelines | @lingo.dev/cli をインストールし、Bitbucket パイプラインのステップで lingo push を実行します。 |
GitHub App は Lingo.dev のサーバー上で動作します。それ以外の連携ではすべて Lingo.dev CLI を実行するため、Node.js 22+ が動作する CI/CD 環境であれば、ファーストパーティ連携がなくてもローカライゼーションを直接実行できます。
GitHub App の仕組み#
アプリを一度インストールし、リポジトリに .lingo/config.json を追加すれば準備完了です。あとは Lingo.dev がローカリゼーションを自動で実行します。パイプラインも API キーのシークレットも lockfile も不要です。
- 変更を監視 - 標準でデフォルトブランチへの push に反応し、
onPullRequestを有効にするとプルリクエストにも反応して、設定したソースパターンに照らして変更ファイルを確認します - 差分だけを翻訳 - 変更されたソースコンテンツを
engineIdで指定したエンジンに送って翻訳します - 結果を GitHub に書き戻す - デフォルトブランチへの push では翻訳用プルリクエストを作成または更新し、プルリクエストでは翻訳済みファイルを PR ブランチにコミットしてステータスコメントを投稿します
- 取りこぼしを補完して分割処理 - 以前の実行で見逃した変更を検出し、非常に大きな更新は複数のコミットに分けて処理します
承認ステップの後に実行するようにしたり、プルリクエスト内で /lingo コマンドを使って手動で翻訳をトリガーしたりできます。設定の詳細は GitHub App ガイド をご覧ください。
CLI 連携のしくみ#
GitHub Actions、GitLab CI/CD、Bitbucket の各連携は、既存のパイプライン内のステップとして、いずれも同じ Lingo.dev CLI を実行します。必要なのは 2 つだけです。.lingo/config.json の設定ファイルと、認証用の LINGO_API_KEY です。
各実行時に、ジョブは CLI（npm install -g @lingo.dev/cli）をインストールし、lingo push を実行します。これにより、次の処理が行われます。
- ソースファイルを見つける - bucket configuration を読み取り、翻訳対象のコンテンツを特定します
- 変更を検出 -
.lingo/lock.jsonロックファイルと比較して、新規または更新された文字列を特定し、差分だけを翻訳します - 翻訳 - 変更されたコンテンツを、用語集、ブランドボイス、ロケールごとのモデル設定など、すべてのルールを適用した設定済みの ローカライゼーションエンジン に送ります
- 結果を書き込み - 対象ロケールのファイルをその場で更新し、
.lingo/lock.jsonを最新の状態に保ちます
その後、パイプラインは各プラットフォーム標準のツールを使って、結果をコミットするかプルリクエストを作成します。翻訳対象は変更された文字列だけなので、数十ものロケールにまたがる場合でも、高速かつコスト効率よく実行できます。
ワークフローの選択肢#
GitHub App#
App の動作は .lingo/config.json で設定します。
| オプション | 内容 |
|---|---|
デフォルトブランチへの push（onPushToDefaultBranch） | デフォルトで有効です。デフォルトブランチにソースの変更が入ると、翻訳 PR を作成または更新します。 |
プルリクエスト翻訳（onPullRequest） | デフォルトでは無効です。PR の変更にあわせて、翻訳を PR ブランチにコミットします。 |
承認ゲート（requireApproval） | デフォルトでは無効です。自動実行で翻訳を行う前に、チェック実行での Approve/Deny、または PR 上での /lingo approve が必要です。 |
手動コマンド（/lingo translate） | PR コメントから、いつでも特定ファイルの翻訳を補完したり強制実行したりできます。 |
設定全体とコマンドリファレンスについては、GitHub App ガイドをご覧ください。
CI/CD で CLI を使う（GitHub Actions、GitLab CI、Bitbucket）#
代表的なチーム構成は、次の 4 つのワークフローパターンでほぼカバーできます。
| ワークフロー | トリガー | 出力 |
|---|---|---|
| main にコミット | main への push | 翻訳を main に直接コミット |
| main から PR 作成 | main への push | 翻訳付きのプルリクエスト |
| feature ブランチにコミット | feature ブランチへの push | 翻訳をそのブランチにコミット |
| feature ブランチから PR 作成 | feature ブランチへの push | そのブランチからのプルリクエスト |
最初の選択肢である main へのコミットが最もシンプルです。開発者の手を介さずに翻訳が自動で反映されます。一方、PR ベースの選択肢では、翻訳が取り込まれる前にレビューのステップを挟めます。
選び方の詳細は Advanced Patterns をご覧ください。
