Package: azure-ai-translation-document
Azure Document Translation client library for PythonAzure Cognitive Services Document Translation is a cloud service that can be used to translate multiple and complex documents across languages and dialects while preserving original document structure and data format.
Use the client library for Document Translation to:Translate numerous, large files from an Azure Blob Storage container to a target container in your language of choice.Check the translation status and progress of each document in the translation operation.Apply a custom translation model or glossaries to tailor translation to your specific case.Source code|Package (PyPI)|API reference documentation|Product documentation|SamplesDisclaimerAzure SDK Python packages support for Python 2.7 has ended 01 January 2022. For more information and questions, please refer tohttps://github.com/Azure/azure-sdk-for-python/issues/20691Getting startedPrerequisitesPython 3.6 or later is required to use this package.You must have anAzure subscriptionand aTranslator resourceto use this package.Install the packageInstall the Azure Document Translation client library for Python withpip:pipinstallazure-ai-translation-documentNote: This version of the client library defaults to the v1.0 version of the serviceCreate a Translator resourceThe Document Translation feature supportssingle-service accessonly.
To access the service, create a Translator resource.You can create the resource usingOption 1:Azure PortalOption 2:Azure CLI.
Below is an example of how you can create a Translator resource using the CLI:# Create a new resource group to hold the Translator resource -# if using an existing resource group, skip this stepazgroupcreate--namemy-resource-group--locationwestus2# Create document translationazcognitiveservicesaccountcreate\--namedocument-translation-resource\--custom-domaindocument-translation-resource\--resource-groupmy-resource-group\--kindTextTranslation\--skuS1\--locationwestus2\--yesAuthenticate the clientIn order to interact with the Document Translation feature service, you will need to create an instance of a client.
Anendpointandcredentialare necessary to instantiate the client object.Looking up the endpointYou can find the endpoint for your Translator resource using theAzure Portal.Note that the service requires a custom domain endpoint. Follow the instructions in the above link to format your endpoint:
https://{NAME-OF-YOUR-RESOURCE}.cognitiveservices.azure.com/Get the API keyThe API key can be found in the Azure Portal or by running the following Azure CLI command:az cognitiveservices account keys list --name "resource-name" --resource-group "resource-group-name"Create the client with AzureKeyCredentialTo use anAPI keyas thecredentialparameter,
pass the key as a string into an instance ofAzureKeyCredential.fromazure.core.credentialsimportAzureKeyCredentialfromazure.ai.translation.documentimportDocumentTranslationClientendpoint="https://<resource-name>.cognitiveservices.azure.com/"credential=AzureKeyCredential("<api_key>")document_translation_client=DocumentTranslationClient(endpoint,credential)Create the client with an Azure Active Directory credentialAzureKeyCredentialauthentication is used in the examples in this getting started guide, but you can also
authenticate with Azure Active Directory using theazure-identitylibrary.To use theDefaultAzureCredentialtype shown below, or other credential types provided
with the Azure SDK, please install theazure-identitypackage:pip install azure-identityYou will also need toregister a new AAD application and grant accessto your
Translator resource by assigning the"Cognitive Services User"role to your service principal.Once completed, set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables:AZURE_CLIENT_ID,AZURE_TENANT_ID,AZURE_CLIENT_SECRET.fromazure.identityimportDefaultAzureCredentialfromazure.ai.translation.documentimportDocumentTranslationClientcredential=DefaultAzureCredential()document_translation_client=DocumentTranslationClient(endpoint="https://<resource-name>.cognitiveservices.azure.com/",credential=credential)Key conceptsThe Document Translation service requires that you upload your files to an Azure Blob Storage source container and provide
a target container where the translated documents can be written. Additional information about setting this up can be found in
the service documentation:Set up Azure Blob Storage containerswith your documentsOptionally applyglossariesor acustom model for translationAllow access to your storage account with either of the following options:GenerateSAS tokensto your containers (or files) with the appropriatepermissionsCreate and use amanaged identityto grant access to your storage accountDocumentTranslationClientInteraction with the Document Translation client library begins with an instance of theDocumentTranslationClient.
The client provides operations for:Creating a translation operation to translate documents in your source container(s) and write results to you target container(s).Checking the status of individual documents in the translation operation and monitoring each document's progress.Enumerating all past and current translation operations.Identifying supported glossary and document formats.Translation InputInput to thebegin_translationclient method can be provided in two different ways:A single source container with documents can be translated to a different language:fromazure.core.credentialsimportAzureKeyCredentialfromazure.ai.translation.documentimportDocumentTranslationClientdocument_translation_client=DocumentTranslationClient("<endpoint>",AzureKeyCredential("<api_key>"))poller=document_translation_client.begin_translation("<sas_url_to_source>","<sas_url_to_target>","<target_language>")Or multiple different sources can be provided each with their own targets.fromazure.core.credentialsimportAzureKeyCredentialfromazure.ai.translation.documentimportDocumentTranslationClient,DocumentTranslationInput,TranslationTargetmy_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)Note: the target_url for each target language must be unique.To translate documents under a folder, or only translate certain documents, seesample_begin_translation_with_filters.py.
See the service documentation for allsupported languages.Long-Running OperationsLong-running operations are operations which consist of an initial request sent to the service to start an operation,
followed by polling the service at intervals to determine whether the operation has completed or failed, and if it has
succeeded, to get the result.Methods that translate documents are modeled as long-running operations.
The client exposes abegin_<method-name>method that returns aDocumentTranslationLROPollerorAsyncDocumentTranslationLROPoller. Callers should wait
for the operation to complete by callingresult()on the poller object returned from thebegin_<method-name>method.
Sample code snippets are provided to illustrate using long-running operationsbelow.ExamplesThe following section provides several code snippets covering some of the most common Document Translation tasks, including:Translate your documentsTranslate multiple inputsList translation operationsTranslate your documentsTranslate all the documents in your source container to the target container. To translate documents under a folder, or only translate certain documents, seesample_begin_translation_with_filters.py.fromazure.core.credentialsimportAzureKeyCredentialfromazure.ai.translation.documentimportDocumentTranslationClientendpoint="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")fordocumentinresult:print(f"Document ID:{document.id}")print(f"Document status:{document.status}")ifdocument.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")Translate multiple inputsBegin translating with documents in multiple source containers to multiple target containers in different languages.fromazure.core.credentialsimportAzureKeyCredentialfromazure.ai.translation.documentimportDocumentTranslationClient,DocumentTranslationInput,TranslationTargetendpoint="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()fordocumentinresult:print(f"Document ID:{document.id}")print(f"Document status:{document.status}")ifdocument.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")List translation operationsEnumerate over the translation operations submitted for the resource.fromazure.core.credentialsimportAzureKeyCredentialfromazure.ai.translation.documentimportDocumentTranslationClientendpoint="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]foroperationinoperations: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")To see how to use the Document Translation client library with Azure Storage Blob to upload documents, create SAS tokens
for your containers, and download the finished translated documents, see thissample.
Note that you will need to install theazure-storage-bloblibrary to run this sample.Advanced TopicsThe following section provides some insights for some advanced translation features such as glossaries and custom translation models.GlossariesGlossaries are domain-specific dictionaries. For example, if you want to translate some medical-related documents, you may need support for the many words, terminology, and idioms in the medical field which you can't find in the standard translation dictionary, or you simply need specific translation. This is why Document Translation provides support for glossaries.How To Create Glossary FileDocument Translation supports glossaries in the following formats:File TypeExtensionDescriptionSamplesTab-Separated Values/TAB.tsv, .tabRead more onwikipediaglossary_sample.tsvComma-Separated Values.csvRead more onwikipediaglossary_sample.csvLocalization Interchange File Format.xlf, .xliffRead more onwikipediaglossary_sample.xlfView all supported formatshere.How Use Glossaries in Document TranslationIn order to use glossaries with Document Translation, you first need to upload your glossary file to a blob container, and then provide the SAS URL to the file as in the code samplessample_translation_with_glossaries.py.Custom Translation ModelsInstead of using Document Translation's engine for translation, you can use your own custom Azure machine/deep learning model.How To Create a Custom Translation ModelFor more info on how to create, provision, and deploy your own custom Azure translation model, please follow the instructions here:Build, deploy, and use a custom model for translationHow To Use a Custom Translation Model With Document TranslationIn order to use a custom translation model with Document Translation, you first
need to create and deploy your model, then follow the code samplesample_translation_with_custom_model.pyto use with Document Translation.TroubleshootingGeneralDocument Translation client library will raise exceptions defined inAzure Core.LoggingThis library uses the standardlogginglibrary for logging.Basic information about HTTP sessions (URLs, headers, etc.) is logged atINFOlevel.DetailedDEBUGlevel logging, including request/response bodies andunredactedheaders, can be enabled on the client or per-operation with thelogging_enablekeyword argument.See full SDK logging documentation with exampleshere.Optional ConfigurationOptional keyword arguments can be passed in at the client and per-operation level.
The azure-corereference documentationdescribes available configurations for retries, logging, transport protocols, and more.Next stepsThe following section provides several code snippets illustrating common patterns used in the Document Translation Python client library.
More samples can be found under thesamplesdirectory.More sample codeThese code samples show common scenario operations with the Azure Document Translation client library.Client authentication:sample_authentication.pyBegin translating documents:sample_begin_translation.pyTranslate with multiple inputs:sample_translate_multiple_inputs.pyCheck the status of documents:sample_check_document_statuses.pyList all submitted translation operations:sample_list_translations.pyApply a custom glossary to translation:sample_translation_with_glossaries.pyUse Azure Blob Storage to set up translation resources:sample_translation_with_azure_blob.pyAsync samplesThis library also includes a complete set of async APIs. To use them, you must
first install an async transport, such asaiohttp. Async clients
are found under theazure.ai.translation.document.aionamespace.Client authentication:sample_authentication_async.pyBegin translating documents:sample_begin_translation_async.pyTranslate with multiple inputs:sample_translate_multiple_inputs_async.pyCheck the status of documents:sample_check_document_statuses_async.pyList all submitted translation operations:sample_list_translations_async.pyApply a custom glossary to translation:sample_translation_with_glossaries_async.pyUse Azure Blob Storage to set up translation resources:sample_translation_with_azure_blob_async.pyAdditional documentationFor more extensive documentation on Azure Cognitive Services Document Translation, see theDocument Translation documentationon docs.microsoft.com.ContributingThis project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visitcla.microsoft.com.When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.This project has adopted theMicrosoft Open Source Code of Conduct. For more information see theCode of Conduct FAQor contactopencode@microsoft.comwith any additional questions or comments.Release History1.0.0 (2022-06-07)Breaking ChangesChanged:begin_translationparametertarget_language_codehas been renamed totarget_language.Changed:begin_translationkeyword-only argumentsource_language_codehas been renamed tosource_language.Changed:DocumentTranslationInputkeyword-only argument and propertysource_language_codehas been renamed tosource_language.Changed:TranslationTargetkeyword-only argument and propertylanguage_codehas been renamed tolanguage.Changed:TranslationStatuspropertydocuments_not_yet_started_counthas been renamed todocuments_not_started_count.Removed:results_per_pagekeyword-only argument fromlist_translation_statusesandlist_document_statuses.1.0.0b6 (2022-02-08)Other ChangesPython 2.7 is no longer supported. Please use Python version 3.6 or later.1.0.0b5 (2021-09-08)Breaking ChangesChanged:list_all_translation_statuseshas been renamed tolist_translation_statusesChanged:list_all_document_statuseshas been renamed tolist_document_statusesChanged:TranslationStatuspropertydocuments_cancelled_counthas been renamed todocuments_canceled_countChanged:FileFormathas been renamed toDocumentTranslationFileFormatChanged: Operation statusesCancelledandCancellinghave been renamed toCanceledandCanceling, respectively.Bugs FixedThe operationidunderdetailsof the poller object now populates correctly.1.0.0b4 (2021-08-10)Features AddedThe single translation input version ofbegin_translation(source, target, target_language_code)now accepts keyword argumentsstorage_type,glossaries,category_id,prefix,suffix, andsource_language_code.Breaking ChangesChanged: renamed kwargstranslated_beforeandtranslated_aftertocreated_beforeandcreated_after, respectively,
forlist_all_document_statuses.Changed: renamedorder_bysorting query optioncreatedDateTimeUtctocreated_onforlist_all_translation_statusesandlist_all_document_statuses.1.0.0b3 (2021-07-07)Breaking changesTranslationStatusResultwas renamed toTranslationStatus.DocumentStatusResultwas renamed toDocumentStatus.get_document_formatswas renamed toget_supported_document_formats.get_glossary_formatswas renamed toget_supported_glossary_formats.1.0.0b2 (2021-06-08)This version of the SDK defaults to the latest supported service version, which currently is v1.0Breaking changescreate_translation_jobwas removed and replaced withbegin_translationwhich follows a long-running operation (LRO)
approach. The client method now returns aDocumentTranslationLROPoller(orAsyncDocumentTranslationLROPoller) to begin the
long-running operation. A call to.result()can be made on the poller object to wait until the translation is complete.
See theREADMEfor more information about LROs.Upon completion of the LRO,begin_translationnow returns a pageable ofDocumentStatusResult. All job-level metadata can still
be found onpoller.details.has_completedhas been removed fromJobStatusResultandDocumentStatusResult. Usepoller.done()to check if the
translation has completed.Client methodwait_until_donehas been removed. Usepoller.result()to wait for the LRO to complete.Client methodlist_submitted_jobshas been renamed tolist_all_translation_statuses.Client methodget_job_statushas been renamed toget_translation_status.Client methodcancel_jobhas been renamed tocancel_translation.Parameterjob_idwas renamed totranslation_idforget_translation_status,cancel_translation,list_all_document_statuses, andget_document_status.JobStatusResulthas been renamed toTranslationStatusResult.DocumentStatusResultpropertytranslate_tohas been renamed totranslated_toNew featuresAuthentication usingazure-identitycredentials now supported.see theAzure Identity documentationfor more information.Added paging and filtering options tolist_all_document_statusesandlist_submitted_jobs.The input tobegin_translationnow accepts either the parameterinputsas aList[DocumentTranslationInput]to
perform multiple translations, or the parameterssource_url,target_url, andtarget_language_codeto perform a
single translation of your documents.Dependency updatesPackage requiresazure-coreversion 1.14.0 or greater.1.0.0b1 (2021-04-06)This is the first beta package of the azure-ai-translation-document client library that targets the Document Translation
service version1.0-preview.1. This package's documentation and samples demonstrate the new API.