Crowdin API Client

Overview

Use this skill when touching Crowdin API integration code in any project that depends on @crowdin/crowdin-api-client. Core principle: verify local client typings first, then implement with strict model types and correct response envelope handling.

When to Use

• New or changed calls to @crowdin/crowdin-api-client.
• Compile/type errors after API-client upgrades.
• Confusion about method names, request fields, or ResponseList vs ResponseObject.
• Refactors involving uploads, file translations, screenshots, tasks, comments, strings, or projects.
• Reviews where behavior works at runtime but types/mapping look suspicious.

Do not use this skill for unrelated infra-only changes.

Required Preflight (Before Editing)

1. Check local declarations first: node_modules/@crowdin/crowdin-api-client/out/<module>/index.d.ts.
2. Confirm exact API class and method name in use.
3. Confirm request model type and required fields.
4. Confirm response envelope: ResponseList<T> or ResponseObject<T>.

Do not code from memory when typings and docs disagree.

Quick Reference

Core Patterns

Bootstrap

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

const credentials: Credentials = {
  token: process.env.CROWDIN_TOKEN!,
  organization: process.env.CROWDIN_ORG,
};

const client = new Client(credentials);

Response Envelope Handling

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>

Typed Request Models

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

Error Handling

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;
}

Common Mistakes

Verification Gate

After changing API-client usage:

1. Run lint/type checks in the current project.
2. Run at least one targeted test for the modified API flow.
3. If tests fail on strict typing, fix fixture/model typing instead of loosening production types.

Review Checklist

• Correct API module and method for the task.
• Request models are explicit and include required fields.
• Response mapping matches envelope shape.
• Type safety is preserved without bypassing model contracts.
• Pagination strategy matches expected volume.
• Retry/timeout/runtime options fit environment.
• Error handling distinguishes validation from generic API errors.

Reference docs: Crowdin API Client modules