入门：文档翻译 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 门户的“密钥和终结点”页面上找到这些值。

    

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

  备注

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

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

  • Windows
  • Mac 或 Linux

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 请求之前，将 {your-document-translator-endpoint} 和 {your-key} 替换为 Azure 门户翻译器实例中的值。

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 请求中使用的值。

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

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

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 服务翻译文档。