入门:文档翻译 REST API

文档翻译是 Azure AI 翻译服务的一项基于云的功能,它以受支持的语言和各种文件格式异步翻译整个文档。 在本快速入门中,了解如何使用文档翻译和所选编程语言将源文档翻译为目标语言,同时保留结构和文本格式。

文档翻译 API 支持两种翻译流程:

  • 异步批量翻译支持处理多个文档和大型文件。 批量翻译过程需要一个 Azure Blob 存储帐户,其中包含源文档和翻译文档的存储容器。

  • 同步翻译单个文件支持处理单个文件的翻译。 文件翻译过程不需要 Azure Blob 存储帐户。 最终响应包含翻译后的文档,会直接返回给调用客户端。

让我们开始吧。

先决条件

需要一个活动 Azure 订阅。 如果没有 Azure 订阅,则可以创建一个试用版订阅

  • 获得 Azure 订阅后,在 Azure 门户中创建一个翻译器资源

    注意

    • 对于本快速入门,建议使用文本翻译单一服务全局资源,除非业务或应用程序需要特定区域。 如果打算使用系统分配的托管标识进行身份验证,请选择一个地理区域,如“中国北部 2”。
    • 使用单服务全局资源,你将在 REST API 请求中包含一个授权标头 (Ocp-Apim-Subscription-key)。 该 Ocp-Apim-Subscription-key 值是你的文本翻译订阅的 Azure 密钥。
  • 部署资源后,选择“转到资源”并检索密钥和终结点。

    • 需要从资源获取密钥和终结点,以便将应用程序连接到翻译器服务。 稍后需要在本快速入门中将密钥和终结点粘贴到代码中。 可以在 Azure 门户的“密钥和终结点”页面上找到这些值

      Azure 门户中的文档翻译密钥和终结点位置的屏幕截图。

  • 对于此项目,我们使用 cURL 命令行工具进行 REST API 调用。

    注意

    大多数 Windows 10 和 Windows 11 以及大多数 macOS 和 Linux 发行版都预装了 cURL 包。 可以使用以下命令检查包版本:Windows:curl.exe -V macOS:curl -V Linux:curl --version

  • 如果未安装 cURL,下面是你的平台的安装链接:

异步翻译文档 (POST)

  1. 使用首选编辑器或 IDE,为应用创建一个名为 document-translation 的新目录。

  2. 在“document-translation”目录中创建一个名为“document-translation.json”的新 json 文件。

  3. 将文档翻译“请求示例”复制并粘贴到 document-translation.json 文件中。 使用 Azure 门户存储帐户容器实例中的值替换 {your-source-container-SAS-URL}{your-target-container-SAS-URL}

    请求示例:

    {
      "inputs":[
        {
          "source":{
            "sourceUrl":"{your-source-container-SAS-URL}"
          },
          "targets":[
            {
              "targetUrl":"{your-target-container-SAS-URL}",
              "language":"fr"
            }
          ]
        }
      ]
    }
    

生成并运行 POST 请求

在运行 POST 请求之前,将 {your-document-translator-endpoint}{your-key} 替换为 Azure 门户翻译器实例中的值。

重要

完成后,请记住将密钥从代码中删除,并且永远不要公开发布该密钥。 对于生产来说,请使用安全的方式存储和访问凭据,例如 Azure Key Vault。 有关详细信息,请参阅 Azure AI 服务安全性

PowerShell

cmd /c curl "{document-translation-endpoint}/translator/document/batches?api-version={date}" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@document-translation.json"

命令提示符/终端

curl "{document-translation-endpoint}/translator/document/batches?api-version={date}" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@document-translation.json"

成功完成后:

  • 可以在目标容器中找到已翻译的文档。
  • 成功的 POST 方法返回 202 Accepted 响应代码,指示服务创建了批处理请求。
  • POST 请求还返回包含 Operation-Location 的响应标头,这些标头提供在后续 GET 请求中使用的值。

同步翻译单个文档 (POST)

若要通过 REST API 调用同步翻译功能,需要在每个请求中包含以下标头。 不用担心,我们会在示例代码中为你包含标头。

注意

所有 cURL 标志和命令行选项均区分大小写

查询参数 说明 条件
-X--request POST -X 标志指定用于访问 API 的请求方法。 必需
{endpoint} 文档翻译资源终结点的 URL 必需
targetLanguage 指定输出文档的语言。 目标语言必须是翻译范围中包含的支持的语言之一。 必需
sourceLanguage 指定输入文档的语言。 如果未指定 sourceLanguage 参数,则会应用自动语言检测来确定源语言。 可选
-H--header "Ocp-Apim-Subscription-Key:{KEY} 请求头,用于指定授权访问 API 的文档翻译资源密钥。 必需
-F--form 要包含在请求中的文档文件路径。 只允许一个源文档。 必需
document=
type={contentType}/fileExtension
• 源文档的文件位置路径。
• 内容类型和文件扩展名。

示例:"document=@C:\Test\test-file.md;type=text/markdown
必需
-o--output 响应结果的文件路径。 必需
-F--form 要包含在请求中的可选术语表的文件路径。 术语表需要单独的 --form 标志。 可选
glossary=
type={contentType}/fileExtension
• 可选术语表文件的文件位置路径。
• 内容类型和文件扩展名。

示例:"glossary=@C:\Test\glossary-file.txt;type=text/plain
可选

✔️ 有关 contentType 的详细信息,请参阅支持的文档格式

生成并运行同步 POST 请求

  1. 对于此项目,你需要一个示例文档。 可下载本快速入门的 Microsoft Word 示例文档。 源语言为英语。

  2. 在运行 POST 请求之前,请将 {your-document-translation-endpoint}{your-key} 替换为 Azure 门户翻译服务实例中的值。

    重要

    完成后,请记住将密钥从代码中删除,并且永远不要公开发布该密钥。 对于生产来说,请使用安全的方式存储和访问凭据,例如 Azure Key Vault。 有关详细信息,请参阅 Azure AI 服务安全性

    命令提示符/终端

    
    curl -i -X POST "{document-translation-endpoint}/translator/document:translate?targetLanguage={target_language}&api-version={date}" -H "Ocp-Apim-Subscription-Key:{your-key}"  -F "document={path-to-your-document-with-file-extension};type={ContentType}/{file-extension}" -F "glossary={path-to-your-glossary-with-file-extension};type={ContentType}/{file-extension}" -o "{path-to-output-file}"
    

    PowerShell

    cmd /c curl "{document-translation-endpoint}/translator/document:translate?targetLanguage={target_language}&api-version={date}" -i -X POST  -H "Ocp-Apim-Subscription-Key: {your-key}" -F "{path-to-your-document-with-file-extension};type=text/{file-extension}" -o "{path-to-output-file}
    
    

    ✔️ 有关 Query parameters 的详细信息,请参阅同步文档翻译

成功完成后

  • 翻译后的文档随响应一起返回。
  • 成功的 POST 方法返回 200 OK 响应代码,指示服务创建了请求。

完成了,恭喜! 你刚刚学习了如何使用 Azure AI Translator 服务翻译文档。

后续步骤