你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 Python 的 Azure 文档翻译客户端库 - 版本 1.0.0

Azure 认知服务文档翻译是一种云服务，可用于跨语言和方言翻译多个复杂文档，同时保留原始文档结构和数据格式。 使用用于文档翻译的客户端库可以：

• 将大量大型文件从Azure Blob 存储容器翻译成所选语言的目标容器。
• 检查翻译操作中每个文档的翻译状态和进度。
• 应用自定义翻译模型或术语表，根据特定情况定制翻译。

源代码 | 包 (PyPI) | API 参考文档 | 产品文档 | 样品

免责声明

对 Python 2.7 的 Azure SDK Python 包支持已于 2022 年 1 月 1 日结束。 有关详细信息和问题，请参阅 https://github.com/Azure/azure-sdk-for-python/issues/20691

入门

先决条件

• 使用此包需要 Python 3.6 或更高版本。
• 必须具有 Azure 订阅 和 翻译器资源 才能使用此包。

安装包

使用 pip 安装适用于 Python 的 Azure 文档翻译客户端库：

pip install azure-ai-translation-document

注意：此版本的客户端库默认为 v1.0 版本的服务

创建“翻译”资源

文档翻译功能仅支持 单服务访问 。 若要访问服务，请创建翻译器资源。

可以使用 创建资源

选项 1：Azure 门户

选项 2：Azure CLI。 下面是如何使用 CLI 创建翻译器资源的示例：

# Create a new resource group to hold the Translator resource -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create document translation
az cognitiveservices account create \
    --name document-translation-resource \
    --custom-domain document-translation-resource \
    --resource-group my-resource-group \
    --kind TextTranslation \
    --sku S1 \
    --location westus2 \
    --yes

验证客户端

若要与文档翻译功能服务交互，需要创建客户端的实例。 实例化客户端对象需要 终结点 和 凭据 。

查找终结点

可以使用 Azure 门户查找翻译器资源的终结点。

请注意，该服务需要自定义域终结点。 按照上述链接中的说明设置终结点的格式：https://{NAME-OF-YOUR-RESOURCE}.cognitiveservices.azure.com/

获取 API 密钥

可以在 Azure 门户中或通过运行以下 Azure CLI 命令找到 API 密钥：

az cognitiveservices account keys list --name "resource-name" --resource-group "resource-group-name"

使用 AzureKeyCredential 创建客户端

若要使用 API 密钥 作为 credential 参数，请将密钥作为字符串传递到 AzureKeyCredential 的实例中。

from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient

endpoint = "https://<resource-name>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")
document_translation_client = DocumentTranslationClient(endpoint, credential)

使用 Azure Active Directory 凭据创建客户端

AzureKeyCredential 本入门指南中的示例使用身份验证，但也可以使用 azure-identity 库通过 Azure Active Directory 进行身份验证。

若要使用如下所示的 DefaultAzureCredential 类型或 Azure SDK 提供的其他凭据类型，请安装包 azure-identity ：

pip install azure-identity

还需要 注册新的 AAD 应用程序，并通过 将角色分配给服务主体来 "Cognitive Services User" 授予对翻译器资源的访问权限。

完成后，将 AAD 应用程序的客户端 ID、租户 ID 和客户端密码的值设置为环境变量：AZURE_CLIENT_ID、、AZURE_TENANT_IDAZURE_CLIENT_SECRET。

from azure.identity import DefaultAzureCredential
from azure.ai.translation.document import DocumentTranslationClient
credential = DefaultAzureCredential()

document_translation_client = DocumentTranslationClient(
    endpoint="https://<resource-name>.cognitiveservices.azure.com/",
    credential=credential
)

关键概念

文档翻译服务要求将文件上传到Azure Blob 存储源容器，并提供可在其中写入已翻译文档的目标容器。 有关此设置的其他信息，请参阅服务文档：

• 使用文档设置Azure Blob 存储容器
• （可选）应用 术语表 或 自定义模型进行翻译
• 使用以下任一选项允许访问存储帐户：
  • 将 SAS 令牌生成到具有相应权限的容器 (或文件)
  • 创建和使用 托管标识 来授予对存储帐户的访问权限

DocumentTranslationClient

与文档翻译客户端库的交互从 实例 DocumentTranslationClient开始。 客户端为以下项提供操作：

• 创建翻译操作来翻译源容器中的文档 () ，并将结果写入目标容器 () 。
• 检查翻译操作中各个文档的状态并监视每个文档的进度。
• 枚举所有过去和当前翻译操作。
• 确定支持的术语表和文档格式。

翻译输入

begin_translation可以通过两种不同的方式提供对客户端方法的输入：

1. 包含文档的单个源容器可以翻译成其他语言：

from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient

document_translation_client = DocumentTranslationClient("<endpoint>", AzureKeyCredential("<api_key>"))
poller = document_translation_client.begin_translation("<sas_url_to_source>", "<sas_url_to_target>", "<target_language>")

2. 或者，可以为每个源提供其自己的目标。

from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient, DocumentTranslationInput, TranslationTarget

my_input = [
    DocumentTranslationInput(
        source_url="<sas_url_to_source_A>",
        targets=[
            TranslationTarget(target_url="<sas_url_to_target_fr>", language="fr"),
            TranslationTarget(target_url="<sas_url_to_target_de>", language="de")
        ]
    ),
    DocumentTranslationInput(
        source_url="<sas_url_to_source_B>",
        targets=[
            TranslationTarget(target_url="<sas_url_to_target_fr>", language="fr"),
            TranslationTarget(target_url="<sas_url_to_target_de>", language="de")
        ]
    ),
    DocumentTranslationInput(
        source_url="<sas_url_to_source_C>",
        targets=[
            TranslationTarget(target_url="<sas_url_to_target_fr>", language="fr"),
            TranslationTarget(target_url="<sas_url_to_target_de>", language="de")
        ]
    )
]

document_translation_client = DocumentTranslationClient("<endpoint>", AzureKeyCredential("<api_key>"))
poller = document_translation_client.begin_translation(my_input)

注意：每个目标语言的target_url必须是唯一的。

若要翻译文件夹下的文档或仅翻译某些文档，请参阅 sample_begin_translation_with_filters.py。 有关所有 支持的语言，请参阅服务文档。

Long-Running操作

长时间运行的操作包括发送到服务以启动操作的初始请求，然后每隔一段时间轮询服务以确定操作是否已完成或失败，以及是否成功获取结果。

转换文档的方法建模为长时间运行的操作。 客户端公开返回 begin_<method-name>DocumentTranslationLROPoller 或 AsyncDocumentTranslationLROPoller的方法。 调用方应通过对从 begin_<method-name> 方法返回的轮询器对象调用 result() 来等待操作完成。 提供了示例代码片段来说明如何使用长时间运行的操作 。

示例

以下部分提供了几个代码片段，涵盖了一些最常见的文档翻译任务，包括：

• 翻译文档
• 转换多个输入
• 列出翻译操作

翻译文档

将源容器中的所有文档转换为目标容器。 若要翻译文件夹下的文档或仅翻译某些文档，请参阅 sample_begin_translation_with_filters.py。

from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient

endpoint = "https://<resource-name>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")
source_container_sas_url_en = "<sas-url-en>"
target_container_sas_url_es = "<sas-url-es>"

document_translation_client = DocumentTranslationClient(endpoint, credential)

poller = document_translation_client.begin_translation(source_container_sas_url_en, target_container_sas_url_es, "es")

result = poller.result()

print(f"Status: {poller.status()}")
print(f"Created on: {poller.details.created_on}")
print(f"Last updated on: {poller.details.last_updated_on}")
print(f"Total number of translations on documents: {poller.details.documents_total_count}")

print("\nOf total documents...")
print(f"{poller.details.documents_failed_count} failed")
print(f"{poller.details.documents_succeeded_count} succeeded")

for document in result:
    print(f"Document ID: {document.id}")
    print(f"Document status: {document.status}")
    if document.status == "Succeeded":
        print(f"Source document location: {document.source_document_url}")
        print(f"Translated document location: {document.translated_document_url}")
        print(f"Translated to language: {document.translated_to}\n")
    else:
        print(f"Error Code: {document.error.code}, Message: {document.error.message}\n")

转换多个输入

开始将多个源容器中的文档翻译成不同语言的多个目标容器。

from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient, DocumentTranslationInput, TranslationTarget

endpoint = "https://<resource-name>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")
source_container_sas_url_de = "<sas-url-de>"
source_container_sas_url_en = "<sas-url-en>"
target_container_sas_url_es = "<sas-url-es>"
target_container_sas_url_fr = "<sas-url-fr>"
target_container_sas_url_ar = "<sas-url-ar>"

document_translation_client = DocumentTranslationClient(endpoint, credential)

poller = document_translation_client.begin_translation(
    [
        DocumentTranslationInput(
            source_url=source_container_sas_url_en,
            targets=[
                TranslationTarget(target_url=target_container_sas_url_es, language="es"),
                TranslationTarget(target_url=target_container_sas_url_fr, language="fr"),
            ],
        ),
        DocumentTranslationInput(
            source_url=source_container_sas_url_de,
            targets=[
                TranslationTarget(target_url=target_container_sas_url_ar, language="ar"),
            ],
        )
    ]
)

result = poller.result()

for document in result:
    print(f"Document ID: {document.id}")
    print(f"Document status: {document.status}")
    if document.status == "Succeeded":
        print(f"Source document location: {document.source_document_url}")
        print(f"Translated document location: {document.translated_document_url}")
        print(f"Translated to language: {document.translated_to}\n")
    else:
        print(f"Error Code: {document.error.code}, Message: {document.error.message}\n")

列出翻译操作

枚举为资源提交的转换操作。

from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient

endpoint = "https://<resource-name>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")

document_translation_client = DocumentTranslationClient(endpoint, credential)

operations = document_translation_client.list_translation_statuses()  # type: ItemPaged[TranslationStatus]

for operation in operations:
    print(f"\nID: {operation.id}")
    print(f"Status: {operation.status}")
    print(f"Created on: {operation.created_on}")
    print(f"Last updated on: {operation.last_updated_on}")
    print(f"Total number of translations on documents: {operation.documents_total_count}")
    print(f"Total number of characters charged: {operation.total_characters_charged}")

    print("Of total documents...")
    print(f"{operation.documents_failed_count} failed")
    print(f"{operation.documents_succeeded_count} succeeded")
    print(f"{operation.documents_canceled_count} canceled")

若要了解如何将文档翻译客户端库与 Azure 存储 Blob 配合使用来上传文档、为容器创建 SAS 令牌以及下载已完成翻译的文档，请参阅此示例。 请注意，需要安装 azure-storage-blob 库才能运行此示例。

高级主题

以下部分提供有关某些高级翻译功能（例如术语表和自定义翻译模型）的一些见解。

词汇表

术语表是特定于域的字典。 例如，如果要翻译一些与医学相关的文档，则可能需要支持在标准翻译词典中找不到的医学领域的许多字词、术语和成语，或者只需要特定的翻译。 这就是文档翻译支持术语表的原因。

如何创建术语表文件

文档翻译支持以下格式的术语表：

文件类型	扩展名	说明	示例
制表符分隔值/TAB	.tsv、.tab	在维基百科上阅读详细信息	glossary_sample.tsv
逗号分隔值	.csv	在维基百科上阅读详细信息	glossary_sample.csv
本地化交换文件格式	.xlf、.xliff	在维基百科上阅读详细信息	glossary_sample.xlf

在此处查看所有支持的格式。

如何在文档翻译中使用术语表

若要将术语表与文档翻译配合使用，首先需要将术语表文件上传到 Blob 容器，然后提供文件的 SAS URL ，如代码示例sample_translation_with_glossaries.py 中所示。

自定义翻译模型

可以使用自己的自定义 Azure 计算机/深度学习模型，而不是使用文档翻译引擎进行翻译。

如何创建自定义翻译模型

有关如何创建、预配和部署自己的自定义 Azure 翻译模型的详细信息，请按照以下说明操作： 生成、部署和使用自定义模型进行翻译

如何将自定义翻译模型与文档翻译配合使用

若要将自定义翻译模型与文档翻译配合使用，首先需要创建和部署模型，然后按照用于文档翻译 的代码示例sample_translation_with_custom_model.py 进行操作。

疑难解答

常规

文档翻译客户端库将引发 Azure Core 中定义的异常。

日志记录

此库使用标准 日志记录 库进行日志记录。

有关 HTTP 会话 (URL、标头等的基本信息，) 是在级别记录的 INFO 。

可以使用关键字参数在客户端上或按操作logging_enable启用详细DEBUG级别日志记录，包括请求/响应正文和未处理标头。

请参阅此处提供示例的完整 SDK 日志记录文档。

可选配置

可选关键字参数可以在客户端和每个操作级别传入。 azure-core 参考文档 介绍了重试、日志记录、传输协议等的可用配置。

后续步骤

以下部分提供了几个代码片段，说明了文档翻译 Python 客户端库中使用的常见模式。 可以在示例目录下找到更多 示例 。

更多示例代码

这些代码示例演示 Azure 文档翻译客户端库的常见方案操作。

• 客户端身份验证： sample_authentication.py
• 开始翻译文档： sample_begin_translation.py
• 使用多个输入进行翻译： sample_translate_multiple_inputs.py
• 检查文档的状态： sample_check_document_statuses.py
• 列出所有提交的翻译操作： sample_list_translations.py
• 将自定义术语表应用于翻译： sample_translation_with_glossaries.py
• 使用 Azure Blob 存储 设置翻译资源：sample_translation_with_azure_blob.py

异步示例

此库还包括一组完整的异步 API。 若要使用它们，必须先安装异步传输，例如 aiohttp。 异步客户端位于 命名空间下 azure.ai.translation.document.aio 。

• 客户端身份验证： sample_authentication_async.py
• 开始翻译文档： sample_begin_translation_async.py
• 使用多个输入进行转换： sample_translate_multiple_inputs_async.py
• 检查文档的状态： sample_check_document_statuses_async.py
• 列出所有提交的翻译操作： sample_list_translations_async.py
• 将自定义术语表应用于翻译： sample_translation_with_glossaries_async.py
• 使用 Azure Blob 存储 设置翻译资源：sample_translation_with_azure_blob_async.py

其他文档

有关 Azure 认知服务文档翻译的更多文档，请参阅有关 docs.microsoft.com 的文档翻译文档 。

贡献

本项目欢迎贡献和建议。 大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。 有关详细信息，请访问 cla.microsoft.com。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。 直接按机器人提供的说明操作。 只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与 联系。