Install and run Translator containers

Containers enable you to run several features of the Translator service in your own environment. Containers are great for specific security and data governance requirements. In this article you learn how to download, install, and run a Translator container.

Translator container enables you to build a translator application architecture that is optimized for both robust cloud capabilities and edge locality.

See the list of languages supported when using Translator containers.

Important

• To use the Translator container, you must submit an online request and have it approved. For more information, see Request approval to run container.
• Translator container supports limited features compared to the cloud offerings. For more information, see Container translate methods.

Prerequisites

To get started, you need an active Azure account. If you don't have one, you can create a free account.

You also need:

Required	Purpose
Familiarity with Docker	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.
Docker Engine	You need the Docker Engine installed on a host computer. Docker provides packages that configure the Docker environment on macOS, Windows, and Linux. For a primer on Docker and container basics, see the Docker overview. Docker must be configured to allow the containers to connect with and send billing data to Azure. On Windows, Docker must also be configured to support Linux containers.
Translator resource	An Azure Translator regional resource (not global) with an associated API key and endpoint URI. Both values are required to start the container and can be found on the resource overview page.

Optional	Purpose
Azure CLI (command-line interface)	The Azure CLI enables you to use a set of online commands to create and manage Azure resources. It's available to install in Windows, macOS, and Linux environments and can be run in a Docker container and Azure Cloud Shell.

Required elements

All Azure AI containers require three primary elements:

• EULA accept setting. 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 the Translator resource Keys and Endpoint page and selecting the Copy to clipboard icon.

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.

Host computer

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

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

Container requirements and recommendations

The following table describes the minimum and recommended CPU cores and memory to allocate for the Translator container.

Container	Minimum	Recommended	Language Pair
Translator	2 cores, 2-GB memory	4 cores, 8-GB memory	4

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

• For every language pair, it's recommended to have 2 GB of memory. By default, the Translator offline container has four language pairs.

• The core and memory correspond to the --cpus and --memory settings, which are used as part of the docker run command.

Note

• CPU core and memory correspond to the --cpus and --memory settings, which are used as part of the docker run command.

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

Request approval to run container

Complete and submit the Azure AI services Application for Gated Services to request access to the container.

The form requests information about you, your company, and the user scenario for which you'll use the container. After you submit the form, the Azure AI services team reviews it and emails you with a decision within 10 business days.

Important

• On the form, you must use an email address associated with an Azure subscription ID.
• The Azure resource you use to run the container must have been created with the approved Azure subscription ID.
• Check your email (both inbox and junk folders) for updates on the status of your application from Microsoft.

After you're approved, you'll be able to run the container after you download it from the Microsoft Container Registry (MCR), described later in the article.

You won't be able to run the container if your Azure subscription hasn't been approved.

Translator container image

The Translator container image can be found on the mcr.microsoft.com container registry syndicate. It 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, you can use the latest tag. You can find a full list of tags on the MCR.

Get container images with docker commands

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.

Use the docker run command to download a container image from Microsoft Container registry and run it.

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 above command:

• Downloads and runs a Translator container from the container image.
• Allocates 12 gigabytes (GB) of memory and four CPU core.
• Exposes TCP port 5000 and allocates a pseudo-TTY for the container
• 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.

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 container's Translator endpoint

The container provides a REST-based Translator endpoint API. Here's an example request:

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

If you attempt the cURL POST request before the container is ready, you'll end up getting a Service is temporarily unavailable response. Wait until the container is ready, then try again.

Stop the container

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

Troubleshoot

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 may 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 HTTP headers and body format that's required.

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 will test for network connectivity to the billing endpoint.

Text translation code samples

Translate text with swagger

English ↔ German

Navigate to the swagger page: http://localhost:5000/swagger/index.html

1. Select POST /translate
2. Select Try it out
3. Enter the From parameter as en
4. Enter the To parameter as de
5. Enter the api-version parameter as 3.0
6. Under texts, replace string with the following JSON

  [
        {
            "text": "hello, how are you"
        }
  ]

Select Execute, the resulting translations are output in the Response Body. You should expect something similar to the following response:

"translations": [
      {
          "text": "hallo, wie geht es dir",
          "to": "de"
      }
    ]

Translate text with Python

import requests, json

url = 'http://localhost:5000/translate?api-version=3.0&from=en&to=fr'
headers = { 'Content-Type': 'application/json' }
body = [{ 'text': 'Hello, how are you' }]

request = requests.post(url, headers=headers, json=body)
response = request.json()

print(json.dumps(
    response,
    sort_keys=True,
     indent=4,
     ensure_ascii=False,
     separators=(',', ': ')))

Translate text with C#/.NET console app

Launch Visual Studio, and create a new console application. Edit the *.csproj file to add the <LangVersion>7.1</LangVersion> node—specifies C# 7.1. Add the Newtoonsoft.Json NuGet package, version 11.0.2.

In the Program.cs replace all the existing code with the following script:

using Newtonsoft.Json;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

namespace TranslateContainer
{
    class Program
    {
        const string ApiHostEndpoint = "http://localhost:5000";
        const string TranslateApi = "/translate?api-version=3.0&from=en&to=de";

        static async Task Main(string[] args)
        {
            var textToTranslate = "Sunny day in Seattle";
            var result = await TranslateTextAsync(textToTranslate);

            Console.WriteLine(result);
            Console.ReadLine();
        }

        static async Task<string> TranslateTextAsync(string textToTranslate)
        {
            var body = new object[] { new { Text = textToTranslate } };
            var requestBody = JsonConvert.SerializeObject(body);

            var client = new HttpClient();
            using (var request =
                new HttpRequestMessage
                {
                    Method = HttpMethod.Post,
                    RequestUri = new Uri($"{ApiHostEndpoint}{TranslateApi}"),
                    Content = new StringContent(requestBody, Encoding.UTF8, "application/json")
                })
            {
                // Send the request and await a response.
                var response = await client.SendAsync(request);

                return await response.Content.ReadAsStringAsync();
            }
        }
    }
}

Summary

In this article, you learned concepts and workflows for downloading, installing, and running Translator container. Now you know:

• Translator provides Linux containers for Docker.
• Container images are downloaded from the container registry and run in Docker.
• You can use the REST API to call 'translate' operation in Translator container by specifying the container's host URI.

Next steps

Learn more about Azure AI containers