Azure Document Translation客户端库

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

• 将多个大型文件从Azure Blob Storage容器翻译到您选择的目标容器。
• 检查翻译操作中每个文档的翻译状态和进度。
• 应用自定义翻译模型或术语表，以适应您的特定情况。

源代码 | 包（PyPI） | API参考文档 | 产品文档 | 示例

免责声明

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

入门

先决条件

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

安装包

使用pip安装Azure Document Translation客户端库

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

认证客户端

为了与文档翻译功能服务交互，您需要创建客户端实例。实例化客户端对象需要endpoint和credential。

查找端点

您可以使用Azure门户查找您的翻译资源端点。

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

获取API密钥

API密钥可以在Azure门户中找到，或者通过运行以下Azure CLI命令来获取

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"角色分配给服务主体以访问您的翻译资源。

完成后，将Azure AD应用的客户端ID、租户ID和客户端密钥设置为环境变量：AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_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 Storage源容器，并提供一个目标容器，用于写入翻译后的文档。有关设置此内容的更多信息，请参阅服务文档

• 设置Azure Blob Storage容器以存储您的文档
• 可选：应用术语表或翻译自定义模型
• 以下任一选项允许访问您的存储帐户
  • 为容器（或文件）生成适当的权限的SAS令牌
  • 创建并使用托管标识以授予对您的存储帐户的访问权限

DocumentTranslationClient

与Document Translation客户端库的交互从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。有关所有支持的语言的信息，请参阅服务文档。

长时间运行的操作

长时间运行的操作是指由向服务发送的初始请求来启动操作，然后以间隔轮询服务以确定操作是否完成或失败，如果操作成功，则获取结果的操作。

将翻译文档的方法建模为长时间运行的操作。客户端公开了一个返回DocumentTranslationLROPoller或AsyncDocumentTranslationLROPoller的begin_<method-name>方法。调用者应通过在从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")

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

高级主题

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

术语表

术语表是特定领域的字典。例如，如果您想翻译一些与医疗相关的文档，您可能需要支持在标准翻译字典中找不到的许多医疗领域的词汇、术语和成语，或者您只需要特定的翻译。这就是为什么Document Translation支持术语表。

如何创建术语表文件

Document Translation支持以下格式的术语表

文件类型	扩展名	描述	示例
制表符分隔值/TAB	.tsv, .tab	更多信息请参阅维基百科	glossary_sample.tsv
逗号分隔值	.csv	更多信息请参阅维基百科	glossary_sample.csv
本地化交换文件格式	.xlf, .xliff	更多信息请参阅维基百科	glossary_sample.xlf

查看所有支持的格式这里。

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

为了在Document Translation中使用术语表，您首先需要将您的术语表文件上传到Blob容器，然后在代码示例sample_translation_with_glossaries.py中提供文件的SAS URL。

自定义翻译模型

您可以使用自己的自定义Azure机器/深度学习模型进行翻译，而不是使用Document Translation的引擎。

如何创建自定义翻译模型

有关如何创建、配置和部署您自己的自定义Azure翻译模型的更多信息，请按照以下说明操作：构建、部署和使用自定义模型进行翻译

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

为了使用自定义翻译模型与Document Translation，您首先需要创建和部署您的模型，然后按照代码示例sample_translation_with_custom_model.py使用Document Translation。

故障排除

常规

Document Translation客户端库将引发在Azure Core中定义的异常。

日志记录

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

HTTP会话（URL、头等信息）的基本信息以INFO级别进行记录。

详细的DEBUG级别日志记录，包括请求/响应体和未脱敏的头信息，可以通过logging_enable关键字参数在客户端或每个操作中启用。

有关完整SDK日志记录文档和示例，请参阅此处。

可选配置

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

下一步操作

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

更多示例代码

这些代码示例展示了使用Azure Document Translation客户端库的常见场景操作。

• 客户端身份验证：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 Storage设置翻译资源：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 Storage设置翻译资源：sample_translation_with_azure_blob_async.py

其他文档

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

贡献

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

当您提交pull request时，CLA-bot会自动确定您是否需要提供CLA，并适当装饰PR（例如，标签、注释）。只需遵循机器人提供的说明即可。您只需在整个使用我们CLA的存储库中这样做一次。

此项目已采用Microsoft开源行为准则。有关更多信息，请参阅行为准则FAQ或通过opencode@microsoft.com联系，提出任何额外的问题或评论。

版本历史记录

1.0.0 (2022-06-07)

破坏性更改

• 更改：将 begin_translation 参数 target_language_code 重命名为 target_language。
• 更改：将 begin_translation 的关键字参数 source_language_code 重命名为 source_language。
• 更改：将 DocumentTranslationInput 的关键字参数和属性 source_language_code 重命名为 source_language。
• 更改：将 TranslationTarget 的关键字参数和属性 language_code 重命名为 language。
• 更改：将 TranslationStatus 属性 documents_not_yet_started_count 重命名为 documents_not_started_count。
• 删除：从 list_translation_statuses 和 list_document_statuses 中移除了关键字参数 results_per_page。

1.0.0b6 (2022-02-08)

其他更改

• 不再支持 Python 2.7。请使用 Python 版本 3.6 或更高版本。

1.0.0b5 (2021-09-08)

破坏性更改

• 更改：将 list_all_translation_statuses 重命名为 list_translation_statuses。
• 更改：将 list_all_document_statuses 重命名为 list_document_statuses。
• 更改：将 TranslationStatus 属性 documents_cancelled_count 重命名为 documents_canceled_count。
• 更改：将 FileFormat 重命名为 DocumentTranslationFileFormat。
• 更改：操作状态 Cancelled 和 Cancelling 分别重命名为 Canceled 和 Canceling。

已修复的 bug

• 现在，轮询对象的 details 下的 id 操作正确填充。

1.0.0b4 (2021-08-10)

新增功能

• 现在，begin_translation(source, target, target_language_code) 的单个翻译输入版本接受关键字参数 storage_type、glossaries、category_id、prefix、suffix 和 source_language_code。

破坏性更改

• 更改：将 list_all_document_statuses 中的关键字参数 translated_before 和 translated_after 分别重命名为 created_before 和 created_after。
• 更改：将 list_all_translation_statuses 和 list_all_document_statuses 中的排序查询选项 createdDateTimeUtc 重命名为 created_on。

1.0.0b3 (2021-07-07)

重大更改

• TranslationStatusResult 已重命名为 TranslationStatus。
• DocumentStatusResult 已重命名为 DocumentStatus。
• get_document_formats 已重命名为 get_supported_document_formats。
• get_glossary_formats 已重命名为 get_supported_glossary_formats。

1.0.0b2 (2021-06-08)

此版本的 SDK 默认使用最新支持的服务版本，当前为 v1.0。

重大更改

• 已删除 create_translation_job 并用 begin_translation 替换，后者采用长运行操作 (LRO) 方法。客户端方法现在返回一个 DocumentTranslationLROPoller（或 AsyncDocumentTranslationLROPoller）以开始长运行操作。可以在轮询对象上调用 .result() 来等待翻译完成。有关 LRO 的更多信息，请参阅 README。
• LRO 完成后，begin_translation 现在返回一个 DocumentStatusResult 分页。所有作业级元数据都可以在 poller.details 中找到。
• 从 JobStatusResult 和 DocumentStatusResult 中删除了 has_completed。请使用 poller.done() 来检查翻译是否已完成。
• 已删除客户端方法 wait_until_done。请使用 poller.result() 来等待 LRO 完成。
• 客户端方法 list_submitted_jobs 已重命名为 list_all_translation_statuses。
• 客户端方法 get_job_status 已重命名为 get_translation_status。
• 客户端方法 cancel_job 已重命名为 cancel_translation。
• get_translation_status、cancel_translation、list_all_document_statuses 和 get_document_status 中的参数 job_id 已重命名为 translation_id。
• JobStatusResult 已更名为 TranslationStatusResult。
• DocumentStatusResult 属性 translate_to 已更名为 translated_to

新增功能

• 现在支持使用 azure-identity 凭据进行身份验证。
  • 有关更多信息，请参阅Azure Identity 文档。
• 向 list_all_document_statuses 和 list_submitted_jobs 添加了分页和筛选选项。
• begin_translation 的输入现在可以接受参数 inputs 作为 List[DocumentTranslationInput] 来执行多个翻译，或者接受参数 source_url、target_url 和 target_language_code 来执行单个文档的翻译。

依赖项更新

• 该软件包需要 azure-core 版本 1.14.0 或更高版本。

1.0.0b1 (2021-04-06)

这是 azure-ai-translation-document 客户端库的第一个 beta 版本，针对 1.0-preview.1 版本的文档翻译服务。该软件包的文档和示例演示了新的 API。