文档翻译是 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,下面是你的平台的安装链接:
异步翻译文档 (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 门户翻译服务实例中的值。重要
完成后,请记住将密钥从代码中删除,并且永远不要公开发布该密钥。 对于生产来说,请使用安全的方式存储和访问凭据,例如 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 服务翻译文档。