入门：文档翻译 REST API

项目
2024-08-21

文档翻译是 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

异步翻译文档 (POST)

使用首选编辑器或 IDE，为应用创建一个名为 document-translation 的新目录。
在“document-translation”目录中创建一个名为“document-translation.json”的新 json 文件。

将文档翻译“请求示例”复制并粘贴到 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 请求

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

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

重要

命令提示符/终端


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

后续步骤

文档翻译 REST API 指南

通过