Bob

外观

文本翻译 ​

文本翻译插件需要实现以下函数:

  1. 获取支持的语言数组（必须实现）
  2. 执行翻译（必须实现）
  3. 自定义翻译超时时间（可选）
  4. 自定义验证（可选）

1. 获取支持的语言数组 ​

js
function supportLanguages() {
    return ['auto', 'zh-Hans', 'en', ...];
}
function supportLanguages() {
    return ['auto', 'zh-Hans', 'en', ...];
}

该函数不需要参数，调用时返回支持的语言字符串数组即可。

鉴于各个服务商的语言标识符都略有差异，我定义了一套 Bob 专用的语言代码，所有需要回传语言给 Bob 主程序的地方，都要使用 这套语言代码。

2. 执行翻译 ​

js
function translate(query, completion) {
    ...
    ...
    // Bob 1.8.0 之前
    completion({'result': result});
    // or
    completion({'error': error});

    // Bob 1.8.0+
    query.onCompletion({'result': result});
    // or
    query.onCompletion({'error': error});
}
function translate(query, completion) {
    ...
    ...
    // Bob 1.8.0 之前
    completion({'result': result});
    // or
    completion({'error': error});

    // Bob 1.8.0+
    query.onCompletion({'result': result});
    // or
    query.onCompletion({'error': error});
}

该函数在每次翻译的时候会被调用。

  • query 参数为 object 类型，用于传入需要翻译的文本信息
  • completion 参数为 function 类型，用于翻译完毕之后回调（Bob 1.8.0 之前需用本函数回调翻译结果）

由于需要支持流式输出，为了方便扩展，现在将所有新增参数都统一放到 query 参数中。

Bob 1.8.0+ 不再推荐使用 completion 参数，请使用 query.onCompletion，与其等效。不过为了兼容老版本插件，completion 参数目前会保留。

query 参数的结构如下:

属性类型说明
textstring需要翻译的文本。
fromstring用户选中的源语言代码，可能是 auto。查看 语言代码。
tostring用户选中的目标语言代码，可能是 auto。查看 语言代码。
detectFromstring检测过后的源语言，一定不是 auto，如果插件不具备检测语言的能力，可直接使用该属性。查看 语言代码。
detectTostring检测过后的目标语言，一定不是 auto，如果不想自行推测用户实际需要的目标语言，可直接使用该属性。查看 语言代码。
cancelSignal$signal取消信号，可直接将此对象透传给 $http 请求用于取消，同时也可以监听此信号做一些额外的逻辑 Bob 1.8.0+ 可用
onStreamfunction流式数据回调函数 Bob 1.8.0+ 可用
onCompletionfunction翻译完毕回调函数 Bob 1.8.0+ 可用

示例：

js
{
    "text": "good",
    "from": "auto",
    "to": "auto",
    "detectFrom": "en",
    "detectTo": "zh-Hans"
    "cancelSignal": cancelSignal,
    "onStream": onStream,
    "onCompletion": onCompletion
}
{
    "text": "good",
    "from": "auto",
    "to": "auto",
    "detectFrom": "en",
    "detectTo": "zh-Hans"
    "cancelSignal": cancelSignal,
    "onStream": onStream,
    "onCompletion": onCompletion
}

onStream 函数用于回调流式数据，参数为 translate result 对象，必须赋值 toParagraphs 属性，toDict 属性将会被忽略。如果无需流式输出，不需要调用本函数。

onCompletion 函数用于回调最终的翻译数据，参数为 object 类型，根据不同情况赋值对应属性：

属性类型说明
resulttranslate result翻译成功时，设置该属性。
errorservice error翻译错误时，设置该属性。

3. 自定义翻译超时时间 Bob 1.6.0+ 可用 ​

Bob 主程序调用插件 translate 函数的时候，会设定一个超时时间，防止插件出现不回调的情况。

超时时间默认为 60 秒，可自定义为 30 秒到 300 秒之间。不建议将超时时间设置得过长，比较影响用户体验。如无特殊需要，请勿自定义超时时间。

如果需要自定义超时时间，可以实现以下函数：

js
function pluginTimeoutInterval() {
    return 60;
}
function pluginTimeoutInterval() {
    return 60;
}

4. 自定义验证 Bob 1.6.0+ 可用 ​

如果插件想要在偏好设置显示验证按钮，可以自行实现验证函数。

验证函数的 completion 参数为 function 类型，用于验证完毕之后回调。

completion 的参数为 object 类型，根据不同情况赋值对应属性：

属性类型说明
resultboolean验证是否成功。
errorservice error验证失败时，设置该属性。

注意，error 新增了 troubleshootingLink 属性，可用于验证失败时显示故障排除的链接给用户。

js
function pluginValidate(completion) {
    // 验证成功示例
    completion({ result: true });

    // 验证失败示例
    completion({ 
        result: false,
        error: {
            type: "secretKey",
            message: "未设置秘钥",
            troubleshootingLink: "https://www.google.com"
        }
    });
}
function pluginValidate(completion) {
    // 验证成功示例
    completion({ result: true });

    // 验证失败示例
    completion({ 
        result: false,
        error: {
            type: "secretKey",
            message: "未设置秘钥",
            troubleshootingLink: "https://www.google.com"
        }
    });
}

Copyright © 2019-present Zongyi He