Install and run Translator containers (preview)

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

Important

  • Translator container is in gated preview and to use it you must submit an online request, and have it approved. See Request approval to run container below for more information.
  • Translator container supports limited features compared to the cloud offerings. Please refer to Container: Translate for more details.

Prerequisites

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

You'll also need the following:

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 resource with region other than 'global', 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 is available to install in Windows, macOS, and Linux environments and can be run in a Docker container and Azure Cloud Shell.

Required elements

All Cognitive Services 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

  • Subscription keys are used to access your Cognitive Service API. 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 a 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:

Container requirements and recommendations

The following table describes the minimum and recommended specifications for Translator containers. At least 2 gigabytes (GB) of memory are required and each CPU must be at least 2.6 gigahertz (GHz) or faster. and memory, in gigabytes (GB), to allocate for each Translator. The following table describes the minimum and recommended allocation of resources for each Translator container.

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

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 Cognitive 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 Cognitive Services team will review it and email you with a decision.

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 will be able to run the container after downloading 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 has not been approved.

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:80 --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

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 Cognitive Services container running on the HOST together. You also can have multiple containers of the same Cognitive Services container running.

Query the container's Translator endpoint

The container provides a REST-based Translator endpoint API. Here is 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 various request URLs below to validate the container is running. The example request URLs listed below are 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.

Container home page

If you're having trouble running a Cognitive Services container, you can try using the Microsoft diagnostics container. Use this container to diagnose common errors in your deployment environment that might prevent Cognitive Services 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:

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