# General Translation Platform: 项目和文件管理
URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class-methods/project/project-management.mdx
---

title: 项目和文件管理
description: 在 GT 实例中管理 General Translation 项目的信息、分支、文件移动、CDN 发布和编辑差异。项目和文件管理相关方法的 API 参考。

---

[GT](/docs/platform/core/reference/gt-class/constructor) 实例上用于管理项目元数据、分支、文件生命周期和编辑历史的底层方法。这些方法主要供 [CLI](/docs/cli/quickstart) 等工具使用；大多数应用则会改用更高层的[翻译方法](/docs/platform/core/reference/gt-class-methods/translation/translate)。

*注意：本页中的每个方法都会调用 General Translation API，并且要求在 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上配置 API 密钥。参数中的区域设置代码会在请求前标准化为其规范形式。*

| 方法                                      | 描述                               | 返回值                               |
| --------------------------------------- | -------------------------------- | --------------------------------- |
| [`getProjectInfo`](#get-project-info)   | 获取当前已认证项目的名称、区域设置和审核设置。          | `Promise<ProjectInfoResult>`      |
| [`queryBranchData`](#query-branch-data) | 按名称查找分支 ID。                      | `Promise<BranchDataResult>`       |
| [`createBranch`](#create-branch)        | 创建分支 (或返回现有分支) 。                 | `Promise<CreateBranchResult>`     |
| [`getOrphanedFiles`](#orphaned-files)   | 查找某个分支上已不再存在于本地文件集中的文件。          | `Promise<GetOrphanedFilesResult>` |
| [`processFileMoves`](#process-moves)    | 在文件移动或重命名后，使用新的文件 ID 克隆源文件和翻译内容。 | `Promise<ProcessMovesResponse>`   |
| [`publishFiles`](#publish-files)        | 在 CDN 上发布或取消发布文件。                | `Promise<PublishFilesResult>`     |
| [`submitUserEditDiffs`](#edit-diffs)    | 提交用户编辑差异，以便后续生成时保留原意。            | `Promise<void>`                   |

## `getProjectInfo` [#get-project-info]

获取已认证项目的元数据，包括其名称、组织、默认和当前区域设置，以及审核设置。

```typescript
getProjectInfo(options?: { timeout?: number }): Promise<ProjectInfoResult>
```

* **`options.timeout`** — 可选的请求超时时间，单位为毫秒。

返回一个 `ProjectInfoResult`：

| Field            | Description          | Type                 |
| ---------------- | -------------------- | -------------------- |
| `id`             | 项目 ID。               | `string`             |
| `name`           | 项目名称。                | `string`             |
| `orgId`          | Organization ID。     | `string`             |
| `defaultLocale`  | 项目的默认 (source) 区域设置。 | `string`             |
| `currentLocales` | 项目已配置的目标区域设置。        | `string[]`           |
| `autoApprove`    | 翻译是否会在未经过审核的情况下自动批准。 | `boolean` (optional) |

```typescript
const info = await gt.getProjectInfo();
console.log(info.defaultLocale, info.currentLocales);
```

## `queryBranchData` [#query-branch-data]

将分支名称解析为对应的分支记录，并返回项目的默认分支。

```typescript
queryBranchData(query: { branchNames: string[] }): Promise<BranchDataResult>
```

* **`query.branchNames`** — 要查找的 分支 名称。

返回一个 `BranchDataResult`，其中包含 `branches` (`{ id, name }[]`) 和 `defaultBranch` (`{ id, name }` 或 `null`) 。

```typescript
const { branches, defaultBranch } = await gt.queryBranchData({
  branchNames: ['main'],
});
```

## `createBranch` [#create-branch]

创建一个分支；如果已存在同名分支，则返回该分支。

```typescript
createBranch(query: {
  branchName: string;
  defaultBranch: boolean;
}): Promise<CreateBranchResult>
```

* **`query.branchName`** — 要创建的分支名称。
* **`query.defaultBranch`** — 该分支是否为此项目的默认分支。

返回一个 `CreateBranchResult`，其中包含新创建的 `branch` (`{ id, name }`) 。

```typescript
const { branch } = await gt.createBranch({
  branchName: 'feature/new-copy',
  defaultBranch: false,
});
```

## `getOrphanedFiles` [#orphaned-files]

返回存在于某个 分支 上、但文件 ID 不在所提供列表中的文件——这些文件很可能已在本地被移动、重命名或删除。用于检测移动。

```typescript
getOrphanedFiles(
  branchId: string,
  fileIds: string[],
  options?: { timeout?: number }
): Promise<GetOrphanedFilesResult>
```

* **`branchId`** — 要检查的分支。
* **`fileIds`** — 当前的文件 ID (非孤立) 。
* **`options.timeout`** — 可选的请求超时时间 (毫秒) 。

返回包含 `orphanedFiles` (`{ fileId, versionId, fileName }[]`) 的 `GetOrphanedFilesResult`。较长的 `fileIds` 列表会自动分批处理；只有当某个文件在所有批次中都不存在时，才会被报告为孤立文件。

## `processFileMoves` [#process-moves]

通过在新的文件 ID 下克隆源文件及其译文，在文件被移动或重命名时保留翻译内容。

```typescript
processFileMoves(
  moves: MoveMapping[],
  options?: { branchId?: string; timeout?: number }
): Promise<ProcessMovesResponse>
```

* **`moves`** — 由 `{ oldFileId, newFileId, newFileName }` 映射组成的数组。
* **`options.branchId`** — 这些移动操作所属的 分支。
* **`options.timeout`** — 可选的请求超时时间，单位为毫秒。

返回一个 `ProcessMovesResponse`，其中包含每次移动操作的 `results` 和一个 `summary` (`{ total, succeeded, failed }`) 。这些移动操作会自动进行批处理。

```typescript
const result = await gt.processFileMoves(
  [{ oldFileId: 'abc123', newFileId: 'def456', newFileName: 'locales/en.json' }],
  { branchId: 'main' }
);
```

## `publishFiles` [#publish-files]

在 CDN 上发布或取消发布源文件和译文。

```typescript
publishFiles(files: PublishFileEntry[]): Promise<PublishFilesResult>
```

每个条目都是一个 `PublishFileEntry`：

| 字段          | 说明                          | 类型        | 可选 |
| ----------- | --------------------------- | --------- | -- |
| `fileId`    | 要发布或取消发布的文件。                | `string`  | 否  |
| `versionId` | 文件版本。                       | `string`  | 否  |
| `publish`   | `true` 表示发布，`false` 表示取消发布。 | `boolean` | 否  |
| `branchId`  | 文件所属的分支。                    | `string`  | 是  |
| `fileName`  | 文件名。                        | `string`  | 是  |

返回一个 `PublishFilesResult`，其中包含按文件分别给出的 `results` (`{ fileId, versionId, branchId, success, locale?, error? }`) 。结果中的 `locale` 表示该项是译文；如果没有，则表示源文件。

## `submitUserEditDiffs` [#edit-diffs]

提交用户对现有翻译的修改，以便后续生成时保留用户原意。

```typescript
submitUserEditDiffs(payload: {
  diffs: SubmitUserEditDiff[];
}): Promise<void>
```

每个 `SubmitUserEditDiff` 都包含 `fileName`、`locale`、`diff`、`branchId`、`versionId`、`fileId` 和 `localContent`。提交前会先将区域设置标准化为规范形式，并自动将差异按批处理。提交成功后，此操作会完成。