CI/CDローカライゼーションワークフロー

Lingo.dev なら、CI/CD でのローカライゼーションを自動化できます。方法は 2 つ。GitHub App を使ってサーバー側で push やプルリクエストに対応する方法と、独自のパイプライン内で CLI を実行する方法です。どちらも変更のたびに翻訳を同期し、実際に変更された文字列だけを処理するので、プロジェクトが成長してもローカライゼーションを高速かつコスト効率よく保てます。

オプション 1: GitHub App（推奨）#

GitHub App は、継続的ローカライゼーションを始める最もシンプルな方法です。リポジトリを監視してサーバー側で翻訳を実行するため、パイプライン側で何かをインストールする必要はなく、CI secret として API キーを保存する必要もありません。

セットアップは一度だけで完了します。

1. リポジトリに Lingo.dev GitHub App をインストールします。
2. .lingo/config.json を commit します。このファイルには orgId、engineId、source ロケール、target ロケール、翻訳対象のファイルを設定します。生成するにはローカルで lingo init と lingo link を実行し、その結果を commit してください。
3. Push します。

以降は、App が次の 2 つのワークフローを自動で処理します。

• デフォルトブランチへの push では、翻訳をそのブランチに commit します。
• プルリクエストでは、その PR に翻訳を追加するので、マージ前にレビューできます。

App は翻訳の状態をサーバー側で管理するため、リポジトリ内で lockfile の競合が起きることもなく、検証ステップを別途組み込む必要もありません。source と target ロケールの同期をシンプルに保てます。

オプション 2: 独自のパイプラインで CLI を実行#

GitHub 以外を使っている場合や、ビルドやテストのジョブと並ぶ明示的なステップとしてローカライゼーションを実行したい場合は、CLI を自分で実行してください。Node.js 22 以降が使える CI 環境であれば、GitHub Actions、GitLab CI、Bitbucket Pipelines など、どこでも動作します。

流れは常に同じです。

1. @lingo.dev/cli をインストールします。
2. LINGO_API_KEY 環境変数経由で API キーを使って認証します。
3. lingo push を実行して、変更された文字列を翻訳します。
4. 結果を commit するか、ジョブからプルリクエストを作成します。

Lingo.dev の API キーは CI secret として保存し、LINGO_API_KEY として渡してください。commit 済みの .lingo/config.json が CLI に翻訳対象を伝え、commit 済みの .lingo/lock.json（lingo push で再生成）が状態を追跡することで、変更された文字列だけが処理されます。

最小構成の GitHub Actions 例#

このワークフローでは CLI をインストールし、main への push ごとに翻訳を実行して、結果をブランチに commit します。

name: Localize
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  localize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install -g @lingo.dev/cli
      - run: lingo push
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
      - name: Commit translations
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add .
          git commit -m "chore: update translations" || echo "No changes"
          git push

同じ 2 行、つまり npm install -g @lingo.dev/cli のあとに lingo push を実行するだけで、GitLab CI の script: ブロックや Bitbucket Pipelines のステップにもそのまま組み込めます。これらのプラットフォームでは、LINGO_API_KEY を masked/protected な CI variable として設定してください。

commit とプルリクエスト、どちらにする？#

どちらの方法を選んでも、翻訳の反映方法は選べます。

GitHub App なら、この 2 つを自動で使い分けられます。デフォルトブランチへの push では commit し、オープン中の PR には翻訳を追加します。独自のパイプラインでは、選ぶのはあなたです。上記のように結果を commit してもいいですし、ブランチに push する代わりにジョブからプルリクエストを作成してもかまいません。

デプロイ前に翻訳を検証する#

未翻訳のコンテンツがそのまま公開されないようにするには、デプロイステップの前に lingo check をゲートとして追加してください。未翻訳の文字列が残っている場合は、非ゼロのステータスで終了します。

- name: Verify translations
  run: lingo check

GitHub App はロケールを継続的に同期するため、専用の検証ステップが特に役立つのは、CLI を自分で実行する場合です。

モノレポ#

各パッケージが独自の .lingo/config.json を持つモノレポでは、glob を渡して対象パッケージに絞って実行するか、そのパッケージのディレクトリから CLI を実行してください。

lingo push "apps/web/**"

次のステップ#