GitHub Actionsによる継続的インテグレーションの実装例
信頼できるGitHub Actionsジョブで翻訳を実行し、成果物を確認したうえで、出力の準備が整ったらプルリクエストで反映する仕組みを追加します。
翻訳に既存のパイプラインのトリガーやチェックを使う場合は、GitHub ActionsでLingo.dev CLIを実行します。ランナーがリポジトリの設定を読み取り、原文の変更を送信して、翻訳済みファイルをダウンロードします。ファイルを成果物として保持するか、プルリクエストにするかは、選択できます。
この実装例では、手動実行とリポジトリへの読み取り専用アクセスから始めます。変更されたメッセージを1件確認したら、翻訳のプルリクエストに必要な書き込み権限を追加できます。ネイティブのGitHub Appを使えば、このランナーの実装例を使わずに、リポジトリの処理をサービス側に任せることもできます。
リポジトリを準備する #
原文ファイル1つと翻訳先言語1つを使い、ローカル環境でCLIクイックスタートの手順を完了します。.lingo/config.json、内容を確認した翻訳先ファイル、.lingo/lock.jsonをコミットします。設定では、ローカライゼーションエンジン、翻訳元と翻訳先のロケール、ファイルパターンを指定します。Lockfileには、その後の原文の変更に備えた基準となる状態が記録されます。
以下の例では、翻訳元をlocales/en.json、翻訳先をスペイン語に設定し、locales/es.jsonを生成します。翻訳先ファイルがまだない場合はlingo push --backfill-missing --waitで作成し、その後の原文の編集にはlingo push --waitを使います。バックフィルの対象は存在しない翻訳先ファイルです。既存ファイル内の欠落したキーを修復するものではありません。
リポジトリまたは環境のアクション用シークレットにLINGO_API_KEYを追加します。これはGitHubのリポジトリ権限とは別に、Lingo.devへのアクセスを許可するものです。認証情報を使うジョブは、信頼できるコードに対してのみ実行してください。特に、pull_request_targetを使って信頼できないプルリクエストの先端リビジョンをチェックアウトし、シークレットを使って実行することは避けてください。
この例ではCLIのバージョンを固定しています。プロジェクトの依存関係とLockfileで管理する場合は、継続的インテグレーションの設定ガイドに従ってください。
翻訳の成果物を取得する #
これを.github/workflows/translate.ymlとして保存します。この例ではNode.js 22を使用します。
name: Translate catalog
on:
workflow_dispatch:
permissions:
contents: read
jobs:
translate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- name: Translate and download
# Replace 1.21.0 with the current CLI version.
run: npx -y @lingo.dev/cli@1.21.0 push --wait
env:
LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
- name: Inspect expected output
run: |
test -s locales/es.json
node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
git diff -- locales/es.json .lingo/lock.json
- uses: actions/upload-artifact@v4
with:
name: translated-catalog
include-hidden-files: true
path: |
locales/es.json
.lingo/lock.jsonコミット済みの.lingo/config.jsonで、組織とエンジンの識別子を確認します。英語の原文を1か所編集してコミットし、その信頼できるブランチからワークフローを手動実行します。ジョブログで実行結果と差分を確認してから、成果物をダウンロードし、編集内容に対応するスペイン語の項目を探します。アプリケーションで読み込み、意味と変数を確認してください。
アップロードには隠しファイルも含まれるため、.lingo/lock.jsonが保持されます。パスの一覧は、対象の翻訳先ファイルとLockfileだけに限定してください。認証情報やその他の非公開の隠しファイルまで含めないでください。
シェルによるチェックでは、ファイルの存在とJSON構文を検証します。古い翻訳先ファイルでも両方のチェックに通るため、変更された項目を確認することが重要です。ローカライゼーションエンジンで人によるレビューが必要な場合は、コマンドが終了しても、実行は人の対応を待っていることがあります。このポリシーを使い捨てのランナーで使用する前に、継続的インテグレーションでの実行状態の保存手順を追加してください。送信後に、対象の実行を指すポインターと元のプロジェクトルートの絶対パスをエクスポートし、.lingo-ci/run.json、.lingo-ci/project-root.txt、.lingo/config.json、locales/en.json、翻訳先ファイル、Lockfileをアクセス制限付きの成果物としてアップロードします。エクスポートとアップロードのステップではif: always()を使い、後続のチェックに失敗しても復元可能な状態が失われないようにします。ポインターが見つからない場合は、送信状況を調査してください。ポインターを勝手に作ってはいけません。
レビュー後、記録された絶対パスのルートに、まったく同じリビジョンとファイル状態を復元し、ポインターも復元します。その後、別途認証を行い、競合チェック付きのプルを実行します。別のランナーで同じパスを再現できない場合は、必要な権限を持つ永続的なランナーで送信と取得を行ってください。最初の成果物に含まれる古い翻訳先ファイルを、完成した翻訳として扱わないでください。
push --waitは完了を待機し、取得可能な完了済みの出力をダウンロードします。--waitを指定しない場合、プッシュは通常、送信後に終了します。送信と取得を別々のジョブで行う場合も、同じ実行状態のエクスポートと復元が必要です。Lockfileをコピーするだけでは不十分です。同じ完了済みの操作からダウンロードした翻訳先ファイルとLockfileは、まとめて保持してください。また、~/.lingo全体をアーカイブしないでください。
プルリクエストで反映する #
成果物を確認し、問題がなければ、ジョブにcontents: writeとpull-requests: writeを付与します。リポジトリのポリシーでも、アクションによるプルリクエストの作成を許可する必要があります。GITHUB_TOKENはこれらのGitHub操作を認可するものです。翻訳には引き続きLINGO_API_KEYを使用してください。
チームのボットポリシーに従って、Gitのユーザー情報を設定します。その後、出力検証の後に、想定した翻訳先ファイルとLockfileだけをステージングするステップを追加します。
git add locales/es.json .lingo/lock.json
git diff --cached --quiet && exit 0
branch="lingo/translations-${GITHUB_RUN_ID}"
git switch -c "$branch"
git commit -m "chore: update translations"
git push origin "$branch"
gh pr create --fill --base "$GITHUB_REF_NAME" --head "$branch"GitHubホスト型ランナーにはGitHub CLIが含まれています。このステップのGH_TOKENには、secrets.GITHUB_TOKENの値を渡します。この手順は、信頼できるブランチからの手動実行と、新しいブランチ名を前提としています。既存のブランチで再実行する場合は、そのブランチを再利用するか置き換えるかを明示的に決める必要があります。フォークへの書き戻しを行うワークフローではありません。
プルリクエストの反映先は、ジョブを手動実行したブランチです。GitHubでワークフローが承認待ちになっている場合は、リポジトリへの書き込み権限を持つ人がワークフローの実行を承認を選択する必要があります。GitHubのGITHUB_TOKENの動作を参照してください。マージする前に、翻訳の差分、チェック結果、アプリケーションでの出力をレビューしてください。
適切なブランチポリシーがあれば、トリガー元のブランチに直接コミットすることもできます。ただし、その場合は独立したコンテンツレビューの段階がなくなり、ループの防止も必要になります。
実行をスケジュールし、モノレポに対応する #
最初の実行で有用な結果が得られたら、信頼できるブランチへのプッシュをトリガーに追加し、原文パスのフィルターを設定します。生成された翻訳コミットが、次の翻訳ジョブを繰り返し起動しないようにしてください。適切なブランチまたはパスのフィルターと、反映ステップで変更がない場合に終了する処理を組み合わせます。
モノレポでは、翻訳ステップの作業ディレクトリを、.lingo/config.jsonが含まれるパッケージに設定します。アーティファクトのパスとステージング対象のパスも、そのパッケージを含むように更新してください。マトリックスを使うと独立したパッケージを処理できますが、2つのエントリが同じ設定とLockfileを更新して競合しないようにしてください。同じ実行内のエントリは実行識別子を共有するため、各エントリに固有のアーティファクト名と翻訳ブランチを割り当てます。たとえば、translated-catalogとlingo/translations-${GITHUB_RUN_ID}にパッケージ名を追加します。
未完了の実行を復旧する #
まず、報告された状態を確認します。失敗した翻訳先ではエラーの解決が、レビュー待ちの翻訳先では判断が必要です。ローカルでプルの競合が発生した場合は、ローカルの編集とダウンロードした結果のどちらを採用するかを選びます。未完了のロケールは未解決のままにしつつ、成功した出力は確認できる状態で保持してください。部分的な結果を、そのロケールの完全なリリースとして扱ってはいけません。
ゼロ以外の終了コードを隠さないでください。|| true、編集を上書きする強制プル、すべての翻訳先の強制処理は、原因を隠し、承認済みの作業を置き換えてしまう可能性があります。復旧中にリビジョンと基準となる状態を保持する方法は、継続的インテグレーションのワークフローガイドで説明しています。
新しいランナージョブの起動を止めるには、ワークフローまたはそのトリガーを無効にします。ジョブがすでに翻訳を送信している場合は、アクションをキャンセルする際に、対応するサーバー側の実行も別途確認してください。ワークフローを廃止する際は、不要になったシークレットとリポジトリへの書き込み権限を削除します。