Lingo.dev では、GitHub 上で継続的ローカライゼーションを実行する方法を 2 つ用意しています。マネージドな GitHub App を使う方法と、GitHub Actions ジョブ内で @lingo.dev/cli を実行する方法です。
どちらを使うべき？
まずは GitHub App から始めるのがおすすめです。サーバー側で動作し、push や pull request に自動で反応するうえ、runner も API キーの secret も lockfile の管理も不要です。ほかの CI ステップと一緒に、自分のパイプライン内でローカライゼーションを動かしたい場合は GitHub Actions を選んでください。
GitHub App（推奨）#
GitHub App は、GitHub 上で継続的ローカライゼーションを実行するもっとも手軽な方法です。一度インストールしてエンジンを指定すれば、以後はすべての push と pull request に自動で反応します。
- GitHub App ページからアプリをインストールし、リポジトリへのアクセスを許可します。
- リポジトリのルートに
.lingo/config.jsonをコミットし、bucket とロケール、さらにアプリが使用するエンジンのengineIdを記述します。ファイル形式については Configuration を参照してください。 - あとは push するだけです。アプリが変更されたコンテンツをサーバー側でローカライズし、結果をコミットで反映するか、必要に応じて pull request を作成して、
.lingo/lock.jsonを自動で最新の状態に保ちます。
アプリはサーバー側で動作するため、管理すべき runner も、保存しておく LINGO_API_KEY secret も、実行する lockfile コマンドも必要ありません。
GitHub Actions#
自分のパイプライン内でローカライゼーションを実行する場合は、ジョブに CLI をインストールして lingo push を実行し、その後、既存のツールで結果をコミットするか pull request を作成します。
API キーは、LINGO_API_KEY という名前のリポジトリ secret として保存してください（Settings > Secrets and variables > Actions）。CLI は環境変数からそれを読み取ります。
現在のブランチにコミットする#
.github/workflows/localize.yml を作成します。
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
- name: Install Lingo.dev CLI
run: npm install -g @lingo.dev/cli
- name: Localize
run: lingo push
env:
LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
- name: Commit translations
run: |
git config user.name "Lingo.dev"
git config user.email "support@lingo.dev"
git add .
git diff --staged --quiet || git commit -m "feat: update translations"
git pushこれにより、変更されたコンテンツがローカライズされ、push のたびに結果がそのブランチへ直接コミットされます。
pull request を作成する#
直接コミットする代わりに、レビューを通して翻訳を反映したい場合は、結果をブランチに push して pull request を作成します。この例では GitHub CLI を使用します。これは GitHub ホスト型 runner に標準でインストールされています。
name: Localize
on:
push:
branches: [main]
permissions:
contents: write
pull-requests: write
jobs:
localize:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- name: Install Lingo.dev CLI
run: npm install -g @lingo.dev/cli
- name: Localize
run: lingo push
env:
LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
- name: Open pull request
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
git config user.name "Lingo.dev"
git config user.email "support@lingo.dev"
branch="lingo/translations-${{ github.run_id }}"
git checkout -b "$branch"
git add .
git diff --staged --quiet && exit 0
git commit -m "feat: update translations"
git push origin "$branch"
gh pr create --fill --base "${{ github.ref_name }}" --head "$branch"PRベースのワークフローでは、Settings > Actions > General > Allow GitHub Actions to create and approve pull requests を有効にしてください。
同じジョブは feature branch でも動作します。どこでローカライゼーションを実行するかは、on.push.branches フィルター（たとえば branches-ignore: [main]）を変更して制御できます。
