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 时停止 — 食谱
错误分支处理	先判断 CrowdinValidationError，再判断 CrowdinError

核心模式

初始化

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 工作流的测试。
3. 如果测试因严格类型检查失败，请修正测试数据或模型类型，而不要放宽生产代码的类型约束。

审查清单

• 任务使用了正确的 API 模块和方法。
• 请求模型明确，并包含必需字段。
• 响应映射与封装结构一致。
• 保留类型安全，且不绕过模型契约。
• 分页策略符合预期数据量。
• 重试、超时和运行时选项适合当前环境。
• 错误处理能够区分验证错误和一般 API 错误。

参考文档：Crowdin API 客户端模块 · API 用法示例