適用于 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

開始使用

Prerequisites

• 需要 Python 3.6 或更新版本才能使用此套件。
• 您必須擁有 Azure 訂 用帳戶和 翻譯工具資源 ，才能使用此套件。

安裝套件

使用 pip安裝適用于 Python 的 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

驗證用戶端

若要與檔翻譯功能服務互動，您必須建立用戶端的實例。 必須有 端點 和 認證 ，才能具現化用戶端物件。

查閱端點

您可以使用 Azure入口網站來尋找翻譯工具資源的端點。

請注意，服務需要自訂網域端點。 請遵循上述連結中的指示來格式化端點：HTTPs://{NAME-OF-YOUR-RESOURCE}.cognitiveservices.azure.com/

取得 API 金鑰

您可以在 Azure 入口網站中找到 API 金鑰，或執行下列 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" 給服務主體，以授與翻譯工具資源的存取權。

完成後，請將 AAD 應用程式的用戶端識別碼、租使用者識別碼和用戶端密碼的值設定為環境變數： 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 的方法。 呼叫端應該等候作業完成，方法是 result() 呼叫從 方法傳回的 begin_<method-name> 輪詢器物件。 提供範例程式碼片段來說明如何使用長時間執行的作業。

範例

下一節提供數個程式碼片段，涵蓋一些最常見的檔翻譯工作，包括：

• 翻譯您的檔
• 翻譯多個輸入
• 列出翻譯作業

翻譯您的檔

將來源容器中的所有檔轉譯為目標容器。 若要翻譯資料夾下的檔，或只翻譯特定檔，請參閱 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 層級記錄。

詳細的 DEBUG 層級記錄，包括要求/回應主體和 未處理的 標頭，都可以在 logging_enable 用戶端上或使用 關鍵字引數來啟用每個作業。

如需完整的 SDK 記錄檔，請參閱 這裡範例。

選用組態

選擇性關鍵字引數可以在用戶端和每個作業層級傳入。 azure 核心 參考檔 說明重試、記錄、傳輸通訊協定等可用的組態。

下一步

下一節提供數個程式碼片段，說明文件翻譯 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 Bot 會自動判斷您是否需要提供 CLA，並適當地裝飾 PR (例如標籤、註解)。 請遵循 bot 提供的指示。 您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。

此專案採用 Microsoft Open Source Code of Conduct (Microsoft 開放原始碼管理辦法)。 如需詳細資訊，請參閱管理辦法常見問題集，如有任何其他問題或意見請連絡 opencode@microsoft.com。