azure.ai.translation.document.aio package¶

class azure.ai.translation.document.aio.DocumentTranslationClient(endpoint: str, credential: azure.core.credentials.AzureKeyCredential, **kwargs: Any)[source]¶

DocumentTranslationClient is your interface to the Document Translation service. Use the client to translate whole documents while preserving source document structure and text formatting.

Parameters

endpoint (str) – Supported Document Translation endpoint (protocol and hostname, for example: https://<resource-name>.cognitiveservices.azure.com/).
credential (AzureKeyCredential) – Credential needed for the client to connect to Azure. Currently only API key authentication is supported.

Keyword Arguments

api_version (str or DocumentTranslationApiVersion) – The API version of the service to use for requests. It defaults to the latest service version. Setting to an older version may result in reduced feature compatibility.

Example:

Creating the DocumentTranslationClient with an endpoint and API key.¶

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

endpoint = os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"]
key = os.environ["AZURE_DOCUMENT_TRANSLATION_KEY"]

document_translation_client = DocumentTranslationClient(endpoint, AzureKeyCredential(key))

async cancel_job(job_id: str, **kwargs: Any) → None [source]¶

Cancel a currently processing or queued job.

A job will not be cancelled if it is already completed, failed, or cancelling. All documents that have completed translation will not be cancelled and will be charged. If possible, all pending documents will be cancelled.

Parameters: job_id (str) – The translation job ID.
Returns: None
Return type: None
Raises: HttpResponseError or ResourceNotFoundError –

async close() → None [source]¶: Close the DocumentTranslationClient session.

async create_translation_job(inputs: List[azure.ai.translation.document._models.DocumentTranslationInput], **kwargs: Any) → azure.ai.translation.document._models.JobStatusResult[source]¶

Create a document translation job which translates the document(s) in your source container to your TranslationTarget(s) in the given language.

For supported languages and document formats, see the service documentation: https://docs.microsoft.com/azure/cognitive-services/translator/document-translation/overview

Parameters: inputs (List[DocumentTranslationInput]) – A list of translation inputs. Each individual input has a single source URL to documents and can contain multiple TranslationTargets (one for each language) for the destination to write translated documents.
Returns: A JobStatusResult with information on the status of the translation job.
Return type: JobStatusResult
Raises: HttpResponseError –

Example:

Create a translation job.¶

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

endpoint = os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"]
key = os.environ["AZURE_DOCUMENT_TRANSLATION_KEY"]
source_container_url = os.environ["AZURE_SOURCE_CONTAINER_URL"]
target_container_url = os.environ["AZURE_TARGET_CONTAINER_URL"]

client = DocumentTranslationClient(endpoint, AzureKeyCredential(key))
async with client:
    job_result = await client.create_translation_job(inputs=[
            DocumentTranslationInput(
                source_url=source_container_url,
                targets=[
                    TranslationTarget(
                        target_url=target_container_url,
                        language_code="es"
                    )
                ]
            )
        ]
    )  # type: JobStatusResult

async get_document_formats(**kwargs: Any) → List[azure.ai.translation.document._models.FileFormat][source]¶

Get the list of the document formats supported by the Document Translation service.

Returns: A list of supported document formats for translation.
Return type: List[FileFormat]
Raises: HttpResponseError –

async get_document_status(job_id: str, document_id: str, **kwargs: Any) → azure.ai.translation.document._models.DocumentStatusResult[source]¶

Get the status of an individual document within a translation job.

Parameters

job_id (str) – The translation job ID.
document_id (str) – The ID for the document.

Returns

A DocumentStatusResult with information on the status of the document.

Return type

DocumentStatusResult

Raises

HttpResponseError or ResourceNotFoundError –

async get_glossary_formats(**kwargs: Any) → List[azure.ai.translation.document._models.FileFormat][source]¶

Get the list of the glossary formats supported by the Document Translation service.

Returns: A list of supported glossary formats.
Return type: List[FileFormat]
Raises: HttpResponseError –

async get_job_status(job_id: str, **kwargs: Any) → azure.ai.translation.document._models.JobStatusResult[source]¶

Gets the status of a translation job.

The status includes the overall job status, as well as a summary of the documents that are being translated as part of that translation job.

Parameters: job_id (str) – The translation job ID.
Returns: A JobStatusResult with information on the status of the translation job.
Return type: JobStatusResult
Raises: HttpResponseError or ResourceNotFoundError –

list_all_document_statuses(job_id: str, **kwargs: Any) → azure.core.async_paging.AsyncItemPaged[azure.ai.translation.document._models.DocumentStatusResult][source]¶

List all the document statuses under a translation job.

Parameters: job_id (str) – The translation job ID.
Returns: ~azure.core.paging.AsyncItemPaged[DocumentStatusResult]
Return type: AsyncItemPaged
Raises: HttpResponseError –

Example:

List all the document statuses under the translation job.¶

doc_results = client.list_all_document_statuses(job_result.id)  # type: AsyncItemPaged[DocumentStatusResult]
async for document in doc_results:
    print("Document ID: {}".format(document.id))
    print("Document status: {}".format(document.status))
    if document.status == "Succeeded":
        print("Source document location: {}".format(document.source_document_url))
        print("Translated document location: {}".format(document.translated_document_url))
        print("Translated to language: {}\n".format(document.translate_to))
    else:
        print("Error Code: {}, Message: {}\n".format(document.error.code, document.error.message))

list_submitted_jobs(**kwargs: Any) → azure.core.async_paging.AsyncItemPaged[azure.ai.translation.document._models.JobStatusResult][source]¶

List all the submitted translation jobs under the Document Translation resource.

Returns: ~azure.core.paging.AsyncItemPaged[JobStatusResult]
Return type: AsyncItemPaged
Raises: HttpResponseError –

Example:

List all submitted jobs under the resource.¶

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

endpoint = os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"]
key = os.environ["AZURE_DOCUMENT_TRANSLATION_KEY"]

client = DocumentTranslationClient(endpoint, AzureKeyCredential(key))
async with client:
    translation_jobs = client.list_submitted_jobs()  # type: AsyncItemPaged[JobStatusResult]

    async for job in translation_jobs:
        if job.status == "Running":
            job = await client.wait_until_done(job.id)

        print("Job ID: {}".format(job.id))
        print("Job status: {}".format(job.status))
        print("Job created on: {}".format(job.created_on))
        print("Job last updated on: {}".format(job.last_updated_on))
        print("Total number of translations on documents: {}".format(job.documents_total_count))
        print("Total number of characters charged: {}".format(job.total_characters_charged))

        print("\nOf total documents...")
        print("{} failed".format(job.documents_failed_count))
        print("{} succeeded".format(job.documents_succeeded_count))
        print("{} cancelled\n".format(job.documents_cancelled_count))

async wait_until_done(job_id: str, **kwargs: Any) → azure.ai.translation.document._models.JobStatusResult[source]¶

Wait until the translation job is done.

A job is considered “done” when it reaches a terminal state like Succeeded, Failed, Cancelled.

Parameters: job_id (str) – The translation job ID.
Returns: A JobStatusResult with information on the status of the translation job.
Return type: JobStatusResult
Raises: HttpResponseError or ResourceNotFoundError – Will raise if validation fails on the input. E.g. insufficient permissions on the blob containers.

Example:

Create a translation job and wait until it is done.¶

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

endpoint = os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"]
key = os.environ["AZURE_DOCUMENT_TRANSLATION_KEY"]
source_container_url = os.environ["AZURE_SOURCE_CONTAINER_URL"]
target_container_url = os.environ["AZURE_TARGET_CONTAINER_URL"]

client = DocumentTranslationClient(endpoint, AzureKeyCredential(key))

async with client:
    job = await client.create_translation_job(inputs=[
            DocumentTranslationInput(
                source_url=source_container_url,
                targets=[
                    TranslationTarget(
                        target_url=target_container_url,
                        language_code="es"
                    )
                ]
            )
        ]
    )  # type: JobStatusResult

    job_result = await client.wait_until_done(job.id)  # type: JobStatusResult

    print("Job status: {}".format(job_result.status))
    print("Job created on: {}".format(job_result.created_on))
    print("Job last updated on: {}".format(job_result.last_updated_on))
    print("Total number of translations on documents: {}".format(job_result.documents_total_count))

    print("\nOf total documents...")
    print("{} failed".format(job_result.documents_failed_count))
    print("{} succeeded".format(job_result.documents_succeeded_count))