TransOne

简体中文

English

简体中文

English

外观

自定义翻译 API ​

如果你的翻译服务不在 27 个内置引擎之列，或者你自建了一个，自定义 API 引擎让你手动把它描述给 TransOne，之后 TransOne 就会像调用其他引擎一样调用它。

这是本指南里最偏技术的一页。它假设你了解自己的服务期望怎样的请求、它的应答长什么样。如果你只想省心地翻译，一个内置引擎或本地模型会更合适。

它的配置和别的引擎一样：从菜单栏图标打开偏好设置（⌘,），进入设置 ▸ 翻译服务，点添加服务，选自定义 API。

自定义 API 引擎的配置界面

五个区域 ​

编辑器分成五部分。

  • 外观：上传你自己的图标，方便在列表里认出这个引擎。
  • 请求：TransOne 怎样调用你的服务。
    • 方法：GET 或 POST。
    • URL：要调用的地址。它必须是 https，或者一个 localhost 地址。
    • 请求头：增删请求头，比如一个 Authorization 头。
    • 请求体：仅 POST 使用，而且 POST 必须有请求体。
  • 响应：TransOne 怎样读取应答。
    • 提取方式：要么把整个应答当作译文，要么从 JSON 应答里取一个值。
    • 字段路径：从 JSON 取值时，指向译文的那条点分路径（下面解释）。
    • 附加字段：可选，从应答里再取一些值，只读地显示在译文下方（下面解释）。
  • 语言：一张表，把 TransOne 的语言代码映射到你的服务期望的代码，另外还有自动源（下面解释）。
  • 凭据：你的 API Key。和每个引擎一样，它存放在 macOS 钥匙串里。

你可以用的变量 ​

在 URL、请求头和请求体里，写下面这些占位符，TransOne 会在每次翻译时填入它们。

变量展开为
{{text}}要翻译的文字。
{{from}}经过「语言」表映射之后的源语言代码。
{{to}}经过「语言」表映射之后的目标语言代码。
{{from_name}}源语言的全名，例如 English。
{{to_name}}目标语言的全名，例如 Spanish。
{{apiKey}}「凭据」区域里的 API Key。

每个变量都会按它所在的位置正确转义：放在请求体里时按 JSON 安全地加引号，放在 URL 里时做百分号编码。你不用自己转义。

字段路径：读取应答 ​

大多数服务用一段 JSON 应答，译文就藏在里面某处。字段路径就是通往那段文字的点分路径。每一步之间用点隔开，用数字进入一个列表。

例如，路径 data.translations.0.text 读取的是这段应答：

json
{
  "data": {
    "translations": [
      { "text": "Bonjour le monde" }
    ]
  }
}

一步步来看：data 打开外层对象，translations 是它里面的列表，0 取列表里的第一项， text 就是那一项里的译文字符串。TransOne 显示 Bonjour le monde。

如果你的服务只回译文、别的什么都没有，就把提取方式设为使用整段响应，这时不需要路径。

在译文旁边显示附加字段 ​

有些服务回的不只是译文：备选译法、读音、例句等等。附加字段能把这些只读地显示在主译文下方。每个字段是一行，分三部分：

  • 标签：显示在值上方的名字，比如 Pronunciation。
  • 路径：从哪里读它，写法和字段路径一样，但多了一项本领（见下）。
  • 文本 / 列表：这个值是单个字符串（文本），还是一组字符串（列表）。

点添加字段加一行，点行尾的按钮删一行。路径解析不出来的字段会被悄悄跳过，所以偶尔缺一个值也不会让翻译出错，只有主译文是必需的。

用 * 投影列表 ​

字段的路径支持字段路径的全部写法（点分键名和数字下标），另外还多了 *：它会从一个列表的每一项里取同一个键。例如 alternatives.*.text 读出 alternatives 里每一项的 text：

json
{
  "alternatives": [
    { "text": "Hi there" },
    { "text": "Hello" }
  ]
}

把这个字段设为列表，TransOne 就会同时显示 Hi there 和 Hello。（主字段路径保持朴素：只用点分键名和数字下标，不支持 *。）

映射语言 ​

TransOne 有自己的一套语言代码，你的服务可能用另一套。语言表让你把它们配对：每一行一边是 TransOne 的代码，另一边是你的服务期望的代码。当 TransOne 填入 {{from}} 和 {{to}} 时，发出去的是你服务的代码，而不是它自己的。

自动源是源语言处于自动检测状态时，替源语言发送的值。举例来说，如果你的服务把空字符串或 auto 当作「帮我检测语言」，就把它填在这里。每当源语言处于自动检测时，它就会作为 {{from}} 发出去。

规则 ​

  • URL 必须以 https 开头，或者指向一个 localhost 地址。指向其他主机的普通 http 不允许。
  • POST 请求必须有请求体。

一个完整示例 ​

假设你自建了一个 LibreTranslate 风格的翻译服务器。它接收带 JSON 请求体的 POST，回一个 JSON 对象。你可以这样配置「自定义 API」：

方法：    POST
URL：     https://translate.example.com/translate
请求头：  Content-Type: application/json
请求体：
  {
    "q": "{{text}}",
    "source": "{{from}}",
    "target": "{{to}}",
    "api_key": "{{apiKey}}"
  }

提取方式：JSON 字段路径
字段路径：translatedText

如果服务器回的是 {"translatedText": "Hola mundo"}，路径 translatedText 读出 Hola mundo，TransOne 就显示它。

说明

这只是演示各个字段如何配合，并非推荐任何特定服务。请按你自己服务的文档填入相应的值。

相关 ​

35c413a