crowdin-cli

Crowdin CLI

Crowdin CLI は、Crowdin プロジェクトのローカライズリソースを管理、同期するためのコマンドラインツールです。単体で動作するバイナリとして提供され、Java などのランタイムは必要ありません。

crowdin --version を実行して、インストールされているバージョンを確認してください。4.x または Java に関するエラーが表示された場合、レガシー CLI を使用しています。以下のコマンドはほとんどそのまま使えますが、違いについては references/migrating-from-v4.md を参照してください。

ドキュメント全文：https://crowdin.github.io/crowdin-cli

インストール

npm install -g @crowdin/cli

Homebrew（brew tap crowdin/crowdin && brew install crowdin@5）、WinGet、Chocolatey、Docker（crowdin/cli）、Linux のパッケージリポジトリ、スタンドアロンバイナリでも利用できます。すべての方法については、references/configuration.md を参照してください。

認証

CLI には API トークン と（ほとんどのコマンドで）プロジェクト ID が必要です。開発者のマシンで最も手早く設定するには、次のようにします。

crowdin login

ブラウザーで認証し、トークンを ID ファイル ~/.crowdin.yml に保存します。以降のコマンドでは、ユーザーまたはエージェントのどちらが実行しても、このトークンが使われます。設定ファイルは生成も必須でもありません。また、Crowdin Enterprise で追加設定は不要です。組織はサインイン中のアカウントから取得されます。crowdin init は同じブラウザー認証を実行した後、crowdin.yml を生成します。login は、設定を手動で記述する場合や、すでに設定ファイルがある場合に使用します。この処理は同じマシン上のブラウザーコールバックを通じて完了するため、エージェントのシェルが別の場所にある場合は、ユーザー自身のターミナルで実行してください。ブラウザーで発行されたトークンは30日後に期限切れになるため、コマンドが 101 で終了した場合は crowdin login を再実行してください。詳細は references/commands.md を参照してください。

CI や長期間使用するものには、期限切れにならない 個人アクセストークン を使用してください。

• crowdin.com：Settings → API（https://crowdin.com/settings#api-key）でトークンを作成します。base_url は https://api.crowdin.com（デフォルト）です。設定する必要はありません。
• Crowdin Enterprise：Account Settings → Access Tokens でトークンを作成します。base_url は https://{organization}.api.crowdin.com に設定する必要があります。

プロジェクト ID は数値です。トークンを設定したら crowdin project list で取得するか、Crowdin のプロジェクトページで確認してください。crowdin.yml に project_id がなく、project list だけを実行する場合は -i 1 が必要です。このコマンドはプロジェクト ID を無視しますが、検証で必須とされるためです。

認証情報は次の優先順位（上ほど優先）で解決されます。

1. CLI フラグ：-T/--token、-i/--project-id、--base-url、--base-path
2. ID ファイル：--identity <path>、または存在する場合は ~/.crowdin.yml / ~/.crowdin.yaml
3. 設定ファイル内の *_env キー（api_token_env: MY_VAR は $MY_VAR を読み込みます）
4. 設定ファイル内のリテラル値のキー（api_token: "..."）
5. CROWDIN_PERSONAL_TOKEN、CROWDIN_PROJECT_ID、CROWDIN_BASE_PATH、CROWDIN_BASE_URL 環境変数

作業ディレクトリ内の .env ファイルは自動的に読み込まれるため、CROWDIN_PERSONAL_TOKEN をそこに記述できます。ファイルをコミットする場合は、実際のトークンを crowdin.yml に絶対に記述しないでください。代わりに api_token_env または CROWDIN_PERSONAL_TOKEN 変数を使用してください。コミット済みの api_token_env とローカルでの crowdin login は共存できます。変数が未設定の場合は何も使われないため、開発者のマシンでは ID ファイルからトークンが取得され、CI では変数から取得されます。

設定 — crowdin.yml

コマンドは現在のディレクトリから crowdin.yml（または crowdin.yaml）を読み込みます。-c/--config <path> で上書きできます。実際の最小構成の例：

"project_id": "123456"
"api_token_env": "CROWDIN_PERSONAL_TOKEN"
"base_path": "."
"preserve_hierarchy": true

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

• source はローカルのソースファイルを指定する glob です（base_path からの相対パス）。translation は、%two_letters_code%、%locale%、%original_file_name%、%original_path%、%file_name% などのプレースホルダーを使用して、エクスポートした翻訳の保存先を指定します。
• preserve_hierarchy: true を指定すると、ローカルのディレクトリ構造が Crowdin に保持されます。指定しない場合、共通の親ディレクトリは取り除かれます。
• ファイルグループごとに files エントリーを1つ指定します。各エントリーには ignore、dest、type、update_option、labels、excluded_target_languages、languages_mapping などを追加できます。

すべてのプレースホルダー、エントリーごとのオプション、言語マッピング、複数のファイルグループを含む完全なリファレンスは、references/configuration.md を参照してください。

最初にアップロードする前に設定を検証し、誤ったアップロードを後からデバッグする事態を避けてください。

crowdin config lint            # validate syntax
crowdin config sources         # list local files matched by each source pattern
crowdin config translations    # list translation paths that will be produced
crowdin upload sources --dryrun

基本的なワークフロー

日常的なサイクルは、ソースをアップロード → 翻訳 → 翻訳をダウンロード、です。

crowdin upload sources           # push local source files (alias: crowdin push)
crowdin status                   # translation & proofreading progress per language
crowdin auto-translate --method tm   # optional: pre-fill via TM, MT, or AI
crowdin download translations    # pull completed translations (alias: crowdin pull)

便利なバリエーション：

crowdin upload sources --cache               # skip unchanged files (checksum cache)
crowdin upload sources --delete-obsolete     # remove files from Crowdin that no longer exist locally
crowdin upload translations                  # import existing local translations
crowdin download translations -l uk -l fr    # only some languages
crowdin download translations --skip-untranslated-strings
crowdin download sources                     # pull sources back from Crowdin

すべての操作でブランチを指定できます。-b <name> を渡すと、アップロード／ダウンロード／ステータス確認の対象を Crowdin ブランチに限定できます（crowdin branch add で作成します）。

auto-translate（v4 では pre-translate）では、TM（--method tm）、機械翻訳（--method mt --engine-id <id>）、または AI（--method ai --ai-prompt <id>。プロンプト ID の一覧は crowdin ai-prompt list --action pre_translate --assigned で表示できます）を適用できます。さらに、--scope untranslated|translated|all、--skip-approved-translations、--label／--exclude-label、--replace-translations-option、--translation-modified-before などで細かく制御できます。詳しくは references/commands.md を参照してください。ジョブの完了まで待機します。--async を指定すると、ジョブ ID がすぐに返されます。後から crowdin auto-translate status <id> [--wait] で確認できます。

Crowdin アプリを介した連携

コンテンツが CMS、マーケティングツール、ヘルプセンター、またはインストール済みの Crowdin アプリを介して接続された別のプラットフォームにある場合、同期には upload／download ではなく、アプリの API メソッド（crowdin app methods、crowdin app api）を使用します。このコマンドラインおよび Crowdin コネクターを介した同期サイクルは、integration-sync スキルで実行します。最初に crowdin app api を呼び出す前に、このスキルを読み込んでください。インポート、ジョブ、プッシュの手順、アプリの ID の渡し方、設定を置き換える呼び出しについて説明しています。

AI 拡張のための文字列コンテキスト

プロジェクトの文字列コンテキストを拡張する（ダウンロードし、ai_context を入力してアップロードする）サイクルについては、context-extraction スキルを参照してください。crowdin context コマンドと JSONL 形式については、references/context.md を参照してください。--status フィルターは「コンテキストが必要」という意味ではありません。

スクリプトとエージェント向けの出力

グローバルな -o/--output オプションを使うと、任意のコマンドの出力形式を変更できます。

• -o json — 機械可読な JSON です。jq にパイプするか、スクリプトで解析できます
• -o toon — Token-Oriented Object Notation です。JSON と同じデータをわずかなサイズで出力します。コンシューマーが LLM の場合はこちらを優先してください
• -o plain — 処理に適した最小限のテキストです（v4 の --plain フラグ）

json モードと toon モードでは、標準出力にはデータのみが出力され、スピナー、色、装飾的なメッセージは含まれないため、安全に解析できます。CLI をエージェントとして実行する場合、読み取るだけのリストには -o toon、スクリプトで結果を解析する必要がある場合は -o json をデフォルトで使用してください。

crowdin file list -o json | jq -r '.[].path'
crowdin status -o toon

終了コードは安定しており、意味が明確です。エラーテキストを解析するのではなく、終了コードに基づいて分岐してください。

コード	意味
0	成功
1	一般エラー
2	検証エラー（設定または引数が不正）
101	認証エラー（トークンが不正または期限切れ）
102	見つかりません
103	アクセス禁止
129	レート制限超過

ファイルを変更するコマンドは、実行内容を事前に確認するための --dryrun を受け付けます。問題の診断時は -v/--verbose を追加してください。CI でログを簡潔にするには --no-progress/--no-colors を使用してください（json/toon モードではこれらが自動的に有効になります）。

コマンド一覧

トップレベルのコマンドは 24 個あり、その大半にはサブコマンドがあります。オプションの詳細を含むリファレンスについては、references/commands.md を参照してください。

コマンド	目的
upload (push)	crowdin.yml に従ってソース／翻訳をアップロード
download (pull)	crowdin.yml に従って翻訳／ソースをダウンロード
init	対話形式で crowdin.yml を生成
login	ブラウザーで認証し、トークンを ~/.crowdin.yml に保存
status	翻訳と校正の進捗状況
auto-translate	TM／MT／AI で翻訳を事前入力（status、list）
file	設定パターンを使わずにファイルを直接操作（list、upload、download、delete）
string	ソース文字列を管理（list、add、edit、delete。CroQL フィルターに対応）
branch	ブランチを管理（add、list、clone、merge、edit、delete）
task	翻訳／校正タスクを作成して一覧表示
tm	翻訳メモリ（list、upload、download。list --assigned でプロジェクトに絞り込み）
glossary	用語集（list、upload、download。list --assigned でプロジェクトに絞り込み）
style-guide	スタイルガイド（list、download、upload、delete）
ai-prompt	AI プロンプト（list。--action pre_translate --assigned で、auto-translate --method ai が受け取る ID を検索）
bundle	エクスポート用バンドル（list、add、download、clone、browse）
distribution	コンテンツ配信（add、list、edit、release）
screenshot	コンテキスト用のスクリーンショット（list、ファイルまたはディレクトリのアップロード、delete）
comment	文字列のコメントと課題（list、add、resolve）
label	ラベル（list、add、delete）
language	プロジェクト／対応言語を一覧表示。--verbose を指定すると、文字方向と複数形カテゴリーも表示
project	プロジェクトを一覧表示、追加、参照
config	設定を検証し、一致するソース／翻訳をプレビュー
app	インストール済みアプリ：一覧表示、インストール、アンインストール、API メソッドの呼び出し（import、push、jobs のループは integration-sync）
context	文字列の AI コンテキスト：ダウンロード、アップロード、適用範囲のステータス確認、リセット。references/context.md を参照

シェル補完：source <(crowdin complete zsh)（bash、fish、powershell にも対応）。

CI/CD

• トークンは CROWDIN_PERSONAL_TOKEN として公開する CI シークレットに保存し、project_id はコミット済みの crowdin.yml に保持します（機密情報ではありません）。
• 一般的なパイプライン：メインブランチへのマージ時に crowdin upload sources を実行し、スケジュールに従って、またはリリース前に crowdin download translations を実行して、更新されたファイルをコミットまたは PR します。
• GitHub Actions では、この CLI をラップする公式の crowdin/github-action を推奨します。詳しくは github-action スキルをご覧ください。
• 必要な値がすべて指定されている場合、CLI はプロンプトを表示しません。値が不足している場合は、待機せずに終了コード 2 で失敗します。
• crowdin status --fail-if-incomplete は、プロジェクトの翻訳が完了していない場合にゼロ以外の値で終了します。すぐに使えるリリースゲートです。

関連スキル

• context-extraction — crowdin context upload が送信する ai_context の値を書き込みます
• croql — 文字列コマンドの --croql フィルターに使う CroQL 式
• crowdin-api-client — CLI コマンドで要件を満たせない場合に使う JS/TS API クライアント
• translate — プロジェクトの用語集、TM、スタイルガイドを使ってローカルのリソースファイルに翻訳案を作成し、提案としてアップロードします