# generaltranslation: General Translation Core SDK: setupProject
URL: https://generaltranslation.com/zh/docs/core/class/methods/translation/setup-project.mdx
---
title: setupProject
description: 用于初始化翻译项目设置的 setupProject 方法 API 参考
---

## 概述

`setupProject` 方法会使用之前上传的文件，初始化翻译项目的设置流程。
这会创建一个异步设置任务，用于分析这些文件并为后续翻译工作流做好准备。

```typescript
const gt = new GT({ projectId: 'your-project-id', apiKey: 'your-api-key' });

const setupResult = await gt.setupProject(fileRefs, { timeout: 30000 });
console.log(`Setup job created: ${setupResult.jobId}`);
```

<Callout type="info">
  调用 `setupProject` 之前，你必须先使用 [`uploadSourceFiles`](/docs/core/class/methods/translation/upload-source-files) 上传这些文件。
</Callout>


## 参考

### 参数

| 名称         | 类型                    | 描述               |
| ---------- | --------------------- | ---------------- |
| `files`    | `FileReference[]`     | 由先前上传的源文件引用组成的数组 |
| `options?` | `SetupProjectOptions` | 设置任务的可选设置    |

#### FileReference 结构

```typescript
type FileReference = {
  fileId: string;
  versionId: string;
  branchId: string;
  fileName: string;
  fileFormat?: FileFormat;
  dataFormat?: DataFormat;
}
```


#### SetupProjectOptions

| 名称         | 类型         | 描述                  |
| ---------- | ---------- | ------------------- |
| `locales?` | `string[]` | 可选的目标区域设置数组         |
| `timeout?` | `number`   | API 请求的可选超时时间 (毫秒)  |

### 返回值

`Promise<SetupProjectResult>` - 包含设置任务标识符和初始状态。

```typescript
type SetupProjectResult = {
  jobId: string;
  status: 'queued';
}
```

| 属性       | 类型         | 描述             |
| -------- | ---------- | -------------- |
| `jobId`  | `string`   | 设置任务的唯一标识符 |
| `status` | `'queued'` | 设置任务的初始状态  |

***


## 示例

### 基本用法

使用已上传的文件进行项目设置：

```typescript title="index.ts" copy
import { GT } from 'generaltranslation';

const gt = new GT({
  projectId: 'your-project-id',
  apiKey: 'your-api-key'
});

// 来自上次 upload 的文件引用
const fileRefs = [
  {
    fileId: 'file-123',
    versionId: 'version-456',
    branchId: 'branch-789',
    fileName: 'app.json',
    fileFormat: 'JSON'
  },
  {
    fileId: 'file-789',
    versionId: 'version-012',
    branchId: 'branch-789',
    fileName: 'content.md',
    fileFormat: 'MD'
  }
];

const setupResult = await gt.setupProject(fileRefs);
console.log(`Setup 已启动，任务 ID：${setupResult.jobId}`);

// 监控任务状态
const jobStatus = await gt.checkJobStatus([setupResult.jobId]);
console.log(`任务状态：${jobStatus.jobs[0].status}`);
```

***


## 注意事项

* 调用 `setupProject` 之前，必须先使用 [`uploadSourceFiles`](/docs/core/class/methods/translation/upload-source-files) 上传文件
* 项目设置过程会分析文件内容和结构，以优化翻译工作流
* 设置任务会异步运行——请使用 [`checkJobStatus`](/docs/core/class/methods/translation/check-job-status) 监控进度
* 对于新项目，通常需要先完成设置，然后才能将翻译任务加入队列
* 文件引用包含 `branchId`，以便在支持 branch 的情况下正确进行版本控制

## 后续步骤

* 如需在设置前上传文件，请参阅 [`uploadSourceFiles`](/docs/core/class/methods/translation/upload-source-files)
* 如需监控设置进度，请参阅 [`checkJobStatus`](/docs/core/class/methods/translation/check-job-status)
* 如需在设置完成后开始翻译，请参阅 [`enqueueFiles`](/docs/core/class/methods/translation/enqueue-files)