Lingo.dev のCLIは、Node.js が動くあらゆる CI/CD 環境で実行できます。パイプラインのステップに追加すれば、push のたびに翻訳を自動実行。lockfileによって変更された文字列だけが処理されるため、プロジェクトが大きくなっても高速かつコスト効率の高い翻訳を維持できます。
GitHub をお使いですか？実行方法は 2 つあります
GitHub なら、GitHub Appがいちばん簡単です。一度インストールすれば、push や pull request に自動で反応します。runner も API キーの secret も lockfile も不要で、.lingo/config.jsonとengineIdでリポジトリを設定できます。
GitHub Action とそのほかの以下の連携では、i18n.json、i18n.lock lockfile、LINGODOTDEV_API_KEY secret を使って、自分たちのパイプライン内で CLI を実行します。翻訳をほかの CI ステップと一緒に動かしたい場合や、GitHub 以外を使っている場合はこちらが適しています。
このガイドでは、ここから GitHub Action と CLI について説明します。
仕組み#
CI/CD パイプラインでは、checkout の後のステップとして CLI を実行します。CLI はi18n.json設定を読み込み、ソースファイルを lockfile と比較して変更を特定し、設定されたローカライゼーションエンジンを通じて差分だけを翻訳し、結果を対象ロケールのファイルに書き込みます。その後はワークフローの設定に応じて、パイプラインが翻訳済みファイルを commit するか、pull request を作成します。
ワークフローを選ぶ#
ほとんどのチームは、次の 4 つのワークフローパターンでカバーできます。まずは最もシンプルなものから始めて、チームの成長に合わせて発展させていきましょう。
| ワークフロー | 仕組み | 最適なケース | トレードオフ |
|---|---|---|---|
| main に commit | 翻訳して main に直接 commit | 小規模チーム、摩擦ゼロ | 翻訳のレビュー工程がない |
| main から PR | 翻訳してレビュー用の PR を作成 | 翻訳をレビューするチーム | PR の手動承認が必要 |
| feature branch に commit | feature branch への push 時に翻訳 | 長期間運用する feature branch | branch の履歴に翻訳の commit が残る |
| feature branch から PR | 翻訳して feature branch から PR を作成 | 機能ごとに最大限コントロールしたい場合 | 機能ごとに複数の PR が発生 |
最初のおすすめ
ほとんどのチームには、main に commit する運用がよく合います。翻訳は push のたびに反映され、lockfile が一貫性を保ち、ローカライゼーションエンジンの glossary とブランドボイスのルールが品質を支えます。翻訳に人のレビューが必要になったら、PR ベースのワークフローに移行しましょう。
クイックセットアップ#
Lingo.dev の API キーを CI/CD の secret として保存し、パイプラインに翻訳ステップを追加してください。
Lingo.dev は、checkout、翻訳、commit / PR 作成までをまとめて処理する公式 GitHub Actionを提供しています。
ワークフローファイルや API キーの secret、lockfile を管理したくないなら、GitHub Appがおすすめです。そうした設定なしで GitHub 上の継続的なローカライズを実現でき、一度インストールして.lingo/config.jsonを設定するだけで使えます。
main に commit:
name: Translate
on:
push:
branches: [main]
permissions:
contents: write
jobs:
translate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: lingodotdev/lingo.dev@main
with:
api-key: ${{ secrets.LINGODOTDEV_API_KEY }}main から PR - pull-request: trueとGH_TOKENを追加してください:
name: Translate
on:
push:
branches: [main]
permissions:
contents: write
pull-requests: write
jobs:
translate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: lingodotdev/lingo.dev@main
with:
api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
pull-request: true
env:
GH_TOKEN: ${{ github.token }}feature branch ワークフロー、カスタム commit メッセージ、monorepo サポート、GPG 署名については、完全版のGitHub Actions 連携ガイドをご覧ください。
翻訳の検証#
--frozenフラグと lockfile は、GitHub Action と CLI に含まれます。GitHub Appは翻訳状態をサーバー側で追跡するため、lockfile も --frozen に相当するものもありません。
--frozenフラグをデプロイゲートとして使えば、未翻訳のコンテンツが本番環境に出るのを防げます。翻訳が必要な文字列が 1 つでもある場合、CLI は非ゼロステータスで終了します。
npx lingo.dev@latest run --frozenデプロイ前に実行する別のパイプラインステップとして、これを追加してください:
- name: Verify translations
run: npx lingo.dev@latest run --frozenmonorepo ワークフロー#
それぞれ独自の翻訳ファイルを持つ複数パッケージの monorepo では、特定のパッケージを対象にするためにworking-directoryオプションを使います:
- uses: lingodotdev/lingo.dev@main
with:
api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
working-directory: apps/webマージコンフリクト#
これは GitHub Action と CLI に当てはまります。GitHub Appは lockfile を使わないため、解決すべきi18n.lockコンフリクトは発生しません。
翻訳変更を含む branch 同士をマージすると、lockfile（i18n.lock）で競合が起きることがあります。対処はシンプルで、競合した lockfile を削除し、マージを完了してから再生成します:
git merge feature-branch
rm i18n.lock
git add .
git merge --continue
npx lingo.dev@latest lockfile --forcelockfile --forceコマンドは、新しい翻訳を発生させることなく、現在のソースファイルの状態から lockfile を再構築します。rebase ベースの解決方法や競合を防ぐための戦略については、高度な連携パターンガイドをご覧ください。
