Edit

Share via

Install and run Azure AI Translator container

  • Article

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. 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

Important

Your translator resource must meet the following requirements:

  • Your Translator instance must be a Translator resource (not a multi-service Azure AI services resource).

  • Your Translator instance must be a regional resource (not a global Azure AI Translator resource) within am available Azure geographic region. For more information, see Azure AI Translator region pricing options.

  • 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 regional resource created under your 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.

      Screenshot of pricing tier selection for Translator connected container.

    • 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.

      A screenshot showing resource creation on the Azure portal.

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.

Tip

Consider adding Docker Desktop to your computing environment. Docker Desktop is a graphical user interface (GUI) that enables you to build, run, and share containerized applications directly from your desktop.

DockerDesktop includes Docker Engine, Docker CLI client, Docker Compose and provides packages that configure Docker for your preferred operating system:

Tool Description Condition
Docker Engine The Docker Engine is the core component of the Docker containerization platform. It must be installed on a host computer to enable you to build, run, and manage your containers. Required for all operations.
Docker Compose The Docker Compose tool is used to define and run multi-container applications. Required for supporting containers.
Docker CLI The Docker command-line interface enables you to interact with Docker Engine and manage Docker containers directly from your local machine. Recommended
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:

Operating System System requirements
Windows • Windows 10 or Windows 11 installed
• 64-bit processor
• A minimum of 4 GB of RAM
• Windows Hyper-V and Container features, and BIOS-level hardware virtualization
• For more information, see Install Docker Desktop on Windows
Mac • 2010 computer model or later
• OS 10.13 or later
• A minimum of 4 GB of RAM
• For more information, see Install Docker Desktop on Mac
Linux • 64-bit version of Ubuntu (latest LTS (long term support) version or current non-LTS version), Debian 12, Fedora 38, or Fedora 39
• CPU support for virtualization
• A minimum of 4 GB of RAM
• For more information, see Install Docker Desktop on Linux

Note

The minimum and recommended specifications are based on Docker limits, not host machine resources.

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

Function Minimum recommended Notes
Text translation 4 Core, 4-GB memory
Text transliteration 4 Core, 2-GB memory
Document translation 4 Core, 6-GB memory The number of documents that can be processed concurrently can be calculated with the following formula: [minimum of (n-2), (m-6)/4)].
• n is number of CPU cores.
• m is GB of memory.
• Example: 8 Core, 32-GB memory can process six(6) concurrent documents [minimum of (8-2), (36-6)/4)].

  • 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.

Important

  • Keys are used to access your Azure AI resource. Do not share your keys. Store them securely, for example, using Azure Key Vault.

  • We also recommend regenerating these keys regularly. Only one key is necessary to make an API call. When regenerating the first key, you can use the second key for continued access to the service.

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:

Option Description
ApiKey The key of the Azure AI services resource used to track billing information.
The value of this option must be set to a key for the provisioned resource specified in Billing.
Billing The endpoint of the Azure AI services resource used to track billing information.
The value of this option must be set to the endpoint URI of a provisioned Azure resource.
Eula Indicates that you accepted the license for the container.
The value of this option must be set to accept.

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:

Azure AI Translator containers enable you to run the Azure AI Translator service on-premise in your own environment. Connected containers run locally and send usage information to the cloud for billing.

Download and run container image

The docker run command downloads an image from Microsoft Artifact Registry and starts the container.

Important

  • The docker commands in the following sections use the back slash, \, as a line continuation character. Replace or remove this based on your host operating system's requirements.
  • The EULA, Billing, and ApiKey options must be specified to run the container; otherwise, the container won't start.
  • If you're translating documents, be sure to use the document translation endpoint.
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

The Docker command:

  • Creates a running Translator container from a downloaded container image.
  • Allocates 12 gigabytes (GB) of memory and four CPU core.
  • Exposes transmission control protocol (TCP) port 5000 and allocates a pseudo-TTY for the container. Now, the localhost address points to the container itself, not your host machine.
  • Accepts the end-user agreement (EULA).
  • Configures billing endpoint.
  • Downloads translation models for languages English, French, Spanish, Arabic, and Russian.
  • Automatically removes the container after it exits. The container image is still available on the host computer.

Tip

Additional Docker command:

  • docker ps lists running containers.
  • docker pause {your-container name} pauses a running container.
  • docker unpause {your-container-name} unpauses a paused container.
  • docker restart {your-container-name} restarts a running container.
  • docker exec enables you to execute commands lto detach or set environment variables in a running container.

For more information, see docker CLI reference.

Run multiple containers on the same host

If you intend to run multiple containers with exposed ports, make sure to run each container with a different exposed port. For example, run the first container on port 5000 and the second container on port 5001.

You can have this container and a different Azure AI container running on the HOST together. You also can have multiple containers of the same Azure AI container running.

Query the Translator container endpoint

The container provides a REST-based Translator endpoint API. Here's an example request with source language (from=en) specified:

  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?'}]"

Note

  • Source language detection requires an additional container. For more information, see Supporting containers

  • If the cURL POST request returns a Service is temporarily unavailable response the container isn't ready. Wait a few minutes, then try again.

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.

Request URL Purpose
http://localhost:5000/ The container provides a home page.
http://localhost:5000/ready Requested with GET. Provides a verification that the container is ready to accept a query against the model. This request can be used for Kubernetes liveness and readiness probes.
http://localhost:5000/status Requested with GET. Verifies if the api-key used to start the container is valid without causing an endpoint query. This request can be used for Kubernetes liveness and readiness probes.
http://localhost:5000/swagger The container provides a full set of documentation for the endpoints and a Try it out feature. With this feature, you can enter your settings into a web-based HTML form and make the query without having to write any code. After the query returns, an example CURL command is provided to demonstrate the required HTTP headers and body format.

Screenshot of the container home page.

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.

Operation Request query Document type Supporting containers
• Text translation
• Document Translation		 from specified. Office documents None
• Text translation
• Document Translation		 from not specified. Requires automatic language detection to determine the source language. Office documents ✔️ Text analytics:language container
• Text translation
• Document Translation		 from specified. Scanned PDF documents ✔️ Vision:read container
• Text translation
• Document Translation		 from not specified requiring automatic language detection to determine source language. Scanned PDF documents ✔️ Text analytics:language container

✔️ Vision:read container

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/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"
    volumes:
          - {your local folder}:/usr/local/models
    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}
          - Languages=en,es
          - LADINCLUSTER=true
    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:

Container Image location Notes
Translator: Text and document translation mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest You can view the full list of Azure AI services Text Translation version tags on MCR.
Text analytics: language mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest You can view the full list of Azure AI services Text Analytics Language version tags on MCR.
Vision: read mcr.microsoft.com/azure-cognitive-services/vision/read:latest You can view the full list of Azure AI services Computer Vision Read OCR version tags on MCR.

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:

Connected container

Usage charges are calculated based upon the quantity value.

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

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

Learn more about Azure AI container configuration Learn more about container language support.