本文へスキップ
本文へスキップ

ドキュメント / ガイド

機械翻訳されたページ

このページは自動翻訳のため、誤りや不自然な表現が含まれている可能性があります。正式な内容は英語版です。英語の原文を読む。

CI で verbatra を実行する

CLI を使えばどの CI システムでも、翻訳のドリフト、壊れた値、未レビューの機械翻訳で pull request を失敗させ、プッシュ時に翻訳できます。

パイプラインでソースからドリフトしたロケールファイルを検出したい場合や、プッシュ時に自動で翻訳したい場合に、このガイドを使います。すべての手順は、ローカルで実行するのと同じ CLI を実行します。そのため、どの CI システムでも動作します。例では GitHub Actions を使います。

始める前に、次のものが必要です。

  • 開発依存として追加した @verbatra/cli。パッケージマネージャーのロックファイルもコミットしておきます。CLI には Node ^22.22.0 || >=24 が必要です。
  • コミット済みの設定ファイル、ロケールファイル、verbatra.lock.json。
  • 翻訳する場合だけ:プロバイダーの API キーを CI のシークレットストアに登録しておくこと。

GitHub Actions を使っていて、ジョブを自分で書かずに注釈とジョブの概要を使いたい場合は、代わりに GitHub Action を使うを参照してください。

ドリフトゲートを追加する

verbatra check は、ソース、ターゲットファイル、ロックファイルを比較し、欠落または古くなったキーがあるロケールがあれば終了コード 1 で終了します。プロバイダーを呼び出さないため、ジョブに API キーは不要で、フォークからの pull request でも実行できます。

.github/workflows/i18n.yml
name: i18n
on: pull_request

permissions:
  contents: read

jobs:
  check-translations:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@<commit-sha>
      - uses: pnpm/action-setup@<commit-sha>
      - uses: actions/setup-node@<commit-sha>
        with:
          node-version: 22
      - run: pnpm install --frozen-lockfile
      - run: pnpm exec verbatra check

ドリフトの原因になっているキー名がほしい場合(たとえば pull request のコメントに投稿したい場合)は、check を verbatra diff に置き換えます。終了コード 1 になる条件は同じです。孤立したキーは出力に表示されますが、それだけで失敗することはありません。

一部のロケールだけをゲートの対象にするには、--locales de,fr を指定します。設定していないロケールを --locales に指定すると、有効なロケールと並べても終了コード 2 で終了します。そのため、タイプミスでゲートが通ってしまうことはありません。

翻訳品質をゲート条件にする

検出する価値があるのは、ドリフトだけではありません。--qa を追加すると、コミット済みのすべての訳文に整合性ゲートとレビューフラグも実行されます。手で編集した値のプレースホルダーやマークアップが壊れている場合や、ICU の複数形の分岐が合っていない場合に、ジョブが失敗します。

verbatra check --qa
  • --strict を追加すると、レビューの警告と欠落している複数形カテゴリでも失敗します。
  • 編集フックでは、verbatra check --file <path> で 1 つのロケールファイルを単独でチェックできます。

品質チェックと単一のファイルを参照してください。GitHub Action では、qa: "true" で同じゲートを実行します。

レビューの判断をゲート条件にする

--require-reviewed を追加すると、機械が書いた訳文のうち、コミット済みの verbatra.provenance.json で承認されていないものがある間は失敗します。このファイルには、レビューキュー(Studio では Review queue)と MCP のレビューツールが書き込みます(Studio でレビューするを参照)。

verbatra check --require-reviewed

こちらも API キーは不要です。報告されるコードについては、レビュー済みの訳文を必須にするを参照してください。

プッシュ時に翻訳する

verbatra translate を実行し、シークレットストアのプロバイダーの API キーを、その手順の環境変数に割り当てます。CLI は API キーを引数で受け取らず、設定ファイルからも読み込みません。各プロバイダーが読み込む API キーの変数は、プロバイダーにあります。

      - run: pnpm exec verbatra translate --json
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  • この手順はロケールファイルをチェックアウトに書き込み、そこで終わります。ファイルをコミットする、または pull request を作成する手順は、自分で追加します。そのジョブにだけ contents: write または pull-requests: write を付与します。
  • 先にプレビューするには、verbatra translate --dry-run または --estimate を実行します。どちらもプロバイダーを呼び出さず、API キーも不要です。実行前に費用を見積もるを参照してください。
  • レート制限のあるプロバイダーでは、--locales を使って 1 つの手順で 1 つのロケールを翻訳します。

doctor で事前チェックする

どちらのジョブの前にも verbatra doctor を置くと、構成が壊れている場合に早い段階で失敗させられます。doctor は、設定ファイル、フォーマット、プロバイダー、API キーの変数、ネットワークポリシー、ソースファイル、ロケールのサポートをチェックします。--live を指定しない限り、プロバイダーを呼び出さず、API キーの値も読み込みません。ただし、API キーの変数が未設定の場合はチェックの失敗として報告します。そのチェックを通す必要があるジョブには、API キーを割り当ててください。

終了コード

分岐の条件にするのは終了コードで、テキストではありません。各コードの意味と例外的なケースは、終了コードと JSON 出力にあります。出力に含まれるエラーコードの説明は、エラーコードにあります。

JSON 出力

--json を指定すると、レコードごとに 1 つのエンベロープ(envelope)が stdout に出力されます。フィールドは終了コードと JSON 出力に、各コマンドの result は、そのコマンドのページにあります。この出力を解析するレシピは、JSON で verbatra をスクリプト化するにあります。

API キーとインストール

  • インストールには pnpm install --frozen-lockfile または npm ci を使います。そうすると、ジョブはパッケージマネージャーのロックファイルに記録された @verbatra/cli のリリースをそのまま実行します。
  • プロバイダーを呼び出さないジョブ(check、diff、report、export、import、extract、pseudo、types、tmx)には、シークレットを渡しません。
  • CI では env: を使います。どのコマンドが .env.local と .env も読み込むかは、環境ファイルにあります。

関連項目

GitHub で編集

このページの内容