Bitbucket Pipelinesのレシピ

Bitbucket Pipelinesでファイルを翻訳し、結果をリポジトリにコミット。翻訳が最新でないプルリクエストはチェックで失敗させます。

Bitbucketのパイプラインを使い、Lingo.devの設定で指定したソースファイルを翻訳します。CLIが処理を送信して翻訳先ファイルをダウンロードし、パイプラインがその保存方法と受け渡し方法を決めます。このレシピでは、手動で起動するカスタムパイプラインから始めます。定期実行を設定する前に、まず一度、翻訳結果を確認できます。

接続には、Bitbucketアカウントとの標準連携コネクターではなく、ランナーからのAPI呼び出しを使用します。リポジトリへの書き込みとプルリクエストの作成には、Bitbucketの権限が別途必要です。

動作確認済みのカタログを一つ用意する #

ローカル環境でCLIクイックスタートの手順を実行し、.lingo/config.json、確認済みの翻訳先ファイル、.lingo/lock.jsonをコミットします。翻訳元と翻訳先のロケール、ローカライゼーションエンジン、ファイルパターンは、この設定に記述します。

この例ではlocales/en.jsonを使用し、locales/es.jsonにある既存のスペイン語ファイルだけを翻訳先にしています。翻訳先が複数ある場合は、翻訳先ファイルごとにtest -sとJSONのチェックを実行し、locales/es.jsonを指定するほかのコマンドには、すべての翻訳先パスを列挙してください。Lockfileにはソースが翻訳済みとして記録されるため、以降のプッシュではそのソースがスキップされ、アーティファクトに含めなかった翻訳先は古いままになります。以下のコマンドをソース変更時に繰り返し実行する運用に移る前に、lingo push --backfill-missing --waitで不足している翻訳先ファイルを作成してください。通常のプッシュでは、その後のソースの変更が処理されます。ただし、不足ファイルの補完では、既存の翻訳先ファイル内で欠落しているキーは補われません。

LINGO_API_KEYを保護されたリポジトリ変数として保存してください。CLIが読み取るのはこの名前だけです。以前のCLIで使われていたLINGODOTDEV_API_KEY変数は無視されるため、名前を変更してください。パイプラインは信頼できるコードで実行し、認証情報を扱う箇所ではシェルトレースを無効にしてください。変数を保護しても、プルリクエスト内の任意のスクリプトに公開してよいわけではありません。

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

翻訳して結果を保存する #

次のカスタムパイプラインをbitbucket-pipelines.ymlに追加します。

yaml
image: node:22

pipelines:
  custom:
    translate-catalog:
      - step:
          name: Translate and inspect
          script:
            # 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 diff -- locales/es.json .lingo/lock.json
          artifacts:
            - locales/es.json
            - .lingo/lock.json

ランナーがnpmからCLIをダウンロードできることを確認してください。ファイルパスは設定に合わせて調整します。

コミット済みの.lingo/config.jsonで、組織とエンジンの識別子を確認します。英語のソースに小さな変更を一つ加えてコミットし、その信頼できるブランチでtranslate-catalogを実行します。実行結果と差分を確認してからアーティファクトをダウンロードし、変更されたスペイン語の項目を該当するリビジョンのソースと照合します。アプリケーションでカタログを読み込み、変数と表示を確認してください。

ファイルの存在確認とJSONの解析で、出力の欠落や形式の不正を検出できます。ただし、形式が正しい古いファイルと、今回リクエストした新しい翻訳は区別できません。ローカライゼーションエンジンで人によるレビューが必要な場合は、アーティファクトを受け入れる前に、レビューを完了して処理済みの出力を取得してください。

送信と取得の状態を保持する #

プッシュは既定で非同期に実行されます。push --waitを指定すると、実行の完了を待ち、翻訳済みファイルをチェックアウトに書き込みます。--waitを指定しない場合、lingo pushは実行を送信するだけで終了するため、次のコマンドでは保持またはコミットする新しいファイルが見つかりません。人によるレビューを待つ場合は、後から翻訳結果を取得する手順が必要になることもあります。

レビュー待ちに入る前や、取得を別のステップで行う前に、継続的インテグレーションの実行状態を保持する手順を追加してください。送信後に、対象のポインターと元のプロジェクトルートの絶対パスをエクスポートします。その後の検証に失敗した場合も、必ずエクスポートしてください。.lingo-ci/run.json、.lingo-ci/project-root.txt、.lingo/config.json、locales/en.json、翻訳先ファイル、Lockfileを、アクセス制限付きのアーティファクトとして、レビューに十分な期間保存します。元のステップの失敗は確認できる状態に保ち、~/.lingo全体や認証情報は決してアーカイブしないでください。

取得時には、記録した絶対パスのルートに、同じリビジョンと保存済みのファイル状態を復元します。ポインターは対象のものだけを復元し、認証情報は別途渡して、出力を収集する前に--dry-runを指定してプルを実行します。後続のパイプラインステップで同じパスを再現できない場合は、送信と取得の両方に、必要な権限を持つ永続的なランナーを使用してください。ローカルの出力の競合は、内容を確認したうえで解決します。強制的にプルすると、レビュー担当者の変更が失われる可能性があります。

出力をリポジトリに反映する方法を選ぶ #

受け渡し前に人や後続のリリースジョブが出力を確認する場合は、アーティファクトで十分です。同じ完了済みの処理で得られた翻訳済みファイルとLockfileを一緒に保存してください。

レビューを経てリポジトリを更新するには、翻訳用ブランチにプッシュしてから、Bitbucket上で、またはドキュメントに記載されたAPIを使ってプルリクエストを作成します。次のセクションで示すように、ステップは既定のoriginを使い、追加の認証情報なしで自身のリポジトリにプッシュできます。リポジトリのSSHキーやアクセストークンを追加するのは、ブランチの権限設定でプッシュが拒否される場合、またはAPI経由でプルリクエストを作成する場合に限ってください。後者にはプルリクエストへの書き込み権限が必要です。チームのボットの識別情報を設定し、既知の翻訳先パスと.lingo/lock.jsonだけをステージングして、ステージング済みの差分がなければ終了します。同時実行で互いの変更を上書きしないよう、実行ごとに異なるブランチ名を使うか、再利用するブランチを意図的に決めてください。

直接コミットする場合も、同じ出力チェックを行い、ステージングの対象を限定します。ただし、プッシュ先は明示的に指定した信頼できるブランチにします。既定のブランチへ直接反映すると、翻訳用プルリクエストでのレビューがなくなるため、ブランチポリシーとして意図的に選択する必要があります。どちらの方法でも、反映後のアプリケーションの出力を確認してください。

Lingo.devのAPIキーは、リポジトリの認証情報と分けて管理します。翻訳プロセスの環境に設定し、Gitのリモート、コミットするファイル、出力アーティファクトには決して含めないでください。ランナー上の無関係なファイルを取り込まないように、git add .ではなく明示的なパスをステージングします。

翻訳結果を元のブランチにコミットする #

このブランチパイプラインは、mainに反映される変更をすべて翻訳し、結果をmainにコミットします。初回の一括翻訳がコミット済みで、エンジンの人によるレビューが無効になっており、翻訳が1つのステップで完了することを前提としています。このパイプラインのbranchesセクションを、カスタムパイプラインと同じpipelinesキーの下に追加してください。ファイル全体は次のようになります。

yaml
image: node:22

pipelines:
  custom:
    translate-catalog:
      - step:
          name: Translate and inspect
          script:
            - 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 diff -- locales/es.json .lingo/lock.json
          artifacts:
            - locales/es.json
            - .lingo/lock.json
  branches:
    main:
      - step:
          name: Translate and commit
          auth:
            system:
              scopes:
                - read:git:bitbucket
                - write:git:bitbucket
          script:
            # 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:$BITBUCKET_BRANCH"

lingo push --waitは、いずれかの翻訳先の処理に失敗するとゼロ以外の終了コードを返すため、コミット前にステップが停止します。変更がなければ「プッシュする内容はありません」と表示され、ステージング済みの差分もないため、コミットせずにステップが終了します。

パイプラインではoriginリモートが設定されるため、ステップは追加の認証情報なしで自身のリポジトリにプッシュできます。ステップのauthブロックは、組み込みトークンにGitのプッシュ権限を付与します。2027年4月30日以降、Bitbucketではauthブロックのないステップにこの権限が付与されなくなります。セルフホスト型ランナーでauthを使用するには、バージョン6.1.0以降が必要です。mainのブランチ制限でプッシュがブロックされる場合は、その制限のパイプライン書き込みアクセス設定にmainをソースブランチとして追加してください。または、Bitbucketのプッシュバックガイドに従い、書き込み権限のあるSSHキーかアクセストークンをステップに設定してください。

このステップが繰り返し実行され続けることはありません。コミットメッセージに[skip ci]があると、Bitbucketは翻訳コミットに対してパイプラインを起動しません。これがなくても、コミット済みの.lingo/lock.jsonに新しいソースがすでに記録されているため、次の実行ではプッシュする内容が見つかりません。翻訳中にブランチが更新された場合、Gitはプッシュを拒否し、より新しいコミットのパイプラインがその変更を翻訳します。

トリガーとパッケージのパスを調整する #

ブランチやプルリクエストの自動トリガーは、どのソースコードに認証情報へのアクセスを許可し、どのブランチに書き込みを許可するかを決めてから追加してください。フォークでは、シークレットや書き込み可能な送信先を利用できない場合があります。その解決策として、信頼できないコードを特権付きの認証情報で実行してはいけません。

生成されたコミットによって翻訳が無限に繰り返されないようにします。対象のソースパスと信頼できるブランチを選び、生成コミットに適切なルールを適用し、変更がなければ終了する処理も残してください。ソースに変更がなければ、差分が生じないのは正常です。

設定がapps/web/.lingo/config.jsonにある場合は、apps/webからCLIを実行します。パイプラインのアーティファクトパスには引き続き、リポジトリからの相対パスを使うBitbucketのルールが適用されるため、apps/web/locales/es.jsonやapps/web/.lingo/lock.jsonのようなパスを使用してください。CLIの作業ディレクトリを変更しても、アーティファクトパスの規則は変わりません。

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

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をコミットしてください。

このチェックは、前述のブランチパイプラインを使わない構成向けです。理由は次の表にまとめています。pipelinesの下にpull-requestsセクションを追加してください。手動パイプラインを残す場合は、customと並べて配置します。このチェックだけを設定する場合、ファイルは次のようになります。

yaml
image: node:22

pipelines:
  pull-requests:
    "**":
      - step:
          name: Check translations
          script:
            # lingo check needs CLI 1.20.0 or newer.
            - npx -y @lingo.dev/cli@1.21.0 check

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

翻訳の実行場所すべてのプルリクエストでチェックするか
開発者がlingo push --waitを実行し、結果をコミットしてからプルリクエストを作成するはい。ソースを変更したのに翻訳を更新していないプルリクエストを失敗させます。
マージ後にブランチパイプラインがmainにコミットするいいえ。機能開発のプルリクエストでは、設計上、翻訳より先にソースが変更されます。

ソースのハッシュはバイト単位で厳密に比較されます。lingo pushを実行したチェックアウトとCIのチェックアウトで、同じ改行コードを使ってください。たとえば、.gitattributesで* text=auto eol=lfを指定します。アプリケーションのリソースチェックも引き続き実施してください。

不足している出力を復旧する、または処理を停止する #

出力がない場合は、選択したソースファイル、ベースライン、翻訳先の網羅状況、保護された変数の利用可否、レビューの状態、報告された失敗を確認します。再送信を選ぶ前に、記録済みの実行を復旧してください。既存のプロジェクトで不足している翻訳先を補完する前に、既存の翻訳先に対する通常の更新を完了し、その結果を取得して確認します。その後、補完が終わるまでソースのリビジョンを固定してください。この一連の手順は言語を追加するに従ってください。強制的な再生成は、選択した承認済みテキストを意図的に置き換える場合にのみ使用します。失敗した実行の復旧では、強制的に置き換えずに再試行をリクエストする方法を説明しています。

新しいジョブの開始を止めるには、パイプラインのトリガーを無効にします。ランナーをキャンセルする際は、すでに送信済みのサーバー側の実行を別途確認してください。このレシピの運用を終了する場合は、不要なAPI変数とプロバイダーへの書き込み権限を削除します。