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

title: uploadTranslations
description: 上传与源文件对应的现有翻译后的文件。uploadTranslations 的 API 参考。

---

上传与先前已上传源文件对应的 translation files。若你已经有现成的翻译——例如要迁移已有翻译，或上传经过人工审核的译文——可配合 General Translation 使用此功能，而不是通过翻译服务生成这些翻译。

## 概览 [#overview]

调用 `uploadTranslations` 时，传入一个包含翻译上传项的数组和一个选项对象。每个上传项都引用一个现有的源文件，并包含一个或多个翻译后的文件。

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

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

签名：

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

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

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

* **源文件引用。** 每个条目中的 `source` 对象都是对已上传源文件的引用；无需提供其内容。
* **翻译内容。** `translations` 数组中的每一项都必须包含内容和目标区域设置。
* **版本控制。** 返回的文件引用包含 `branchId`，可在支持 branch 的情况下用于版本控制。

## 参数 [#parameters]

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

### `files` [#files]

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

每个条目都将一个源文件引用与其对应的翻译后的文件关联起来：

```typescript
{
  source: FileUpload; // 引用已存在的源文件（无需提供内容）
  translations: FileUpload[]; // 包含内容的翻译后的文件
}
```

`source` 引用 (一个 `FileUpload`) 包含以下字段：

| Field        | Description                                                                                              | Type         | Optional |
| ------------ | -------------------------------------------------------------------------------------------------------- | ------------ | -------- |
| `fileName`   | 与之前上传的源文件匹配的文件名。                                                                                         | `string`     | 否        |
| `fileFormat` | 文件格式。可以是 `GTJSON`、`JSON`、`PO`、`POT`、`YAML`、`MDX`、`MD`、`TS`、`JS`、`HTML`、`TXT` 或 `TWILIO_CONTENT_JSON` 之一。 | `FileFormat` | 否        |
| `fileId`     | 源文件的文件 ID。                                                                                               | `string`     | 是        |
| `versionId`  | 源文件的版本 ID。                                                                                               | `string`     | 是        |

每个译文 (一个 `FileUpload`) 包含以下字段：

| Field        | Description                                                                                              | Type         | Optional |
| ------------ | -------------------------------------------------------------------------------------------------------- | ------------ | -------- |
| `content`    | 字符串形式的原始译文文件内容。                                                                                          | `string`     | 否        |
| `fileName`   | 译文的文件名。                                                                                                  | `string`     | 否        |
| `fileFormat` | 文件格式。可以是 `GTJSON`、`JSON`、`PO`、`POT`、`YAML`、`MDX`、`MD`、`TS`、`JS`、`HTML`、`TXT` 或 `TWILIO_CONTENT_JSON` 之一。 | `FileFormat` | 否        |
| `locale`     | 译文的目标区域设置。                                                                                               | `string`     | 否        |
| `fileId`     | 文件 ID。                                                                                                   | `string`     | 是        |
| `versionId`  | 版本 ID。                                                                                                   | `string`     | 是        |

### `options` [#options]

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

上传配置：

| 字段              | 描述            | 类型       | 可选 |
| --------------- | ------------- | -------- | -- |
| `sourceLocale`  | 文件的源区域设置。     | `string` | 否  |
| `modelProvider` | AI 模型提供商偏好。   | `string` | 是  |
| `timeout`       | 请求超时时间 (毫秒) 。 | `number` | 是  |

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

## 返回 [#returns]

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

会解析为一个 `UploadFilesResponse`，其中包含已上传的文件引用和摘要：

```typescript
type UploadFilesResponse = {
  uploadedFiles: FileReference[]; // 已上传的文件引用
  count: number; // 成功上传的文件数量
  message: string; // 来自 API 的状态消息
};
```

## 示例 [#examples]

```typescript
// 基本用法：为之前已上传的源文件上传翻译
import { GT } from 'generaltranslation';
import fs from 'fs';

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

// 假设源文件已提前上传
const files = [
  {
    source: {
      fileName: 'common.json',
      fileFormat: 'JSON' as const,
      fileId: 'source-file-id',
      versionId: 'source-version-id',
    },
    translations: [
      {
        content: fs.readFileSync('./locales/es/common.json', 'utf8'),
        fileName: 'common.json',
        fileFormat: 'JSON' as const,
        locale: 'es',
      },
      {
        content: fs.readFileSync('./locales/fr/common.json', 'utf8'),
        fileName: 'common.json',
        fileFormat: 'JSON' as const,
        locale: 'fr',
      },
    ],
  },
];

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

console.log(`Uploaded ${result.count} translation files`);
```

```typescript
// 完整工作流：上传源文件，然后上传对应的翻译
import { GT } from 'generaltranslation';
import fs from 'fs';

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

// 步骤 1：上传源文件
const sourceFiles = [
  {
    source: {
      content: fs.readFileSync('./locales/en/messages.json', 'utf8'),
      fileName: 'messages.json',
      fileFormat: 'JSON' as const,
      locale: 'en',
    },
  },
];

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

// 步骤 2：上传现有翻译
const translationFiles = [
  {
    source: {
      fileName: uploadedFiles[0].fileName,
      fileFormat: uploadedFiles[0].fileFormat,
      fileId: uploadedFiles[0].fileId,
      versionId: uploadedFiles[0].versionId,
    },
    translations: [
      {
        content: fs.readFileSync('./locales/es/messages.json', 'utf8'),
        fileName: 'messages.json',
        fileFormat: 'JSON' as const,
        locale: 'es',
      },
      {
        content: fs.readFileSync('./locales/de/messages.json', 'utf8'),
        fileName: 'messages.json',
        fileFormat: 'JSON' as const,
        locale: 'de',
      },
    ],
  },
];

const translationResult = await gt.uploadTranslations(translationFiles, {
  sourceLocale: 'en',
});

console.log(`Uploaded ${translationResult.count} translations`);
```

```typescript
// 批量上传多个源文件的翻译
import { glob } from 'glob';
import path from 'path';

async function uploadAllTranslations(
  sourceRefs: FileReference[],
  targetLocales: string[]
) {
  const files = sourceRefs.map((sourceRef) => ({
    source: {
      fileName: sourceRef.fileName,
      fileFormat: sourceRef.fileFormat,
      fileId: sourceRef.fileId,
      versionId: sourceRef.versionId,
    },
    translations: targetLocales
      .map((locale) => {
        const translationPath = `./locales/${locale}/${sourceRef.fileName}`;
        try {
          return {
            content: fs.readFileSync(translationPath, 'utf8'),
            fileName: sourceRef.fileName,
            fileFormat: sourceRef.fileFormat,
            locale,
          };
        } catch {
          // 该区域设置不存在对应的翻译文件
          return null;
        }
      })
      .filter(Boolean),
  }));

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

  return result;
}
```

## 注意事项 [#notes]

* 必须先使用 [`uploadSourceFiles`](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files) 上传源文件。
* 每个 `entry` 中的 `source` 对象都会引用一个现有的源文件——此处不需要内容。
* `translations` array 中的每条翻译都必须包含内容和目标区域设置。
* 此方法适用于迁移现有翻译，或上传经过人工审核的翻译。
* file references 包含 `branchId`，用于支持 branch 的版本控制。