同步翻译入门

  • 项目

文档翻译是 Azure AI 翻译服务的一项基于云的机器翻译功能。 可以跨所有支持的语言和方言翻译多个复杂文档，同时保留原始文档结构和数据格式。

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

让我们开始吧。

先决条件

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

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

    注意

    • 对于本快速入门，建议使用文本翻译单一服务全局资源，除非业务或应用程序需要特定区域。 如果打算使用系统分配的托管标识进行身份验证，请选择一个地理区域，如“中国北部”。
    • 使用单服务全局资源，你将在 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，下面是你的平台的安装链接：

标头和参数

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

注意

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

查询参数 说明 条件
-X 或 --requestPOST -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 "{your-document-translation-endpoint}/translator/document:translate?sourceLanguage=en&targetLanguage=hi&api-version=2023-11-01-preview" -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 "{your-document-translation-endpoint}/translator/document:translate?sourceLanguage=en&targetLanguage=es&api-version=2023-11-01-preview" -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 翻译服务同步翻译文档。

后续步骤

异步批量翻译