Install and run Azure AI Translator container

Containers enable you to host the Azure AI Translator API on your own infrastructure. The container image includes all libraries, tools, and dependencies needed to run an application consistently in any private, public, or personal computing environment. If your security or data governance requirements can't be fulfilled by calling Azure AI Translator API remotely, containers are a good option.

In this article, learn how to install and run the Translator container online with Docker API. The Azure AI Translator container supports the following operations:

• Text Translation. Translate the contextual meaning of words or phrases from supported source to supported target language in real time. For more information, see Container: translate text.

• 🆕 Text Transliteration. Convert text from one language script or writing system to another language script or writing system in real time. For more information, see Container: transliterate text.

• 🆕 Document translation (preview). Synchronously translate documents while preserving structure and format in real time. For more information, see Container:translate documents.

Prerequisites

To get started, you need the following resources, gated access approval, and tools:

Azure resources

• An active Azure subscription. If you don't have one, you can create a free 12-month account.

• An approved access request to either a Translator connected container or Translator disconnected container.

• An Azure AI Translator resource (not a multi-service Azure AI services resource) created under the approved subscription ID. You need the API key and endpoint URI associated with your resource. Both values are required to start the container and can be found on the resource overview page in the Azure portal.

  • For Translator connected containers, select the S1 pricing tier.

    

  • For Translator disconnected containers, select Commitment tier disconnected containers as your pricing tier. You only see the option to purchase a commitment tier if your disconnected container access request is approved.

    

Docker tools

You should have a basic understanding of Docker concepts like registries, repositories, containers, and container images, as well as knowledge of basic docker terminology and commands. For a primer on Docker and container basics, see the Docker overview.

Host computer requirements

The host is an x64-based computer that runs the Docker container. It can be a computer on your premises or one of these Docker hosting service in Azure:

• Azure Kubernetes Service.
• Azure Container Instances.
• A Kubernetes cluster deployed to Azure Stack. For more information, see Deploy Kubernetes to Azure Stack.

Recommended CPU cores and memory

The following table describes the minimum and recommended specifications and the allowable Transactions Per Second (TPS) for each container.

• Each core must be at least 2.6 gigahertz (GHz) or faster.

• For every language pair, 2 GB of memory is recommended.

• In addition to baseline requirements, 4 GB of memory for every concurrent document processing.

  Tip

  You can use the docker images command to list your downloaded container images. For example, the following command lists the ID, repository, and tag of each downloaded container image, formatted as a table:

   docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"
  
   IMAGE ID         REPOSITORY                TAG
   <image-id>       <repository-path/name>    <tag-name>
  

Required input

All Azure AI containers require the following input values:

• EULA accept setting. You must have an end-user license agreement (EULA) set with a value of Eula=accept.

• API key and Endpoint URL. The API key is used to start the container. You can retrieve the API key and Endpoint URL values by navigating to your Azure AI Translator resource Keys and Endpoint page and selecting the Copy to clipboard icon.

• If you're translating documents, be sure to use the document translation endpoint.

Billing

• Queries to the container are billed at the pricing tier of the Azure resource used for the API Key.

• You're billed for each container instance used to process your documents and images.

• The docker run command downloads an image from Microsoft Artifact Registry and starts the container when all three of the following options are provided with valid values:

Connecting to Azure

• The container billing argument values allow the container to connect to the billing endpoint and run.

• The container reports usage about every 10 to 15 minutes. If the container doesn't connect to Azure within the allowed time window, the container continues to run, but doesn't serve queries until the billing endpoint is restored.

• A connection is attempted 10 times at the same time interval of 10 to 15 minutes. If it can't connect to the billing endpoint within the 10 tries, the container stops serving requests. See the Azure AI container FAQ for an example of the information sent to Microsoft for billing.

Container images and tags

The Azure AI services container images can be found in the Microsoft Artifact Registry catalog. Azure AI Translator container resides within the azure-cognitive-services/translator repository and is named text-translation. The fully qualified container image name is mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest.

To use the latest version of the container, use the latest tag. You can view the full list of Azure AI services Text Translation version tags on MCR.

Use containers

Select a tab to choose your Azure AI Translator container environment:

docker run --rm -it -p 5000:5000 --memory 12g --cpus 4 \
-v /mnt/d/TranslatorContainer:/usr/local/models \
-e apikey={API_KEY} \
-e eula=accept \
-e billing={ENDPOINT_URI} \
-e Languages=en,fr,es,ar,ru  \
mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest

  curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-HANS" -H "Content-Type: application/json" -d "[{'Text':'Hello, what is your name?'}]"

docker run --rm -it -p 5000:5000 \

-v {MODEL_MOUNT_PATH} \

-v {LICENSE_MOUNT_PATH} \

-e Mounts:License={CONTAINER_LICENSE_DIRECTORY} \

-e DownloadLicense=true \

-e eula=accept \

-e billing={ENDPOINT_URI} \

-e apikey={API_KEY} \

-e Languages={LANGUAGES_LIST} \

[image]

    -e MODELS= usr/local/models/model1/, usr/local/models/model2/
    -e TRANSLATORSYSTEMCONFIG=/usr/local/models/Config/5a72fa7c-394b-45db-8c06-ecdfc98c0832

docker run --rm -it -p 5000:5000 --memory {MEMORY_SIZE} --cpus {NUMBER_CPUS} \

-v {MODEL_MOUNT_PATH} \

-v {LICENSE_MOUNT_PATH} \

-v {OUTPUT_MOUNT_PATH} \

-e Mounts:License={CONTAINER_LICENSE_DIRECTORY} \

-e Mounts:Output={CONTAINER_OUTPUT_DIRECTORY} \

-e MODELS={MODELS_DIRECTORY_LIST} \

-e TRANSLATORSYSTEMCONFIG={TRANSLATOR_CONFIG_JSON} \

-e eula=accept \

[image]

Validate that a container is running

There are several ways to validate that the container is running:

• The container provides a homepage at / as a visual validation that the container is running.

• You can open your favorite web browser and navigate to the external IP address and exposed port of the container in question. Use the following request URLs to validate the container is running. The example request URLs listed point to http://localhost:5000, but your specific container can vary. Keep in mind that you're navigating to your container's External IP address and exposed port.

If you're having trouble running an Azure AI services container, you can try using the Microsoft diagnostics container. Use this container to diagnose common errors in your deployment environment that might prevent Azure AI containers from functioning as expected.

To get the container, use the following docker pull command:

docker pull mcr.microsoft.com/azure-cognitive-services/diagnostic

Then run the container. Replace {ENDPOINT_URI} with your endpoint, and replace {API_KEY} with your key to your resource:

docker run --rm mcr.microsoft.com/azure-cognitive-services/diagnostic \
eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}

The container tests for network connectivity to the billing endpoint.

Stop the container

To shut down the container, in the command-line environment where the container is running, select Ctrl+C.

Use cases for supporting containers

Some Translator queries require supporting containers to successfully complete operations. If you are using Office documents and don't require source language detection, only the Translator container is required. However if source language detection is required or you're using scanned PDF documents, supporting containers are required:

The following table lists the required supporting containers for your text and document translation operations. The Translator container sends billing information to Azure via the Azure AI Translator resource on your Azure account.

Operate supporting containers with docker compose

Docker compose is a tool that enables you to configure multi-container applications using a single YAML file typically named compose.yaml. Use the docker compose up command to start your container application and the docker compose down command to stop and remove your containers.

If you installed Docker Desktop CLI, it includes Docker compose and its prerequisites. If you don't have Docker Desktop, see the Installing Docker Compose overview.

Create your application

1. Using your preferred editor or IDE, create a new directory for your app named container-environment or a name of your choice.

2. Create a new YAML file named compose.yaml. Both the .yml or .yaml extensions can be used for the compose file.

3. Copy and paste the following YAML code sample into your compose.yaml file. Replace {TRANSLATOR_KEY} and {TRANSLATOR_ENDPOINT_URI} with the key and endpoint values from your Azure portal Translator instance. If you're translating documents, make sure to use the document translation endpoint.

4. The top-level name (azure-ai-translator, azure-ai-language, azure-ai-read) is parameter that you specify.

5. The container_name is an optional parameter that sets a name for the container when it runs, rather than letting docker compose generate a name.

   services:
     azure-ai-translator:
       container_name: azure-ai-translator
       image: mcr.microsoft.com/product/azure-cognitive-services/translator/text-translation:latest
       environment:
           - EULA=accept
           - billing={TRANSLATOR_ENDPOINT_URI}
           - apiKey={TRANSLATOR_KEY}
           - ladurl=http://azure-ai-language:5000
           - VISIONURL=http://azure-ai-read:5000
       ports:
             - "5000:5000"
       azure-ai-language:
         container_name: azure-ai-language
         image:  mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest
         environment:
             - EULA=accept
             - billing={LANGUAGE_RESOURCE_ENDPOINT_URI}
             - apiKey={LANGUAGE_RESOURCE_KEY}
       azure-ai-read:
         container_name: azure-ai-read
         image:  mcr.microsoft.com/azure-cognitive-services/vision/read:latest
         environment:
             - EULA=accept
             - billing={COMPUTER_VISION_ENDPOINT_URI}
             - apiKey={COMPUTER_VISION_KEY}
   

6. Open a terminal navigate to the container-environment folder, and start the containers with the following docker-compose command:

   docker compose up
   

7. To stop the containers, use the following command:

   docker compose down
   

   Tip

   Helpful Docker commands:

   • docker compose pause pauses running containers.
   • docker compose unpause {your-container-name} unpauses paused containers.
   • docker compose restart restarts all stopped and running container with all its previous changes intact. If you make changes to your compose.yaml configuration, these changes aren't updated with the docker compose restart command. You have to use the docker compose up command to reflect updates and changes in the compose.yaml file.
   • docker compose ps -a lists all containers, including those that are stopped.
   • docker compose exec enables you to execute commands to detach or set environment variables in a running container.

   For more information, see docker CLI reference.

Translator and supporting container images and tags

The Azure AI services container images can be found in the Microsoft Artifact Registry catalog. The following table lists the fully qualified image location for text and document translation:

Other parameters and commands

Here are a few more parameters and commands you can use to run the container:

Usage records

When operating Docker containers in a disconnected environment, the container will write usage records to a volume where they're collected over time. You can also call a REST API endpoint to generate a report about service usage.

Arguments for storing logs

When run in a disconnected environment, an output mount must be available to the container to store usage logs. For example, you would include -v /host/output:{OUTPUT_PATH} and Mounts:Output={OUTPUT_PATH} in the following example, replacing {OUTPUT_PATH} with the path where the logs are stored:

Example docker run command

docker run -v /host/output:{OUTPUT_PATH} ... <image> ... Mounts:Output={OUTPUT_PATH}

Environment variable names in Kubernetes deployments

• Some Azure AI Containers, for example Translator, require users to pass environmental variable names that include colons (:) when running the container.

• Kubernetes doesn't accept colons in environmental variable names. To resolve, you can replace colons with two underscore characters (__) when deploying to Kubernetes. See the following example of an acceptable format for environmental variable names:

        env:
        - name: Mounts__License
          value: "/license"
        - name: Mounts__Output
          value: "/output"

This example replaces the default format for the Mounts:License and Mounts:Output environment variable names in the docker run command.

Get usage records using the container endpoints

The container provides two endpoints for returning records regarding its usage.

Get all records

The following endpoint provides a report summarizing all of the usage collected in the mounted billing record directory.

https://<service>/records/usage-logs/

Example HTTPS endpoint to retrieve all records

http://localhost:5000/records/usage-logs

Get records for a specific month

The following endpoint provides a report summarizing usage over a specific month and year:

https://<service>/records/usage-logs/{MONTH}/{YEAR}

Example HTTPS endpoint to retrieve records for a specific month and year

http://localhost:5000/records/usage-logs/03/2024

The usage-logs endpoints return a JSON response similar to the following example:

{
  "apiType": "string",
"serviceName": "string",
"meters": [
  {
    "name": "string",
    "quantity": 256345435
    }
  ]
}

      {
    "type": "CommerceUsageResponse",
    "meters": [
      {
        "name": "CognitiveServices.TextTranslation.Container.OneDocumentTranslatedCharacters",
        "quantity": 1250000,
        "billedUnit": 1875000
      },
      {
        "name": "CognitiveServices.TextTranslation.Container.TranslatedCharacters",
        "quantity": 1250000,
        "billedUnit": 1250000
      }
    ],
    "apiType": "texttranslation",
    "serviceName": "texttranslation"
   }

Summary

In this article, you learned concepts and workflows for downloading, installing, and running an Azure AI Translator container:

• Azure AI Translator container supports text translation, synchronous document translation, and text transliteration.

• Container images are downloaded from the container registry and run in Docker.

• The billing information must be specified when you instantiate a container.

Next steps