# General Translation Platform: 翻译文件
URL: https://generaltranslation.com/zh/docs/platform/core/guides/translating-files.mdx
---

title: 翻译文件
description: "如何使用 generaltranslation 库翻译文件：本指南涵盖上传源文件、将翻译任务加入队列、检查状态以及下载翻译后的文件。"
related:
  links:
    - /docs/platform/core/guides/translating-strings
    - /docs/platform/core/guides/locale-codes

---

`generaltranslation` 库可以翻译完整的源文件。本页将介绍文件上传、入队、状态查询和下载的工作流程。

## 开始之前 [#before-start]

请确保你已完成 [Quickstart](/docs/platform/core/quickstart)，安装好 `generaltranslation` 并初始化 [GT](/docs/platform/core/reference/gt-class/constructor) 类。

## 文件翻译的工作原理 [#file-translation-works]

文件翻译以作业形式进行：

1. 上传源文件。
2. 将文件加入翻译队列。
3. 检查翻译状态。
4. 下载翻译后的文件。

文件翻译需要多次调用，是因为项目通常会翻译很多文件。将流程拆分为独立步骤，能让你在使用 API 时更灵活：更方便批量处理文件、重试失败的任务、轮询作业，以及在输出就绪后下载结果。

上传文件即可启动作业；上传多个文件会启动多个作业。更多信息请参阅 [uploadSourceFiles](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files) 和 [queryFileData](/docs/platform/core/reference/gt-class-methods/translation/query-file-data) 方法。

## 1. 上传源文件 [#upload]

本指南将以这个英文 JSON 文件为例：

```json
{
  "hello": "Hello",
  "world": "World"
}
```

读取文件并格式化内容，然后调用 [uploadSourceFiles](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files) 上传文件。

```typescript title="src/index.ts"
import fs from 'fs';
import path from 'path';
import { FileUpload } from 'generaltranslation/types';

// (i) 读取文件内容
const filePath = path.join(process.cwd(), 'en.json');
const fileContents = fs.readFileSync(filePath, 'utf8');

// (ii) 格式化文件内容
const fileUpload: FileUpload = {
  content: fileContents,
  fileName: filePath,
  fileFormat: 'JSON',
  locale: 'en',
};
const files = [ { source: fileUpload } ];

// (iii) 上传文件
const { uploadedFiles } = await gt.uploadSourceFiles(
  files,
  {
    sourceLocale: 'en'
  }
);
```

响应会返回一个文件引用列表。这样你之后就可以将该文件加入翻译队列、查看文件状态，并下载翻译后的文件。

```ts title="Output"
[
  {
    fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
    versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
    branchId: '123456789',
    fileName: '/Users/demo/en.json',
    fileFormat: 'JSON'
  }
]
```

## 2. 将文件加入翻译队列 [#enqueue]

使用 [enqueueFiles](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files)，并传入已上传文件的引用和目标区域设置。本示例中，我们将翻译为西班牙语 (`es`)。

```typescript title="src/index.ts"
const fileUploadRef = {
  fileId: uploadedFiles[0].fileId,
  versionId: uploadedFiles[0].versionId,
  branchId: uploadedFiles[0].branchId,
  fileName: uploadedFiles[0].fileName,
  fileFormat: uploadedFiles[0].fileFormat,
};

const enqueueResult = await gt.enqueueFiles(
  [fileUploadRef],
  {
    sourceLocale: 'en',
    targetLocales: ['es'],
  }
);
```

该响应会返回一个包含 job 信息的结果。

```ts title="Output"
{
  jobData: {
    'job-123456': {
      sourceFileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
      fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
      versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
      branchId: '123456789',
      targetLocale: 'es',
      projectId: 'your-project-id',
      force: false
    }
  },
  locales: ['es'],
  message: 'Successfully enqueued 1 file translation jobs in 1 batch(es)'
}
```

## 3. 检查文件状态 [#status]

使用 [queryFileData](/docs/platform/core/reference/gt-class-methods/translation/query-file-data) 检查翻译后的文件是否已完成并可供下载。

```typescript title="src/index.ts"
const { fileId, versionId, branchId } = uploadedFiles[0];

const status = await gt.queryFileData({
  translatedFiles: [
    {
      fileId,
      versionId,
      branchId,
      locale: 'es',
    },
  ],
});
```

如果文件仍在翻译中，`completedAt` 为 `null`。翻译完成后，它会包含一个时间戳：

```ts title="Output"
{
  translatedFiles: [
    {
      fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
      versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
      branchId: '123456789',
      locale: 'es',
      completedAt: '2024-01-15T12:00:00Z'
    }
  ]
}
```

## 4. 下载翻译后的文件 [#download]

最后，使用 [downloadFile](/docs/platform/core/reference/gt-class-methods/translation/download-file) 方法下载翻译后的文件。

```typescript title="src/index.ts"
const { fileId, branchId } = uploadedFiles[0];

const content = await gt.downloadFile({
  fileId,
  branchId,
  locale: 'es',
});
```

响应会返回翻译后的文件内容。此示例返回：

```json title="Output"
{
  "hello": "Hola",
  "world": "Mundo"
}
```
## Next steps

- /docs/platform/core/guides/translating-strings
- /docs/platform/core/guides/locale-codes