博客Dashboard

快速开始

General Translation 库快速上手指南

概览

本指南将带你入门使用 General Translation 库。 我们将介绍字符串翻译与文件翻译。

翻译你的第一个字符串

1. 获取环境变量

首先创建 GT_PROJECT_ID 和 GT_API_KEY。 这完全免费，并可让你使用翻译服务。

前往 API Keys 页面，点击 Create API Key。 为你的 API Key 设置一个名称，然后点击 Create。

API key page

General Translation 为个人项目、独立开发者和社区提供非常宽松的免费调用额度。

2. 初始化 GT 类

初始化 GT 类，并安全传入你的 GT_PROJECT_ID 和 GT_API_KEY。

src/index.ts
import { GT } from 'generaltranslation';

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

3. 翻译你的第一个字符串

调用 translate 方法翻译字符串。 传入要翻译的字符串和目标语言代码。

src/index.ts
const { translation } = await gt.translate('Hello, world!', 'es'); // 西班牙语

console.log(translation); // "¡Hola, mundo!"

如需查询语言代码，请查看 supported locales 页面。

翻译你的第一个文件

本指南假设你已经完成了翻译你的第一个字符串中的第 1 和第 2 步， 并且已拥有 GT_PROJECT_ID、GT_API_KEY，以及一个 GT 类实例。

假设你想将名为 en.json 的文件翻译成西班牙语。

en.json
{
  "hello": "你好",
  "world": "世界"
}

要翻译文件，你需要按照以下四个步骤进行：

  1. 上传文件
  2. 将文件加入翻译队列
  3. 查看文件状态（可选）
  4. 下载翻译后的文件。

为什么不只用一次调用？

通常，用户会希望一次性翻译多个文件。 将流程拆分为四个清晰步骤，可以让用户在使用 API 时拥有更大的灵活性。

1. 上传文件

通过 uploadSourceFiles 方法上传文件后，会返回一个文件引用列表。 您可以在稍后将该文件加入翻译队列、查看文件状态，并下载译文文件。

src/index.ts
import fs from 'fs';
import path from 'path';
import { FileUpload } from 'generaltranslation';

// （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'
  }
);

这将返回一个文件引用列表：

Output
[
  {
    fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
    versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
    fileName: '/Users/demo/en.json',
    fileFormat: 'JSON'
  }
]

2. 将文件加入翻译队列

接下来，使用 enqueueFiles 方法选择此次翻译的目标 locales。 在本例中，我们将翻译成西班牙语。

src/index.ts
const fileUploadRef = {
  fileId: uploadedFiles[0].fileId,
  versionId: uploadedFiles[0].versionId,
  fileName: uploadedFiles[0].fileName,
  fileFormat: uploadedFiles[0].fileFormat,
};
const enqueueResult = await gt.enqueueFiles(
  [fileUploadRef],
  {
  sourceLocale: 'en',
  targetLocales: ['es'],
});

这会返回一份文件引用列表：

Output
{
  translations: [],
  data: {
    '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e': {
      fileName: '/Users/demo/en.json',
      versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121'
    }
  },
  locales: [ 'es' ],
  message: '正在创建 1 条翻译。'
}

3. 检查文件状态

好的，文件已上传。我们什么时候能知道它已准备好下载？ 我们可以使用 checkFileTranslations 方法检查文件状态。

src/index.ts
const status = await gt.checkFileTranslations([{
  versionId: uploadedFiles[0].versionId,
  fileName: uploadedFiles[0].fileName,
  locale: 'es'
}]);

如果文件仍在翻译中，输出中不会包含相应的译文。

Output
{
  translations: [
    {
      locale: 'es',
      metadata: {},
      fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
      fileName: '/Users/demo/en.json',
      versionId: '427269616e204c6f75206d6f7265206c696f6e2042726f20686121',
      id: 'skl44z0ieuvdcomw38zb5chv',
      isReady: true,
      downloadUrl: '/v2/project/translations/files/skl44z0ieuvdcomw38zb5chv/download'
    }
  ]
}

4. 下载译文文件

最后，我们可以使用 downloadTranslatedFile 方法来下载译文文件。

src/index.ts
const { translation } = await gt.downloadTranslatedFile({
  fileId: uploadedFiles[0].fileId,
  locale: 'es',
  versionId: uploadedFiles[0].versionId,
});

这将返回翻译后的文件内容：

Output
{
  "hello": "你好",
  "world": "世界"
}

本指南如何?

本页目录

概览
翻译你的第一个字符串
1. 获取环境变量
2. 初始化 GT 类
3. 翻译你的第一个字符串
翻译你的第一个文件
为什么不只用一次调用？
1. 上传文件
2. 将文件加入翻译队列
3. 检查文件状态
4. 下载译文文件