crowdin-api-client

Crowdin API クライアント

概要

@crowdin/crowdin-api-client に依存するプロジェクトで、Crowdin API の統合コードを変更する際にこのスキルを使用します。 基本原則は、まずローカルのクライアント型定義を確認し、その後、厳密なモデル型と正しいレスポンスエンベロープの処理を使用して実装することです。

使用する場面

• @crowdin/crowdin-api-client の新しい呼び出し、または変更された呼び出し。
• API クライアントのアップグレード後に発生したコンパイルエラー／型エラー。
• メソッド名、リクエストフィールド、または ResponseList と ResponseObject のどちらを使うべきかが不明な場合。
• アップロード、ファイル翻訳、スクリーンショット、タスク、コメント、文字列、プロジェクトに関するリファクタリング。
• 実行時には動作するものの、型やマッピングに疑問がある場合のレビュー。
• 複数ステップのフロー：ビルドとダウンロード、事前翻訳、ファイルのアップロードまたは更新、文字列へのラベル付けとタスクの作成、TM または用語集のインポート、レポート。呼び出しを記憶に頼って組み立てるのではなく、references/recipes.md を参照してください。

インフラ関連のみで、これらに関係しない変更にはこのスキルを使用しないでください。

必須の事前確認（編集前）

1. まずローカルの型定義を確認します：node_modules/@crowdin/crowdin-api-client/out/<module>/index.d.ts。
2. 使用する API クラスとメソッドの正確な名前を確認します。
3. リクエストモデルの型と必須フィールドを確認します。
4. レスポンスエンベロープを確認します：ResponseList<T> または ResponseObject<T>。

型定義とドキュメントの内容が異なる場合は、記憶に頼ってコードを書かないでください。

クイックリファレンス

シナリオ	推奨パターン
複数モジュールのフロー	new Client(credentials, options) を使い、必要な API を分割代入する
範囲を絞った単一のフロー	直接モジュールの API クラスを使ってもかまいません
コレクション全体の読み取り	.withFetchAll()
一時的なエラー	retryConfig
リクエスト時間の上限設定	{ httpRequestTimeout: 60_000 }
アップロード	uploadStorageApi.addStorage -> sourceFilesApi.createFile
長時間実行される操作（ビルド、事前翻訳、インポート、エクスポート、レポート）	遅延を挟んで対応する check...Status メソッドをポーリングし、finished、failed、または canceled で停止します — レシピ
エラーの分岐	CrowdinError より先に CrowdinValidationError を判定する

基本パターン

初期化

import { Client, Credentials } from '@crowdin/crowdin-api-client';

const credentials: Credentials = {
  token: process.env.CROWDIN_PERSONAL_TOKEN!,
  organization: process.env.CROWDIN_ORGANIZATION, // Crowdin Enterprise only
};

const client = new Client(credentials);

レスポンスエンベロープの処理

const listResponse = await client.tasksApi.withFetchAll().listTasks(projectId, options);
const tasks = listResponse.data.map((entry) => entry.data); // ResponseList<T>

const createResponse = await client.tasksApi.addTask(projectId, request);
const task = createResponse.data; // ResponseObject<T>

型付きリクエストモデル

const request: TasksModel.CreateTaskRequest = {
  title: 'My Task',
  languageId: 'de',
  type: 0,
  fileIds: [12],
};

エラー処理

import { CrowdinError, CrowdinValidationError } from '@crowdin/crowdin-api-client';

try {
  // API call
} catch (error) {
  if (error instanceof CrowdinValidationError) throw error;
  if (error instanceof CrowdinError) throw error;
  throw error;
}

よくある間違い

間違い	修正方法
記憶を頼りにエンドポイントのメソッドを推測する	まずローカルの index.d.ts で確認する
リストレスポンスをオブジェクトレスポンスとして扱う	ResponseList<T> と ResponseObject<T> のどちらかを確認し、それに応じてマッピングする
モデル型を弱めたり、迂回したりする	サービスのシグネチャとフィクスチャで、クライアントの *Model 型を使用する
デフォルトで手動のページネーションループを作る	カスタムのバッチ処理が必要な場合を除き、.withFetchAll() を優先する
ファイルを直接 createFile にアップロードする	先にストレージを作成し、その後 storageId を渡す
すべてのエラーを汎用エラーとして捕捉する	CrowdinValidationError と CrowdinError を明示的に分岐する
ステータスエンドポイントを間隔を置かずにポーリングする、または finished になるまでしか確認しない	チェックの間に待機し、failed と canceled も終了状態として扱います — レシピを参照してください
複数ステップのフローを記憶に頼って組み立てる	references/recipes.md の該当するレシピから始める

検証ゲート

API クライアントの使用方法を変更した後は、次の作業を行います。

1. 現在のプロジェクトで lint と型チェックを実行します。
2. 変更した API フローを対象とするテストを少なくとも 1 つ実行します。
3. 厳密な型付けが原因でテストが失敗した場合は、本番コードの型を緩めずに、フィクスチャ／モデルの型付けを修正します。

レビューチェックリスト

• タスクに適した API モジュールとメソッドを使用していること。
• リクエストモデルが明示され、必須フィールドを含んでいること。
• レスポンスのマッピングがエンベロープの構造に合っていること。
• モデルの契約を回避せずに、型安全性が保たれていること。
• ページネーションの方法が想定されるデータ量に合っていること。
• リトライ／タイムアウト／ランタイムのオプションが環境に適していること。
• エラーハンドリングで、バリデーションエラーと一般的な API エラーを区別していること。

参考ドキュメント：Crowdin API Client モジュール · API のレシピ