github-action

Crowdin GitHub Action

crowdin/github-action は、Crowdin CLI を Docker コンテナー内で単一のワークフローステップとして実行します。ソースファイルを Crowdin にアップロードし、完成した翻訳をダウンロードしてローカライズブランチにコミットし、プルリクエストを作成します。

Docker アクションであるため、実行できるのは Linux ランナー（ubuntu-latest、または Docker が利用可能なセルフホスト Linux ランナー）のみです。macos-* や windows-* では実行できません。

リファレンス：README · 例 · 入力と出力 · ワークフローのレシピ

このステップはコマンドではなくパイプラインです

1 つのステップで最大 5 つの操作を実行します。実行順序は常に固定されており、それぞれの操作は専用の入力によって制御されます。

順序	入力	実行内容
1	upload_sources: true (デフォルト)	crowdin upload sources
2	upload_translations: true	crowdin upload translations
3	download_sources: true	crowdin download sources、続いてGit 部分
4	download_translations: true	crowdin download、続いてGit 部分
5	download_bundle: <id>	crowdin bundle download <id>、続いてGit 部分

Git 部分は、一連の作業単位です。git add .、コミット、ローカライズブランチへの強制プッシュ、PR の作成を行います。各処理は個別に切り替えられます（push_translations、push_sources、create_pull_request）。この処理に進めるのは 3～5 行目のみです。

この順序を把握しておけば、このアクションで起きる意外な動作のほとんどを説明できます。

• upload_sources のデフォルトは true です。 ダウンロード専用にするつもりのステップでも、upload_sources: false と指定しない限り、ソースが Crowdin にアップロードされます。デフォルトに頼らず、必要なフラグはすべて明示的に設定してください。
• Git 部分はダウンロードの後にのみ実行されます。 アップロード専用のステップで create_pull_request: true を指定しても何も起きません。コミットするものがないためです。
• 1 つのステップで 2 回ダウンロードすると、Git 部分も 2 回実行されます。 同じローカライズブランチに 2 回コミットされ、PR は 1 つ作成されます。
• Git 部分では git add . でコミットします。 それ以前のステップで生成されたファイルを含め、ワークスペース内の変更がすべて追加されます。Crowdin のステップはビルドステップより前に配置するか、専用のジョブに分けてください。
• 変更があるたびに強制プッシュされるため、 開いている翻訳 PR は追記ではなく書き換えられます。そのため、毎回チェックが最初からやり直しになります。

セットアップ

5 つのステップのうち 2 つは人が行う必要があります。ステップ 2 のリポジトリシークレットと、ステップ 4 のプルリクエスト設定は、リポジトリの管理者権限を持つ人が GitHub の UI で設定する必要があります。すでに設定済みだと決めつけず、この作業一覧を明確に共有してください。ディスク上では完璧なワークフローでも、これらが設定されていなければ初回実行に失敗します。

1. crowdin.yml を設定する

このアクションは CLI と同じ crowdin.yml を読み込みます。crowdin-cli スキルでは、files、プレースホルダー、言語マッピングについて説明しています。ここでは、特に重要な項目が 3 つあります。

"project_id_env": "CROWDIN_PROJECT_ID"
"api_token_env": "CROWDIN_PERSONAL_TOKEN"
"preserve_hierarchy": true

files:
  - source: "/src/locales/en/**/*.json"
    translation: "/src/locales/%two_letters_code%/**/%original_file_name%"

• project_id_env / api_token_env は、ワークフローが渡す環境変数を指定するため、認証情報がコミットされることはありません。
• preserve_hierarchy: true を設定すると、Crowdin のファイルツリーをリポジトリと同じ状態に保てます。設定しない場合、Crowdin は共通の親ディレクトリを取り除くため、ダウンロードした翻訳がリポジトリと一致しないパスに配置されます。これが、PR に誤った場所のファイルが大量に含まれる一般的な原因です。また、ネイティブの GitHub（OAuth）連携から移行する際にも必要です。
• ファイルはリポジトリのルートに置くか、config 入力でパスを指定してください（先頭に / は付けません）。

ソースと翻訳のパターンがそれぞれ 1 つだけのリポジトリでは、ファイル全体を省略し、代わりに source と translation を入力として渡せます。詳しくは「crowdin.yml なし」を参照してください。どちらか一方を選んでください。リポジトリ内に crowdin.yml がある場合、これらの入力と競合します。

2. リポジトリのシークレットを作成する

Settings → Secrets and variables → Actions で、以下を追加します。

• CROWDIN_PROJECT_ID — 数値のプロジェクト ID。Crowdin プロジェクトの Tools → API で確認できます。
• CROWDIN_PERSONAL_TOKEN — Crowdin の個人アクセストークン（crowdin.com、または Enterprise の Account Settings → Access Tokens で取得できます）。

トークンのスコープは、ワークフローが実際に行う操作に限定します。通常の同期では、Projects → Read、Translation Status → Read、Source files & strings → Read and Write、Translations → Read and Write が必要です。

3. ワークフローを作成する

.github/workflows/crowdin.yml：

name: Crowdin

on:
  push:
    branches: [ main ]
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

concurrency:
  group: crowdin
  cancel-in-progress: false

jobs:
  synchronize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - name: Synchronize with Crowdin
        uses: crowdin/github-action@v3
        with:
          upload_sources: true
          upload_translations: false
          download_translations: true

          localization_branch_name: l10n_crowdin
          create_pull_request: true
          pull_request_title: 'New Crowdin translations'
          pull_request_base_branch_name: main
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
          CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}

調整する際に留意すべき点：

• 認証情報は with: ではなく env: に設定します。CLI とアクションの git コードは、環境から認証情報を読み取ります。（代替として token と project_id の入力もありますが、with: にトークンを指定すると、ステップのレンダリングされた入力に表示されます。）
• workflow_dispatch を使うと、プッシュを待たずにワークフローをテストできます。
• cancel-in-progress: false を指定した concurrency は、実行を競合させずにキューに入れます。Crowdin が前回のエクスポートをまだ作成中に 2 回目の実行が始まると、409 エラーで失敗します。
• pull_request_base_branch_name は明示的に設定することをおすすめします。未設定の場合、ベースブランチは実行をトリガーした ref になります。これは main へのプッシュでは適切ですが、タグやリリースをトリガーとする場合は問題になります。
• 同期ステップを 1 つにするのが最も簡単ですが、2 つの方向では自然な実行頻度が異なります。main へのプッシュごとにアップロードし、スケジュールに従ってダウンロードします。ワークフローの分割を参照してください。
• actions/checkout@v7 は 2026 年 8 月時点で最新です。古いサンプルからバージョンをコピーするのではなく、リリースを確認してください。

4. トークンに書き込みアクセスを許可する

ブランチをプッシュして PR を作成するには、contents: write と pull-requests: write が必要です。デフォルトの GITHUB_TOKEN を使う場合は、上記のジョブレベルの permissions: ブロックに加えて、リポジトリの設定で Settings → Actions → General → Allow GitHub Actions to create and approve pull requests も有効にする必要があります。この設定がないと、権限が正しく見えても PR の作成に失敗します。

デフォルトのトークンには、権限では解決できない制限が 1 つあります。このトークンで作成したプルリクエストはワークフローをトリガーしないため、翻訳 PR に CI チェックが付きません。PR に対してチェックを実行する必要がある場合は、Actions bot 以外の認証方法を使います。GitHub App（スコープを限定でき、自動ローテーションされるため、よりおすすめです）または repo スコープのクラシック PAT を GH_TOKEN または GITHUB_TOKEN として渡してください。

5. 実行を確認する

YAML が有効なだけでは完了ではありません。このアクションは、認証情報、ファイルパターン、権限に問題があると実行時に失敗します。そのため、ファイルを書いた時点ではなく、実行ログに期待したステージが出力された時点で作業完了です。

1. dryrun_action: true を設定し、ワークフローを手動で実行します。CLI に管理対象となるファイルが表示されるため、誤った source パターンを、Crowdin に何かが送信される前に見つけられます。
2. フラグを外して再度手動実行し、ログの最後まで確認します。UPLOAD SOURCES、続いて DOWNLOAD TRANSLATIONS が表示され、その後に PR の URL または NOTHING TO COMMIT が表示されます。
3. 実行に問題があった場合は、Enable debug logging を有効にして再実行します。このアクションは RUNNER_DEBUG を検出して環境を出力し、すべての CLI 呼び出しに --verbose --debug を追加します。

手動実行にはシークレットを保持する担当者が必要です。ワークフローファイルを確認するだけで終わらせず、実行ログを共有してもらいましょう。

問題が起きる原因と対処法

まずステップのログを確認してください。実行中に UPLOAD SOURCES、DOWNLOAD TRANSLATIONS、PUSH TO BRANCH、NOTHING TO COMMIT、CREATE PULL REQUEST が出力されるため、推測を始める前に失敗したパイプラインの段階を特定できます。

症状	原因	対処法
実行は成功したが PR が作成されず、ログに NOTHING TO COMMIT と表示される	ダウンロードした翻訳がコミット済みの内容とバイト単位で同一です	正常な動作です。対応は不要です
実行は成功したが PR が作成されず、ログにダウンロードの記録がない	download_translations がデフォルト値の false のままです	download_translations: true を設定します
ERROR: Either 'GITHUB_TOKEN' or 'GH_TOKEN' must be set	ステップの env: にトークンがありません	GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} を追加します
FAILED TO AUTHENTICATE WITH GITHUB、またはプッシュ時に 403 が発生する	ジョブに書き込み権限がないか、リポジトリで Actions による PR 作成がブロックされています	permissions: ブロックを追加し、さらにリポジトリの設定を有効にします（手順 4）
PR は作成されるが、CI チェックが実行されない	デフォルトの GITHUB_TOKEN を使った PR ではワークフローがトリガーされません	GitHub App トークンまたは PAT を使います
同期を実行するたびにチェックが再実行される	ローカライズ用ブランチが毎回強制プッシュされています	ユーザーからのプッシュになるよう、PAT を actions/checkout に渡します
タグまたはリリースをトリガーにした場合、PR の作成に失敗する	ベースブランチがトリガーされた ref に設定されますが、その ref は refs/tags/... です	pull_request_base_branch_name を設定します
後続のステップで、ダウンロードしたファイルに対する権限エラーが発生する	コンテナは root として実行されるため、書き込んだファイルの所有者も root になります	ワークスペースの所有者を検出するため、user: auto を追加します
409 / ビルドがすでに進行中	同じ Crowdin プロジェクトに対して実行が並行しています	concurrency を使って直列化するか、マトリックスで max-parallel: 1 を設定します
翻訳 PR にビルド成果物が含まれる	git add . がワークスペース全体をコミットしています	ビルドの前に Crowdin ステップを移動するか、独立したジョブに移します
プロジェクトが文字列ベースのため、何もダウンロードされない	download_translations は文字列ベースのプロジェクトには適用されません	バンドルをダウンロードします：download_bundle: <id>
crowdin.yml が見つからない	アクションはリポジトリのルートを検索します	config: path/to/crowdin.yml を指定します。先頭に / は付けません
Enterprise：CLI から 404 または認証エラーが返される	Enterprise では組織固有の API ホストが必要です	base_url: 'https://{organization}.api.crowdin.com' を指定します

command — 任意の CLI コマンドの実行

command（および省略可能な command_args）を指定すると、ステップは任意の CLI 呼び出しを実行します。status、auto-translate、bundle、string など、CLI がサポートするコマンドを実行できます。

- name: Fail the build unless translations are complete
  uses: crowdin/github-action@v3
  with:
    command: 'status translation'
    command_args: '--fail-if-incomplete'
  env:
    CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
    CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}

実装方法に起因する注意点が 2 つありますが、いずれも上流のドキュメントには記載されていません。

• command はパイプラインを置き換えます。 ステップはコマンドを実行して終了するため、他の入力の指定内容にかかわらず、アップロード、ダウンロード、コミット、PR 作成は行われません。アップロードとダウンロードの間にコマンドを実行するには、ステップを 3 つに分ける必要があります（AI による事前翻訳が代表的な例です）。
• アクションの設定入力は command に渡されません。 config、token、project_id、base_url、base_path、crowdin_branch_name、dryrun_action は command ステップに転送されず、転送されるのは command_args のみです。認証情報は env: で渡し、それ以外は command_args に指定してください（--config path/to/crowdin.yml、--branch main、--dryrun）。

コマンドの標準出力は、後続のステップから command_output 出力として利用できます。

固定するバージョンの選び方

@v3 は現在の安定版の系列で、Crowdin CLI 5 を実行します。

@v2 はレガシー系列で、Java ベースの Crowdin CLI 4 が含まれています。2 つのバージョンでは、すべての入力、出力、デフォルト値が同一です。そのため、パイプライン形式のステップをアップグレードする際は、バージョン指定を 1 行変更するだけで済みます。変わるのは内部で使われる CLI であり、そのため command や *_args に渡す文字列も変わります。特に、v4 の pre-translate は auto-translate に、--plain は -o plain に変わりました。その他の変更については、移行リファレンスを参照してください。command ステップが v4 固有の CLI 構文に依存している間だけ、@v2 を使い続けてください。

関連スキル

• crowdin-cli — crowdin.yml の設定と、すべての入力に関わるコマンドおよびフラグ
• crowdin-api-client — CLI で対応できない自動化向け
• croql — 文字列コマンドの command_args 向け CroQL フィルター