Edit

Container: Translate Text

  • Article

Translate text.

Request URL

Send a POST request to:

POST {Endpoint}/translate?api-version=3.0&&from={from}&to={to}

Example request

POST https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=es

[
  {
    "Text": "I would really like to drive your car."
  }
]

Example response

[
  {
    "translations": [
      {
        "text": "Realmente me gustaría conducir su coche.",
        "to": "es"
      }
    ]
  }
]

Request parameters

Request parameters passed on the query string are:

Required parameters

Query parameter Description Condition
api-version Version of the API requested by the client. Value must be 3.0. Required parameter
from Specifies the language of the input text. Required parameter
to Specifies the language of the output text. For example, use to=de to translate to German.
It's possible to translate to multiple languages simultaneously by repeating the parameter in the query string. For example, use to=de&to=it to translate to German and Italian.		 Required parameter

Optional parameters

Query parameter Description
textType Optional parameter.
Defines whether the text being translated is plain text or HTML text. Any HTML needs to be a well-formed, complete element. Possible values are: plain (default) or html.
includeSentenceLength Optional parameter.
Specifies whether to include sentence boundaries for the input text and the translated text. Possible values are: true or false (default).

Request headers

Headers Description Condition
Authentication headers See available options for authentication. Required request header
Content-Type Specifies the content type of the payload.
Accepted value is application/json; charset=UTF-8.		 Required request header
Content-Length The length of the request body. Optional
X-ClientTraceId A client-generated GUID to uniquely identify the request. You can omit this header if you include the trace ID in the query string using a query parameter named ClientTraceId. Optional

Request body

The body of the request is a JSON array. Each array element is a JSON object with a string property named Text, which represents the string to translate.

[
    {"Text":"I would really like to drive your car around the block a few times."}
]

The following limitations apply:

  • The array can have at most 100 elements.
  • The entire text included in the request can't exceed 10,000 characters including spaces.

Response body

A successful response is a JSON array with one result for each string in the input array. A result object includes the following properties:

  • translations: An array of translation results. The size of the array matches the number of target languages specified through the to query parameter. Each element in the array includes:

  • to: A string representing the language code of the target language.

  • text: A string giving the translated text.

  • sentLen: An object returning sentence boundaries in the input and output texts.

  • srcSentLen: An integer array representing the lengths of the sentences in the input text. The length of the array is the number of sentences, and the values are the length of each sentence.

  • transSentLen: An integer array representing the lengths of the sentences in the translated text. The length of the array is the number of sentences, and the values are the length of each sentence.

    Sentence boundaries are only included when the request parameter includeSentenceLength is true.

    • sourceText: An object with a single string property named text, which gives the input text in the default script of the source language. sourceText property is present only when the input is expressed in a script that's not the usual script for the language. For example, if the input were Arabic written in Latin script, then sourceText.text would be the same Arabic text converted into Arab script.

Response headers

Headers Description
X-RequestId Value generated by the service to identify the request and used for troubleshooting purposes.
X-MT-System Specifies the system type that was used for translation for each 'to' language requested for translation. The value is a comma-separated list of strings. Each string indicates a type:

▪ Custom - Request includes a custom system and at least one custom system was used during translation.
▪ Team - All other requests

Response status codes

If an error occurs, the request returns a JSON error response. The error code is a 6-digit number combining the 3-digit HTTP status code followed by a 3-digit number to further categorize the error. Common error codes can be found on the v3 Translator reference page.

Code samples: translate text

Note

  • Each sample runs on the localhost that you specified with the docker run command.
  • While your container is running, localhost points to the container itself.
  • You don't have to use localhost:5000. You can use any port that is not already in use in your host environment. To specify a port, use the -p option.

Translate a single input

This example shows how to translate a single sentence from English to Simplified Chinese.

curl -X POST "http://localhost:{port}/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

The response body is:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    }
]

The translations array includes one element, which provides the translation of the single piece of text in the input.

Query Azure AI Translator endpoint (text)

Here's an example cURL HTTP request using localhost:5000 that you specified with the docker run command:

  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.

Translate text using Swagger API

English ↔ German

  1. Navigate to the Swagger page: http://localhost:5000/swagger/index.html
  2. Select POST /translate
  3. Select Try it out
  4. Enter the From parameter as en
  5. Enter the To parameter as de
  6. Enter the api-version parameter as 3.0
  7. 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 see the following response:

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

Translate text with Python

English ↔ French

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

English ↔ Spanish

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=es";

        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();
            }
        }
    }
}

Translate multiple strings

Translating multiple strings at once is simply a matter of specifying an array of strings in the request body.

curl -X POST "http://localhost:{port}/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}, {'Text':'I am fine, thank you.'}]"

The response contains the translation of all pieces of text in the exact same order as in the request. The response body is:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    },
    {
        "translations":[
            {"text":"我很好，谢谢你。","to":"zh-Hans"}
        ]
    }
]

Translate to multiple languages

This example shows how to translate the same input to several languages in one request.

curl -X POST "http://localhost:{port}/translate?api-version=3.0&from=en&to=zh-Hans&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

The response body is:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"},
            {"text":"Hallo, was ist dein Name?","to":"de"}
        ]
    }
]

Translate content with markup and specify translated content

It's common to translate content that includes markup such as content from an HTML page or content from an XML document. Include query parameter textType=html when translating content with tags. In addition, it's sometimes useful to exclude specific content from translation. You can use the attribute class=notranslate to specify content that should remain in its original language. In the following example, the content inside the first div element isn't translated, while the content in the second div element is translated.

<div class="notranslate">This will not be translated.</div>
<div>This will be translated. </div>

Here's a sample request to illustrate.

curl -X POST "http://localhost:{port}/translate?api-version=3.0&from=en&to=zh-Hans&textType=html" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'<div class=\"notranslate\">This will not be translated.</div><div>This will be translated.</div>'}]"

The response is:

[
    {
        "translations":[
            {"text":"<div class=\"notranslate\">This will not be translated.</div><div>这将被翻译。</div>","to":"zh-Hans"}
        ]
    }
]

Translate with dynamic dictionary

If you already know the translation you want to apply to a word or a phrase, you can supply it as markup within the request. The dynamic dictionary is only safe for proper nouns such as personal names and product names.

The markup to supply uses the following syntax.

<mstrans:dictionary translation="translation of phrase">phrase</mstrans:dictionary>

For example, consider the English sentence "The word wordomatic is a dictionary entry." To preserve the word wordomatic in the translation, send the request:

curl -X POST "http://localhost:{port}/translate?api-version=3.0&from=en&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The word <mstrans:dictionary translation=\"wordomatic\">word or phrase</mstrans:dictionary> is a dictionary entry.'}]"

The result is:

[
    {
        "translations":[
            {"text":"Das Wort \"wordomatic\" ist ein Wörterbucheintrag.","to":"de"}
        ]
    }
]

This feature works the same way with textType=text or with textType=html. The feature should be used sparingly. The appropriate and far better way of customizing translation is by using Custom Translator. Custom Translator makes full use of context and statistical probabilities. If you created training data that shows your work or phrase in context, you get better results. Learn more about Custom Translator.

Request limits

Each translate request is limited to 10,000 characters, across all the target languages you're translating to. For example, sending a translate request of 3,000 characters to translate to three different languages results in a request size of 3000x3 = 9,000 characters, which satisfy the request limit. You're charged per character, not by the number of requests. We recommended sending shorter requests.

The following table lists array element and character limits for the Translator translation operation.

Operation Maximum size of array element Maximum number of array elements Maximum request size (characters)
translate 10,000 100 10,000

Use docker compose: Translator with supporting containers

Docker compose is a tool 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.

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
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 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.
Translator: Document translation TODO TODO
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.

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. Make sure you 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}
        - AzureAiLanguageHost=http://azure-ai-language:5000
        - AzureAiReadHost=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={TRANSLATOR_ENDPOINT_URI}
          - apiKey={TRANSLATOR_KEY}
    azure-ai-read:
      container_name: azure-ai-read
      image:  mcr.microsoft.com/azure-cognitive-services/vision/read:latest
      environment:
          - EULA=accept
          - billing={TRANSLATOR_ENDPOINT_URI}
          - apiKey={TRANSLATOR_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

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

Next Steps

Learn more about text translation