Buildkite の設定例

Buildkite パイプラインでファイルを翻訳して結果をブランチにプッシュし、翻訳が最新でないプルリクエストをチェックで失敗させます。

Buildkite のステップでは、自前のエージェント上で Lingo.dev CLI を使い、リポジトリ内のファイルを翻訳できます。CLI は Lingo.dev の設定で選択されたソースファイルを送信し、翻訳済みファイルをチェックアウト先に書き込みます。その後、翻訳をどう反映するかはパイプラインで決めます。エージェント、シークレット、リポジトリへのアクセスは Buildkite が管理し、Lingo.dev はローカライゼーションエンジンでファイルを処理します。

これは継続的インテグレーションの設定例であり、Buildkite とのネイティブ接続ではありません。まずはデフォルトブランチまたはプルリクエストのビルドに翻訳ステップを1つ追加し、最初に作成されるコミットを確認してください。プルリクエストのチェックは、後述の表で適しているとされる構成にのみ追加してください。

リポジトリとエージェントを準備する #

ローカルでCLI クイックスタートを完了してください。.lingo/config.json、受け入れ済みのターゲットファイル、.lingo/lock.jsonをコミットします。設定では、ソースロケール、ターゲットロケール、ファイルパターン、ローカライゼーションエンジンを選択します。例ではlocales/en.jsonをソースとし、locales/es.jsonにある既存のスペイン語ターゲットを使用します。ターゲットが複数ある場合は、ターゲットファイルごとにtest -sと JSON のチェックを1回ずつ実行してください。また、locales/es.jsonを指定しているほかのコマンドにも、すべてのターゲットパスを列挙するか、locales/のようにターゲットディレクトリ全体をステージングしてください。Lockfile にはソースが翻訳済みとして記録されるため、以後のプッシュではそのソースがスキップされ、コミットから漏れたターゲットは古いままになります。

継続的に実行するステップを導入する前に、lingo push --backfill-missing --waitで不足しているターゲットファイルを作成してください。その後のソース変更には通常のlingo push --waitを使用します。不足ファイルの補完では、既存のターゲット内で欠落しているキーは補われません。

エージェントには Node.js、npm、Git に加え、npm レジストリと Lingo.dev へのネットワークアクセスが必要です。デプロイキーなど、エージェントがチェックアウトに使用するリポジトリ認証情報には、ステップの書き込み先ブランチへのプッシュ権限も必要です。

Lingo.dev の API キーを、LINGO_API_KEYという名前のBuildkite シークレットとして保存します。CLI が読み取るのは、この名前のシークレットだけです。以前の CLI で使用していたLINGODOTDEV_API_KEY変数は無視されるため、名前を変更してください。シークレットは翻訳を行うステップでのみ読み込んでください。ステップのsecrets:キーを使うには、シークレットを保持するクラスター上で動作する、バージョン 3.106.0 以降の Buildkite エージェントが必要です。それ以前のバージョンではパイプラインが失敗します。古いエージェントやクラスターに属さないエージェントでは、secrets:を削除し、代わりにエージェントのenvironmentフックまたはシークレット用プラグインから、そのステップ用にLINGO_API_KEYをエクスポートしてください。

パイプラインのGitHub 設定では、サードパーティのフォークリポジトリからのビルドを許可をオフのままにしてください。フォークからのプルリクエストは、そのフォーク自身のpipeline.ymlを使ってビルドされるため、シークレットを読み取るステップを追加できてしまいます。こちらのファイルにどのようなif:を設定しても、それを防ぐことはできません。シークレットにもアクセスポリシーを追加し、このパイプラインのビルドだけが読み取れるようにしてください。

例では CLI のバージョンを 1.21.0 に固定しています。lingo checkによる翻訳ファイルのチェックは、CLI 1.20.0 以降で利用できます。プロジェクトの依存関係と Lockfile でバージョンを管理するには、継続的インテグレーションのセットアップガイドに従ってください。

翻訳してブランチにプッシュする #

このステップは、デフォルトブランチに取り込まれる変更をその都度翻訳し、結果を同じブランチにプッシュします。初回の補完結果がコミット済みで、エンジンの人によるレビューがオフになっており、翻訳が1つのステップで完了することを前提としています。.buildkite/pipeline.ymlに追加してください。

yaml
steps:
  - label: "Translate"
    if: build.branch == pipeline.default_branch && build.pull_request.id == null
    concurrency: 1
    concurrency_group: "lingo-translations"
    # secrets: needs Buildkite agent 3.106.0 or later.
    secrets:
      - LINGO_API_KEY
    command: |
      # Replace 1.21.0 with the current CLI version.
      npx -y @lingo.dev/cli@1.21.0 push --wait
      test -s locales/es.json
      node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
      git add -- locales/es.json .lingo/lock.json
      if git diff --cached --quiet; then exit 0; fi
      git config user.name "Localization bot"
      git config user.email "localization@example.com"
      git commit -m "[skip ci] Update translations"
      git push origin "HEAD:refs/heads/$${BUILDKITE_BRANCH}"

--waitを指定すると、ステップは実行の完了を待ち、翻訳済みファイルをチェックアウト先に書き込みます。指定しない場合、lingo pushは実行を送信するだけで終了するため、ステップにはコミット対象がありません。ターゲットの処理が失敗すると、lingo push --waitはゼロ以外の終了コードを返し、コミット前にステップが停止します。変更がない場合は「プッシュするものはありません」と表示され、ステージング済みの差分は空のまま、コミットせずにステップが終了します。

Buildkite はブランチではなく単一のコミットをチェックアウトするため、プッシュ時にはブランチ名を指定します。$$を使うとBUILDKITE_BRANCHがそのまま保持され、ステップの実行時にシェルが展開します。$を1つだけ使うと、Buildkite がパイプラインのアップロード時にブランチ名をコマンド内に書き込みます。concurrencyとconcurrency_groupにより、翻訳は一度に1件ずつ実行されます。翻訳中にブランチが更新された場合、Git はプッシュを拒否し、新しいコミットのビルドがその変更を翻訳します。

このステップはループしません。Buildkite は、メッセージに[skip ci]を含むコミットのビルドをスキップします。これがなくても、コミット済みの.lingo/lock.jsonには新しいソースがすでに記録されているため、次のビルドではプッシュ対象が見つかりません。

デフォルトブランチに直接プッシュすると、翻訳用プルリクエストのレビューが省かれます。その点を踏まえ、ブランチポリシーとして意図的に選択してください。先に翻訳をレビューする場合は、代わりにlingo/translationsなどの別ブランチにプッシュし、Git プロバイダーのツールでプルリクエストを作成します。

プルリクエストのビルドで翻訳する #

各プルリクエストのソース変更をそのブランチ上で翻訳するには、デフォルトブランチ用ステップの代わりにこのステップを使用します。前提条件は同じです。フォークのブランチにはプッシュできないため、このステップのif:はフォークからのプルリクエストをスキップします。

このステップを使うには、パイプラインのGitHub 設定で2つの設定が必要です。プルリクエストの作成時または更新時にビルドをオンにしてください。ブランチをビルドはオフにするか、デフォルトブランチだけに制限します。ブランチのビルドがオンの場合、プルリクエストのブランチへのプッシュによって、プルリクエストの詳細情報を持たないビルドが開始されることがあります。ステップはそのビルドをスキップするため、翻訳は行われず、失敗にもなりません。

if:はLINGO_API_KEYを保護しません。Buildkite はプルリクエスト自身のpipeline.ymlからこれを読み取り、フォーク側でそのファイルを変更できます。そのため、セットアップで説明したとおり、フォークのビルドはオフのままにする必要があります。リポジトリ内のブランチからのプルリクエストでも、このファイルは変更できます。つまり、ブランチにプッシュできる人は誰でも、このステップを通じてキーを読み取れます。プッシュ権限を持つ全員がキーを保有してもよい場合にのみ、このステップを使用してください。

yaml
steps:
  - label: "Translate pull request"
    if: build.pull_request.id != null && build.pull_request.repository.fork != true
    # secrets: needs Buildkite agent 3.106.0 or later.
    secrets:
      - LINGO_API_KEY
    command: |
      # Replace 1.21.0 with the current CLI version.
      npx -y @lingo.dev/cli@1.21.0 push --wait
      test -s locales/es.json
      node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
      git add -- locales/es.json .lingo/lock.json
      if git diff --cached --quiet; then exit 0; fi
      git config user.name "Localization bot"
      git config user.email "localization@example.com"
      git commit -m "Update translations"
      git push origin "HEAD:refs/heads/$${BUILDKITE_BRANCH}"

コミットメッセージに[skip ci]を含めないのは意図的です。Buildkite が翻訳コミットをビルドすると、ステップが再実行されますが、プッシュ対象が見つからないため、コミットせずに終了します。つまり、追加のビルド1回でループが終わります。このビルドによって、プルリクエストの最新コミットにステータスが付与されます。[skip ci]を含めると、最新コミットに対する Buildkite のビルドが行われず、必須の Buildkite ステータスチェックによってマージがブロックされます。

エージェントのチェックアウト用認証情報には、プルリクエストのブランチへのプッシュ権限が必要です。翻訳中にブランチが更新された場合、Git はプッシュを拒否し、ステップは失敗します。その変更は、新しいコミットのビルドで翻訳されます。そのため、短時間に2回プッシュすると翻訳が2回開始され、両方が課金対象になります。パイプライン設定で中間ビルドをキャンセルをオンにし、新しいプッシュによって古いビルドがキャンセルされるようにしてください。ただし、古いビルドがすでに送信した翻訳はキャンセルされません。

翻訳が最新でないプルリクエストをチェックで失敗させる #

lingo checkは、設定された各ソースを.lingo/lock.jsonと比較し、すべてのターゲットファイルが存在することを確認します。最後の翻訳以降にソースが変更された場合、ソースに対応する Lockfile のエントリがない場合、ターゲットファイルがない場合、またはfilesのパターンに一致するソースファイルがない場合は、終了コード1を返します。API キーやシークレットは不要で、書き込みも行いません。DO_NOT_TRACK=1で無効にするCLI テレメトリを除き、ネットワーク通信も行いません。ただし、npxの例ではチェックの実行前に npm から CLI をダウンロードします。これは、以前の CLI の--frozenによるチェックに代わるものです。

チェック対象はファイルであり、キーではありません。手動で編集したターゲットもチェックを通過します。また、既存のターゲット内でキーが欠落していても、React の.jsoncカタログ内を除いて報告されません。.lingo/lock.jsonがないとソースの変更を検出できないため、変更されたソースや一度もプッシュされていないソースがあってもチェックは失敗せず、その旨が標準エラー出力に表示されます。lingo pushが書き込む Lockfile をコミットしてください。

以下の表でこのチェックが適しているとされる場合に、.buildkite/pipeline.ymlへこのステップを追加してください。このチェックは、上記のどちらの翻訳ステップも使わない構成向けです。そのため、ここで示す各例は、それぞれの構成に必要なsteps:リスト全体になっています。2つ目のsteps:キーを追加するのではなく、既存のsteps:リストにこのステップを組み込んでください。

yaml
steps:
  - label: "Check translations"
    if: build.pull_request.id != null
    command:
      # lingo check needs CLI 1.20.0 or newer.
      - npx -y @lingo.dev/cli@1.21.0 check

このチェックは、ソースの変更と翻訳を一緒にコミットする構成に適しています。

翻訳を実行する場所すべてのプルリクエストでのチェック
開発者がlingo push --waitを実行し、プルリクエストの作成前に結果をコミットする適しています。翻訳せずにソースを変更したプルリクエストをチェックで失敗させます。
翻訳ステップがマージ後にデフォルトブランチへプッシュする適していません。機能開発のプルリクエストでは、翻訳前にソースが変更されることが前提となっているためです。
プルリクエスト用ステップがプルリクエストのブランチにコミットする適していません。翻訳を行うビルドでは、チェックが翻訳前のコミットを検査するため失敗します。翻訳コミットでステップ自体が再実行され、プッシュ対象が見つからないことによって、.lingo/lock.json以降にソースが変更されていないと確認できます。

ソースのハッシュは、バイト単位の違いを厳密に反映します。たとえば.gitattributesに* text=auto eol=lfを設定するなどして、lingo pushを実行したチェックアウトと継続的インテグレーションでのチェックアウトで、同じ改行コードを使用してください。

ステップを調整する #

モノレポでは、.lingo/config.jsonを含むパッケージから CLI を実行し、そのパッケージのターゲットファイルと Lockfile をステージングします。たとえば、コマンドの先頭にcd apps/webを指定します。独立したパッケージはそれぞれ別の Lockfile を保持し、異なるローカライゼーションエンジンを使用できます。

ローカライゼーションエンジンが処理を人によるレビューに回す場合、lingo push --waitは完了したファイルだけを書き込み、終了コード0を返します。この部分的な結果を、すべて完了したものとしてコミットしないでください。継続的インテグレーションでの実行状態の保持手順を追加し、レビュー完了後に同じエージェント上でプルを実行して残りを取得してください。

ステップの復旧と廃止 #

エラーの内容から、次に取るべき対応を判断してください。パッケージのインストールを修復する、シークレットを設定する、レビューを完了する、プルの競合を解決する、原因を修正して失敗したターゲットの処理を再試行する、といった対応が必要です。ゼロ以外の終了コードを隠さず、確認できる状態にしてください。|| trueを使うと原因が隠れてしまいます。

新しいビルドを止めるには、ステップまたはそのトリガーを削除します。ビルドをキャンセルする際は、すでに送信済みの翻訳を別途確認してください。この設定を廃止する際は、LINGO_API_KEYシークレットを削除し、エージェントの書き込み権限を取り消してください。