# General Translation Platform: setupProject
URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class-methods/translation/setup-project.mdx
---

title: setupProject
description: 为项目翻译工作流准备已上传的文件。setupProject 的 API 参考。

---

使用此前通过 General Translation 上传的文件，初始化翻译项目的 setup 流程。它会创建一个异步 初始化作业，分析这些文件，并将其准备好用于翻译工作流。

## 概览 [#overview]

调用 `setupProject`，传入来自 [`uploadSourceFiles`](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files) 的文件引用，也可选择传入 setup 选项。它要么会将一个 初始化作业 加入队列 (返回 `setupJobId`) ，要么提示该项目已完成 setup。

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

const setupResult = await gt.setupProject(fileRefs, { timeoutMs: 30000 });
if (setupResult.status === 'queued') {
  console.log(`Setup job created: ${setupResult.setupJobId}`);
} else {
  console.log('Project is already set up');
}
```

签名：

```typescript
setupProject(
  files: FileReference[],
  options?: SetupProjectOptions
): Promise<SetupProjectResult>
```

*注意：`setupProject` 要求 GT 实例中提供 `apiKey` (或 `devApiKey`) 和 `projectId`。你必须先使用 [`uploadSourceFiles`](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files) 上传这些文件。*

## 工作方式 [#how-it-works]

* **文件分析。** 初始化 会分析文件内容和结构，以优化翻译流程。
* **异步任务。** 初始化作业 会异步运行——可使用 [`checkJobStatus`](/docs/platform/core/reference/gt-class-methods/translation/check-job-status) 监控进度。
* **何时需要。** 对于新 Project，通常需要先完成 初始化，然后才能将翻译任务加入队列。
* **版本控制。** 文件引用包含 `branchId`，以支持基于 branch 的版本控制。

## 参数 [#parameters]

| 参数                    | 描述             | 类型                    | 可选 | 默认值 |
| --------------------- | -------------- | --------------------- | -- | --- |
| [`files`](#files)     | 对之前已上传的源文件的引用。 | `FileReference[]`     | 否  | —   |
| [`options`](#options) | 初始化作业 的配置。 | `SetupProjectOptions` | 是  | —   |

### `files` [#files]

**类型** `FileReference[]` · **必填**

[`uploadSourceFiles`](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files) 返回的文件引用：

```typescript
type FileReference = {
  fileId: string;
  versionId: string;
  branchId: string;
  fileName: string;
  fileFormat: FileFormat;
  transformFormat?: FileFormat; // 生成翻译时所请求的输出格式
  dataFormat?: DataFormat;
};
```

`FileReference` 上的 `fileName` 和 `fileFormat` 均为必填项；`transformFormat` 和 `dataFormat` 为可选项。

### `options` [#options]

**类型** `SetupProjectOptions` · **可选**

| 字段          | 描述                     | 类型         | 可选 |
| ----------- | ---------------------- | ---------- | -- |
| `force`     | 通过使现有缓存的翻译失效来强制重新执行设置。 | `boolean`  | 是  |
| `locales`   | 项目的目标 locales。         | `string[]` | 是  |
| `timeoutMs` | API 请求超时时间 (毫秒) 。      | `number`   | 是  |

## 返回值 [#returns]

**类型** `Promise<SetupProjectResult>`

返回一个 `SetupProjectResult`，它是以下两种变体的联合类型：

```typescript
type SetupProjectResult =
  | { setupJobId: string; status: 'queued' }
  | { status: 'completed' };
```

* 创建初始化作业时，会返回带有 `setupJobId` 的 `queued` 变体。
* 当项目已完成初始化时，会返回 `completed` 变体，且不包含作业标识符。

| 属性           | 描述                                              | 类型                        |
| ------------ | ----------------------------------------------- | ------------------------- |
| `setupJobId` | 已排队的初始化作业的唯一标识符。仅在 `queued` 变体中出现。              | `string`                  |
| `status`     | 创建了初始化作业时为 `'queued'`，项目已完成初始化时为 `'completed'`。 | `'queued' \| 'completed'` |

## 示例 [#examples]

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

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

// 来自之前上传的文件引用
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);

if (setupResult.status === 'queued') {
  console.log(`Setup initiated with job ID: ${setupResult.setupJobId}`);

  // 监控任务状态（checkJobStatus 返回一个扁平数组）
  const jobStatus = await gt.checkJobStatus([setupResult.setupJobId]);
  console.log(`Job status: ${jobStatus[0].status}`);
} else {
  console.log('Project is already set up — no setup job needed');
}
```

## 注意事项 [#notes]

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