# generaltranslation: General Translation Core SDK: uploadSourceFiles
URL: https://generaltranslation.com/zh/docs/core/class/methods/translation/upload-source-files.mdx
---
title: uploadSourceFiles
description: uploadSourceFiles 方法的 API 参考，用于上传待翻译的源文件
---

## 概述

`uploadSourceFiles` 方法用于将源文件上传到 General Translation 平台进行翻译处理。
这通常是翻译工作流的第一步，在设置项目或将翻译任务加入队列之前执行。

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

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

<Mermaid
  chart="
graph TD;
A[uploadSourceFiles];
B[setupProject];
C[enqueueFiles];
E[queryFileData];
F[downloadFileBatch];
A --> B;
B --> C;
C --> E;
E --> F;
"
/>


## 参考

### 参数

| 名称        | 类型                         | 说明              |
| --------- | -------------------------- | --------------- |
| `files`   | `{ source: FileUpload }[]` | 要 upload 的源文件数组 |
| `options` | `UploadFilesOptions`       | upload 的配置选项    |

#### FileUpload 结构

| 名称            | 类型           | 说明                            |
| ------------- | ------------ | ----------------------------- |
| `content`     | `string`     | 原始文件内容 (字符串)                  |
| `fileName`    | `string`     | 唯一文件标识符 (通常为文件路径 + 文件名)       |
| `fileFormat`  | `FileFormat` | 文件格式 (JSON、MDX、MD、XML 等)      |
| `dataFormat?` | `DataFormat` | 文件内数据的可选格式 (ICU、I18NEXT、JSX)  |
| `locale`      | `string`     | 源文件内容的区域设置                    |
| `versionId?`  | `string`     | 高级用法中可选的版本 ID                 |
| `fileId?`     | `string`     | 高级用法中可选的文件 ID                 |

#### UploadFilesOptions

| 名称               | 类型       | 说明              |
| ---------------- | -------- | --------------- |
| `sourceLocale`   | `string` | 所有上传文件的源区域设置    |
| `branchId?`      | `string` | 可选，指定要上传到的分支 ID |
| `modelProvider?` | `string` | 可选的 AI 模型提供方偏好  |
| `timeout?`       | `number` | 请求超时时间 (毫秒)     |

### 返回值

`Promise<UploadFilesResponse>` - 包含上传结果和文件引用信息。

```typescript
type UploadFilesResponse = {
  uploadedFiles: FileReference[];
  count: number;
  message: string;
}
```

| 属性              | 类型                | 说明                |
| --------------- | ----------------- | ----------------- |
| `uploadedFiles` | `FileReference[]` | 供后续操作使用的已上传文件引用数组 |
| `count`         | `number`          | 成功上传的文件数          |
| `message`       | `string`          | API 返回的状态消息       |


#### FileReference 的结构

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

***


## 示例

### 基本用法

上传 JSON 翻译文件：

```typescript copy
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 copy
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 copy
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(`正在上传 ${files.length} 个文件...`);

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

    if (result.count !== files.length) {
      console.warn(`预期上传 ${files.length} 个文件，但实际只上传了 ${result.count} 个`);
    }

    return result.uploadedFiles;

  } catch (error) {
    console.error('上传失败：', error);
    throw error;
  }
}

const uploadedFiles = await uploadAllJsonFiles();
```

***


## 注意事项

* 文件内容会自动进行 Base64 编码，以确保传输安全
* 文件名应作为唯一标识符，通常包含文件路径
* 每个文件中的 `locale` 字段应与 `sourceLocale` 选项一致
* 大文件或文件数量较多时，可能需要增大超时值
* 此方法返回的文件引用是后续操作所必需的
* 文件引用包含 `branchId`，以便在启用分支支持时正确进行版本管理
* 支持的文件格式包括 JSON、MD、MDX、XML 等；完整列表请参见 `FileFormat` 类型

## 后续步骤

* 请参阅 [`setupProject`](/docs/core/class/methods/translation/setup-project)，准备已上传的文件以供翻译
* 请参阅 [`enqueueFiles`](/docs/core/class/methods/translation/enqueue-files)，启动翻译任务
* 请参阅 [`uploadTranslations`](/docs/core/class/methods/translation/upload-translations)，上传已有翻译
* 有关文件结构的详细说明，请参阅 `FileUpload`