# General Translation Platform: uploadSourceFiles
URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class-methods/translation/upload-source-files.mdx
---

title: uploadSourceFiles
description: 在将翻译加入队列之前，先将源文件上传到项目。uploadSourceFiles 的 API 参考。

---

将源文件上传到 General Translation platform 进行翻译处理。这通常是文件翻译工作流的第一步，需先完成这一步，再设置项目或将翻译任务加入队列。

## 概览 [#overview]

调用 `uploadSourceFiles`，传入文件数组以及用于设置源区域设置的选项对象。该方法会返回已上传的文件引用，供你在后续步骤中使用。

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

const result = await gt.uploadSourceFiles(files, {
  sourceLocale: 'en',
});
```

签名：

```typescript
uploadSourceFiles(
  files: { source: FileUpload }[],
  options: UploadFilesOptions
): Promise<UploadFilesResponse>
```

*注意：`uploadSourceFiles` 要求在 GT 实例上配置 `apiKey` (或 `devApiKey`) 和 `projectId`。*

## 工作原理 [#how-it-works]

* **文件编码。** 文件内容会自动进行 Base64 编码，以确保传输安全。
* **文件引用。** 返回的文件引用 (包括 `fileId`、`versionId` 和 `branchId`) 是后续操作的必需输入。
* **典型工作流。** `uploadSourceFiles` 是文件流水线的入口文件：先上传源文件，然后依次执行 [`setupProject`](/docs/platform/core/reference/gt-class-methods/translation/setup-project) → [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files) → [`queryFileData`](/docs/platform/core/reference/gt-class-methods/translation/query-file-data) → [`downloadFileBatch`](/docs/platform/core/reference/gt-class-methods/translation/download-file-batch)。

## 参数 [#parameters]

| 参数                    | 描述         | 类型                         | 可选 | 默认值 |
| --------------------- | ---------- | -------------------------- | -- | --- |
| [`files`](#files)     | 要上传的源文件数组。 | `{ source: FileUpload }[]` | 否  | —   |
| [`options`](#options) | 上传配置选项。    | `UploadFilesOptions`       | 否  | —   |

### `files` [#files]

**类型** `{ source: FileUpload }[]` · **必填**

要上传的源文件。每个条目都会在 `source` 键下封装一个 `FileUpload`：

| 字段                | 描述                                                                                                      | 类型                                                              | 可选 |
| ----------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | -- |
| `content`         | 作为字符串的原始文件内容。                                                                                           | `string`                                                        | 否  |
| `fileName`        | 唯一的文件标识符，通常是文件路径加文件名。                                                                                   | `string`                                                        | 否  |
| `fileFormat`      | 文件格式。可为 `GTJSON`、`JSON`、`PO`、`POT`、`YAML`、`MDX`、`MD`、`TS`、`JS`、`HTML`、`TXT` 或 `TWILIO_CONTENT_JSON` 之一。 | `FileFormat`                                                    | 否  |
| `transformFormat` | 生成译文所需的输出格式。                                                                                            | `FileFormat`                                                    | 是  |
| `dataFormat`      | 文件内数据的格式 (ICU、I18NEXT、JSX) 。                                                                            | [`DataFormat`](/docs/platform/core/reference/types/data-format) | 是  |
| `locale`          | 源文件内容的区域设置。                                                                                             | `string`                                                        | 否  |
| `branchId`        | 文件要上传到的分支。省略时使用默认分支。                                                                                    | `string`                                                        | 是  |
| `versionId`       | 版本 ID，用于高级用例。                                                                                           | `string`                                                        | 是  |
| `fileId`          | 文件 ID，用于高级用例。                                                                                           | `string`                                                        | 是  |

### `options` [#options]

**类型** `UploadFilesOptions` · **必填**

上传配置如下：

| 字段              | 描述                   | 类型       | 可选 |
| --------------- | -------------------- | -------- | -- |
| `sourceLocale`  | 所有上传文件的 源区域设置。 | `string` | 否  |
| `modelProvider` | AI 模型 provider 偏好设置。 | `string` | 是  |
| `timeout`       | 请求超时时间 (以毫秒为单位) 。    | `number` | 是  |

*注意：`branchId` 不是 upload 选项。它是每个文件对象上的字段，而不是 `UploadFilesOptions` 的一部分。*

## 返回值 [#returns]

**类型** `Promise<UploadFilesResponse>`

最终会得到一个 `UploadFilesResponse`，其中包含已上传的文件引用和摘要：

```typescript
type UploadFilesResponse = {
  uploadedFiles: FileReference[]; // 后续操作的引用
  count: number; // 成功上传的文件数量
  message: string; // API 返回的状态消息
};
```

每个 `FileReference` 的结构如下：

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

## 示例 [#examples]

```typescript
// 基本用法：上传 JSON 翻译文件
import { GT } from 'generaltranslation';
import fs from 'fs';

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

const files = [
  {
    source: {
      content: fs.readFileSync('./locales/en/common.json', 'utf8'),
      fileName: 'common.json',
      fileFormat: 'JSON' as const,
      locale: 'en',
    },
  },
  {
    source: {
      content: fs.readFileSync('./locales/en/navigation.json', 'utf8'),
      fileName: 'navigation.json',
      fileFormat: 'JSON' as const,
      locale: 'en',
    },
  },
];

const result = await gt.uploadSourceFiles(files, {
  sourceLocale: 'en',
});

console.log(`Uploaded ${result.count} files`);
result.uploadedFiles.forEach((file) => {
  console.log(`  ${file.fileName}: ${file.fileId} (branch: ${file.branchId})`);
});
```

```typescript
// 显式指定数据格式
const files = [
  {
    source: {
      content: '{"welcome": "Welcome, {name}!"}',
      fileName: 'messages.json',
      fileFormat: 'JSON' as const,
      dataFormat: 'ICU' as const, // ICU 消息格式
      locale: 'en',
    },
  },
  {
    source: {
      content: '{"greeting": "Hello {{name}}"}',
      fileName: 'i18next.json',
      fileFormat: 'JSON' as const,
      dataFormat: 'I18NEXT' as const,
      locale: 'en',
    },
  },
];

const result = await gt.uploadSourceFiles(files, {
  sourceLocale: 'en',
  modelProvider: 'gpt-4',
  timeout: 30000,
});
```

```typescript
// 批量上传并处理错误
import { glob } from 'glob';
import path from 'path';

async function uploadAllJsonFiles() {
  try {
    // 查找所有 JSON 文件
    const jsonPaths = await glob('./locales/en/**/*.json');

    const files = jsonPaths.map((filePath) => ({
      source: {
        content: fs.readFileSync(filePath, 'utf8'),
        fileName: path.relative('./locales/en', filePath),
        fileFormat: 'JSON' as const,
        locale: 'en',
      },
    }));

    console.log(`Uploading ${files.length} files...`);

    const result = await gt.uploadSourceFiles(files, {
      sourceLocale: 'en',
      timeout: 60000, // 大文件上传超时时间为 60 秒
    });

    if (result.count !== files.length) {
      console.warn(`Expected ${files.length} files, but only ${result.count} uploaded`);
    }

    return result.uploadedFiles;
  } catch (error) {
    console.error('Upload failed:', error);
    throw error;
  }
}

const uploadedFiles = await uploadAllJsonFiles();
```

## 注意事项 [#notes]

* 文件内容会自动进行 Base64 编码，以确保传输安全。
* 文件名应作为唯一标识符，通常包含文件路径。
* 每个文件中的 `locale` 字段应与 `sourceLocale` 选项保持一致。
* 对于大文件或文件数量较多的情况，可能需要增大超时值。
* 此方法返回的 文件引用 是后续操作所必需的，并包含用于支持 分支 版本管理的 `branchId`。
* 支持的文件格式包括 `GTJSON`、`JSON`、`PO`、`POT`、`YAML`、`MDX`、`MD`、`TS`、`JS`、`HTML`、`TXT` 和 `TWILIO_CONTENT_JSON` —— 完整列表请参阅 `FileFormat` 类型。