# generaltranslation: General Translation Core SDK: uploadTranslations
URL: https://generaltranslation.com/zh/docs/core/class/methods/translation/upload-translations.mdx
---
title: uploadTranslations
description: 用于上传现有翻译文件的 uploadTranslations 方法 API 参考
---

## 概述

`uploadTranslations` 方法用于上传与此前已上传的源文件相对应的翻译文件。
如果你已有现成的译文，希望直接上传，而不是通过翻译服务生成，这个方法就很有用。

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

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

<Callout type="info">
  在上传译文之前，您必须先使用 [`uploadSourceFiles`](/docs/core/class/methods/translation/upload-source-files) 上传过源文件。
</Callout>


## 参考

### 参数

| 名称        | 类型                    | 说明             |
| --------- | --------------------- | -------------- |
| `files`   | `TranslationUpload[]` | 源文件引用及其翻译组成的数组 |
| `options` | `UploadFilesOptions`  | upload 的配置选项   |

#### TranslationUpload 结构

```typescript
type TranslationUpload = {
  source: FileUpload;      // 引用现有源文件（无需提供内容）
  translations: FileUpload[]; // 包含内容的已翻译文件数组
}
```


#### FileUpload 结构 (用于引用源文件) 

| 名称           | 类型           | 说明                        |
| ------------ | ------------ | ------------------------- |
| `fileName`   | `string`     | 与先前上传的源文件对应的文件名           |
| `fileFormat` | `FileFormat` | 文件格式 (JSON、MDX、MD、XML 等)  |
| `fileId?`    | `string`     | 源文件的可选文件 ID               |
| `versionId?` | `string`     | 源文件的可选版本 ID               |

#### FileUpload 结构 (用于翻译) 

| 名称           | 类型           | 说明                        |
| ------------ | ------------ | ------------------------- |
| `content`    | `string`     | 翻译后文件的原始内容，以字符串形式表示       |
| `fileName`   | `string`     | 译文文件的文件名                  |
| `fileFormat` | `FileFormat` | 文件格式 (JSON、MDX、MD、XML 等)  |
| `locale`     | `string`     | 翻译的目标区域设置                 |
| `fileId?`    | `string`     | 可选的文件 ID                  |
| `versionId?` | `string`     | 可选的版本 ID                  |

#### UploadFilesOptions

| 名称             | 类型       | 描述                 |
| -------------- | -------- | ------------------ |
| `sourceLocale` | `string` | 这些文件的源区域设置         |
| `branchId?`    | `string` | 要 upload 到的可选分支 ID |
| `timeout?`     | `number` | 请求超时时间 (毫秒)        |

### 返回值

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

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

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

***


## 示例

### 基本用法

为先前上传的源文件上传译文：

```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: {
      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 copy
import { GT } from 'generaltranslation';
import fs from 'fs';

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

// 第一步：上传源文件
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'
});

// 第二步：上传现有译文
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(`已上传 ${translationResult.count} 个译文`);
```


### 批量上传多个文件

上传多个源文件的译文：

```typescript copy
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;
}
```

***


## 说明

* 必须先使用 [`uploadSourceFiles`](/docs/core/class/methods/translation/upload-source-files) 上传源文件
* 每个文件条目中的 `source` 对象都是对现有源文件的引用 (无需提供内容) 
* `translations` 数组中的每条译文都必须包含内容和目标区域设置
* 此方法适合用于迁移现有译文，或上传经人工审核的译文
* 文件引用包含 `branchId`，以便在支持分支的情况下正确进行版本控制

## 后续步骤

* 请先参阅 [`uploadSourceFiles`](/docs/core/class/methods/translation/upload-source-files) 以上传源文件
* 请参阅 [`enqueueFiles`](/docs/core/class/methods/translation/enqueue-files) 以自动生成译文
* 请参阅 [`downloadFile`](/docs/core/class/methods/translation/download-file) 以下载译文结果
* 请参阅 [`queryFileData`](/docs/core/class/methods/translation/query-file-data) 以查看译文状态