使用翻译器 API 翻译文本

翻译器 API 是一种实验性 Web API，允许你使用内置于 Microsoft Edge 的专家模型，从网站或浏览器扩展中的 JavaScript 代码翻译不同语言之间的文本。

有关翻译器 API 的介绍性信息，请参阅：

• 翻译器和语言检测器 API
• 翻译器和语言检测器 API 的解释器

详细内容：

• 翻译器 API 的可用性
• 翻译器 API 的优点
• 翻译器 API 的替代方法
• 免责声明
• 模型可用性
• 启用翻译器 API
• 查看工作示例
• 使用翻译器 API
• 检查是否启用了翻译器 API
• 检查模型是否可以 (可用性 () )
• 创建新会话 (创建 () )
• 监视模型下载进度 (monitor：)
• 运行翻译器 API (翻译 () )
  • 等待文本翻译 (翻译 () )
  • 在翻译流式处理 () ) 生成令牌 (时显示令牌
• 停止翻译文本 (abortController.signal)
• 销毁会话 (销毁 () )
  • 通过调用 destroy () 销毁会话
  • 使用 AbortController 销毁会话
• 发送反馈
• 另请参阅

翻译器 API 的可用性

从版本 143.0.3636.0 开始，翻译 API 在 Microsoft Edge Canary 或开发频道中作为开发人员预览版提供。 若要下载 Microsoft Edge (Beta、Dev 或 Canary) 的预览频道，请转到 成为 Microsoft Edge 预览体验成员。

翻译器 API 的优点

翻译器 API 使用专家模型进行机器翻译，该模型在同一设备上运行，在该设备上，模型的输入和输出 (本地) 。 与基于云的解决方案相比，此方法具有以下优势：

• 降低成本： 使用云翻译服务不产生任何费用。

• 网络独立性： 除了初始模型下载之外，使用此 API 翻译文本时不会有网络延迟，并且当设备脱机时也可以使用该 API。

• 改进的隐私： 输入到模型的数据永远不会离开设备，也不会收集这些数据来训练 AI 模型。

首次在 Microsoft Edge 中使用 API 时，将下载指定语言对的翻译模型，随后在浏览器中的所有网站之间共享。 通过简单的 Web API 访问模型，该 API 不需要了解第三方框架，也不需要人工智能 (AI) 或机器学习 (ML) 专业知识。

翻译器 API 的替代方法

可以将网络请求发送到基于云的翻译服务，其中包含更复杂的功能，包括神经翻译;请参阅Azure AI Translator 文档。

作为设备上的替代方法，提示 API 通过内置于 Microsoft Edge 中的小型语言模型，提供更多自定义的多语言提示方案;请参阅 使用提示 API 提示内置语言模型。

免责声明

与其他机器翻译模型一样，Microsft Edge 中的专家模型可能会生成不公平、不可靠或冒犯性的翻译。 若要详细了解这些机器翻译模型的局限性，请参阅Azure AI 翻译工具透明度说明中的限制。

模型可用性

网站首次调用内置 AI API 时，需要初始下载模型。 创建新的翻译器 API 会话时，可以使用监视器选项监视模型下载;请参阅下面的 监视模型下载进度 (monitor：) 。

启用翻译器 API

若要在 Microsoft Edge 中使用翻译 API，请设置两个标志，如下所示：

1. 在 Microsoft Edge 中，转到 edge://version，并确保使用版本 143.0.3636.0 或更高版本的 Microsoft Edge，例如 Microsoft Edge 的 Canary 或 Dev 预览频道。

   若要下载 Microsoft Edge (Beta、Dev 或 Canary) 的预览频道，请转到 成为 Microsoft Edge 预览体验成员。

2. 在该版本的 Microsoft Edge 中，打开一个新选项卡或窗口，然后转到 edge://flags。

3. 在顶部的 “搜索标志 ”文本框中，开始键入 翻译 API：

   

   列出了以下标志：

   • 实验性翻译 API - 启用设备语言翻译 API。 有关 翻译器和语言检测器 API，请参阅解释器。

     此条目显示 #edge-translation-api，它转到 edge://flags/#edge-translation-api。

   • 按句子拆分的翻译 API 流式处理 - 启用后，翻译 API 将按句子拆分文本，并在翻译完成后对每个翻译的句子进行流式处理，从而为长文本翻译提供更好的响应能力。

     此条目显示 #edge-translation-api-streaming-by-sentence，它转到 edge://flags/#edge-translation-api-streaming-by-sentence。

4. 在 “实验翻译 API”下，选择“ 已启用”。

5. 在“ 翻译 API 流式处理按句子拆分”下，选择“ 已启用”。

   右下角显示“ 重启 ”按钮。

6. 单击“ 重启” 按钮。

查看工作示例

若要查看翻译器 API 的运行情况，并查看使用这些 API 的现有代码，请执行以下作：

1. 如上所述，启用翻译器 API。

2. 在 Microsoft Edge Canary 或 Dev 中，转到新窗口或选项卡中的 翻译 API场 。

3. 在顶部的信息横幅中，检查状态：最初为：设备 API 和型号可下载。首次使用 API 时，将下载指定语言对的模型。

4. 在“ 要翻译的文本 ”文本框中，输入要翻译的文本，并选择性地更改 “源语言 ”和“ 目标语言 ”值。

5. 单击“ 翻译 ”按钮。

   如果之前尚未下载指定语言对的模型，则开始下载。

   

   如果模型下载未启动，请重启Microsoft Edge，然后重试。

   下载模型后，模型开始生成文本从源语言到目标语言的翻译。

   输出在页面的响应部分中生成：

   

6. 若要停止生成响应，请随时单击“ 停止 ”按钮。

另请参阅：

• /built-in-ai/ - 内置 AI场演示的源代码和自述文件。

使用翻译器 API

接下来的部分是关于使用翻译器 API。

检查是否启用了翻译器 API

在网站代码中使用翻译器 API 之前，检查通过测试对象的存在来启用 APITranslator：

if (!Translator) {
  // The Translator API is not available.
} else {
  // The Translator API is available.
}

检查模型是否可以 (availability()) 使用

翻译器 API 具有以下要求：

• 必须支持从指定的源语言翻译为指定的目标语言。
• Microsoft Edge 必须已下载语言对和模型运行时的翻译模型。

若要检查 API 是否可以使用，请调用 availability()：

const availability = await Translator.availability({
  sourceLanguage: "en",
  targetLanguage: "es"
});

if (availability == "unavailable") {
  // The model is not available.
}

if (availability == "downloadable" || availability == "downloading") {
  // The model can be used, but it needs to be downloaded first.
}

if (availability == "available") {
  // The model is available and can be used.
}

对于 sourceLanguage 和 targetLanguage，请使用 用于标识语言的标记中的语言代码作为字符串。

创建新会话 (create())

创建会话会指示浏览器在内存中加载语言模型，以便可以使用它。 在翻译文本之前，请使用 create() 方法创建新会话，并指定源语言和目标语言：

// Create a Translator session.
const session = await Translator.create({
  sourceLanguage: "en",
  targetLanguage: "es"
});

可以使用 选项监视模型下载 monitor ，如下所示。

监视模型下载 (monitor:) 的进度

可以使用 选项跟踪模型下载 monitor 进度。 当模型尚未完全下载到要使用的设备上时，这将非常有用，以通知网站用户他们应该等待。

// Create a Translator session with the monitor option to monitor the model
// download.
const session = await Translator.create({
  sourceLanguage: "en",
  targetLanguage: "es",
  monitor: m => {
    // Use the monitor object argument to add an listener for the 
    // downloadprogress event.
    m.addEventListener("downloadprogress", event => {
      // The event is an object with the loaded and total properties.
      if (event.loaded == event.total) {
        // The model is fully downloaded.
      } else {
        // The model is still downloading.
        const percentageComplete = (event.loaded / event.total) * 100;
      }
    });
  }
});

运行翻译 API (translate())

创建模型会话后，可以翻译文本。 翻译 API 提供两种翻译文本的方法：

• translatorSession.translate() 返回承诺，该承诺在文本翻译后解析。
• translatorSession.translateStreaming() 立即返回一个流对象，该对象可用于显示生成的已翻译文本（逐个标记）。

详细信息如下所示。

等待文本翻译 (translate())

翻译文本。 返回一个承诺，该承诺在翻译文本后解析。

若要在继续运行代码之前等待文本完全翻译，请使用 translate() 异步方法。 此方法返回一个承诺，该承诺在 API 完成文本生成后解析：

// Create a Translator session.
const translatorSession = await Translator.create({
  sourceLanguage: "en",
  targetLanguage: "es"
});

// Translate the text and wait for the translation to be done.
const translatedText = await translatorSession.translate(sourceText);

// Use the translation.
console.log(translatedText);

在生成令牌时显示令牌 (translateStreaming())

翻译文本。 立即返回一个流对象，可以使用该对象在生成时逐个标记显示已翻译的文本。

若要在生成令牌时显示令牌，请使用此流式处理方法。 方法 translateStreaming() 立即返回流对象。 使用返回的流对象在生成响应令牌时显示这些令牌：

// Create a Translator session.
const translatorSession = await Translator.create({
  sourceLanguage: "en",
  targetLanguage: "es"
});

// Ask the model to translate text.
const stream = translatorSession.translateStreaming(sourceText);

// Use the stream object to display tokens that are generated by the model, as
// they are being generated.
for await (const chunk of stream) {
  console.log(chunk);
}

停止翻译文本 (abortController.signal)

若要在上述方法返回的承诺或流已解决或结束之前停止翻译文本，请使用 AbortController 信号：

// Create a Translator session.
const translatorSession = await Translator.create({
  sourceLanguage: "en",
  targetLanguage: "es"
});

// Create an AbortController object.
const abortController = new AbortController();

// Use the model session to translate some text and pass the AbortController
// object by using the signal option.
const stream = translatorSession.translateStreaming(sourceText, {
    signal: abortController.signal
});

// Later, perhaps when the user presses a "Stop" button, call the abort()
// method on the AbortController object to stop translating text.
abortController.abort();

销毁会话 (destroy())

翻译文本后，销毁会话，让浏览器知道你不再需要语言模型，以便可以从内存中卸载该模型。

可以通过两种不同的方式销毁会话：

• 通过使用 destroy() 方法。
• 通过使用 AbortController。

详细信息如下所示。

通过调用销毁会话 destroy()

若要使用会话调用 destroy() 来销毁会话，请执行 Translator ：

const session = await Translator.create({
  sourceLanguage: "en",
  targetLanguage: "es"
});

// Later, destroy the session by using the destroy method.
session.destroy();

使用 销毁会话 AbortController

若要通过创建 AbortController 对象来销毁会话，请创建会话 Translator ，然后调用 abort()：

// Create an AbortController object.
const controller = new AbortController();

// Create a Translator session and pass the 
// AbortController object by using the signal option.
const session = await Translator.create({
  sourceLanguage: "en",
  targetLanguage: "es",
  signal: controller.signal
});

// Later, perhaps when the user interacts with the UI, destroy the session by
// calling the abort() function of the AbortController object.
controller.abort();

发送反馈

我们非常有兴趣了解你打算使用翻译器 API 的方案范围、API 或专家模型的任何问题，以及其他特定于任务的内置 API 是否有用。

若要发送有关方案和要实现的任务的反馈，请向 翻译 API 反馈问题添加注释。

如果在改用 API 时发现任何问题，请在存储库中报告。

还可以在 W3C Web 机器学习工作组存储库中参与有关翻译器 API 设计的讨论。

另请参阅

• 使用提示 API 提示内置语言模型
• 使用编写辅助 API 汇总、编写和重写文本

获取 Microsoft Edge：

• 成为Microsoft Edge 预览体验成员 - 下载Microsoft Edge (Beta 版、开发人员版或 Canary) 的预览频道。

GitHub：

• webmachinelearning /translation-api 存储库。
  • 翻译器和语言检测器 API 的解释器
• 翻译器和语言检测器 API
  • 标识语言的标记 - 和 sourceLanguagetargetLanguage。

Azure文档：

• Azure AI 翻译器文档
• Azure AI 翻译工具透明度说明中的限制。

演示存储库：

• 翻译 API场
• /built-in-ai/ - 内置 AI场演示的源代码和自述文件。