Text Translation with Translator

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

See the section bibliography for the reference material consulted while preparing these pages.

This page targets Azure CLI 2.90.0 and the Text Translation REST API 2026-06-06 (GA in June 2026), with v3.0 still GA. The client libraries azure-ai-translation-text 2.0.0 (Python), Azure.AI.Translation.Text 2.0.0 (.NET), com.azure:azure-ai-translation-text 2.0.3 (Java) and @azure-rest/ai-translation-text 2.0.0 (JavaScript) target 2026-06-06. The 1.x libraries target v3.0. Checked on 2026-10-06.

Earlier Learn material described 2026-06-06 as REST-only. The 2.x SDKs were released for it, and this page uses them. If you are pinned to a 1.x SDK, you are calling v3.0.

Azure Translator in Foundry Tools translates text between more than 130 languages. Since 2026-06-06, each request can choose between neural machine translation (NMT), which is fast and billed per character, and LLM translation with a GPT model you deploy, which adds tone and gender control and is billed per token.

API 2026-06-06

Request shape

A request is a list of inputs. Each input has its text, optional source language and script, and a list of targets. Each target names a language and, optionally, how to translate into it:

{
  "inputs": [
    {
      "text": "A sweeping novel about memory and loss.",
      "language": "en",
      "targets": [
        { "language": "es" },
        { "language": "fr", "deploymentName": "gpt-4.1-mini", "tone": "formal" },
        { "language": "de", "deploymentName": "gpt-4.1-mini", "gender": "female" }
      ]
    }
  ]
}

Source: Text translation 2026-06-06 REST API guide

  • A target without deploymentName uses NMT.

  • A target with deploymentName uses that GPT model deployment (GPT-4.1 or GPT-5.x family) on the same Foundry resource. LLM translation needs a Foundry resource (AIServices), not a single-service Translator.

  • tone (formal, informal, neutral) and gender (female, male, neutral) apply only to LLM targets, for languages that mark them.

  • Adaptive custom translation improves LLM output with your own examples: send up to 5 reference sentence pairs with the request, or point to a dataset index of translation pairs you uploaded in the Foundry portal.

Limits and billing

NMT LLM

Max request size

50,000 characters across all inputs and targets

Smaller: check the service limits page per model; long texts should be split

Billing

Per character translated, per target

Per input and output token of the model deployment

Latency

Low (tens of ms per sentence)

Higher, depends on the model

Custom models

Custom Translator category

Adaptive custom translation

Source: Translator service limits

Calling it with REST

NMT with the global endpoint and a key (the key-based quickstart path, which also needs the region header):

curl -s -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=2026-06-06" \
  -H "Ocp-Apim-Subscription-Key: $TRANSLATOR_KEY" \
  -H "Ocp-Apim-Subscription-Region: eastus2" \
  -H "Content-Type: application/json" \
  -d '{"inputs":[{"text":"A sweeping novel about memory and loss.","targets":[{"language":"es"},{"language":"de"}]}]}'

Source: Text translation 2026-06-06 REST API guide

LLM translation with Entra ID, through the Foundry resource’s custom-subdomain endpoint:

TOKEN=$(az account get-access-token --resource https://cognitiveservices.azure.com --query accessToken -o tsv)

curl -s -X POST "https://$FOUNDRY.cognitiveservices.azure.com/translator/text/translate?api-version=2026-06-06" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"inputs":[{"text":"Free shipping on orders over 30 euros.","language":"en",
        "targets":[{"language":"fr","deploymentName":"gpt-4.1-mini","tone":"formal"}]}]}'

Source: Translate with an LLM

Calling it with the SDKs

from azure.ai.translation.text import TextTranslationClient
from azure.ai.translation.text.models import TranslateInputItem, TranslationTarget
from azure.identity import DefaultAzureCredential

client = TextTranslationClient(
    credential=DefaultAzureCredential(),
    endpoint="https://foundry-bookshelf.cognitiveservices.azure.com/",
)

# NMT into several languages
result = client.translate(body=["A sweeping novel about memory and loss."], to_language=["es", "fr", "de"])
for t in result[0].translations:
    print(t.language, t.text)

# LLM translation with tone
item = TranslateInputItem(
    text="Free shipping on orders over 30 euros.",
    targets=[TranslationTarget(language="fr", deployment_name="gpt-4.1-mini", tone="formal")],
)
print(client.translate(body=[item])[0].translations[0].text)

Source: Text translation SDKs

using Azure;
using Azure.AI.Translation.Text;
using Azure.Identity;

var client = new TextTranslationClient(
    new DefaultAzureCredential(), new Uri("https://foundry-bookshelf.cognitiveservices.azure.com/"));

Response<IReadOnlyList<TranslatedTextItem>> response =
    await client.TranslateAsync("es", "A sweeping novel about memory and loss.");
Console.WriteLine(response.Value[0].Translations[0].Text);

Source: Azure Text Translation client library for .NET

import com.azure.ai.translation.text.TextTranslationClient;
import com.azure.ai.translation.text.TextTranslationClientBuilder;
import com.azure.ai.translation.text.models.*;
import com.azure.identity.DefaultAzureCredentialBuilder;
import java.util.List;

TextTranslationClient client = new TextTranslationClientBuilder()
    .endpoint("https://foundry-bookshelf.cognitiveservices.azure.com/")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

TranslateInputItem input = new TranslateInputItem(
    "A sweeping novel about memory and loss.",
    List.of(new TranslationTarget("es"), new TranslationTarget("de")));
input.setLanguage("en");

for (TranslationText t : client.translate(List.of(input)).get(0).getTranslations()) {
    System.out.println(t.getLanguage() + ": " + t.getText());
}

Source: Azure Text Translation client library for Java

v3.0 operations

v3.0 is still GA and is what 1.x SDKs and older integrations call. It has more operations than 2026-06-06:

Operation Purpose

translate

NMT translation, with to query parameters, textType=html, profanityAction and category for Custom Translator.

transliterate

Convert script, for example Japanese kanji to Latin.

detect

Detect the language of a text.

breaksentence

Return sentence boundaries.

dictionary/lookup and dictionary/examples

Alternative translations of a word and usage examples.

 
curl -s -X POST \
  "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=es&to=fr&textType=html&profanityAction=Marked" \
  -H "Ocp-Apim-Subscription-Key: $TRANSLATOR_KEY" -H "Ocp-Apim-Subscription-Region: eastus2" \
  -H "Content-Type: application/json" \
  -d '[{"Text":"<p>A <b>sweeping</b> novel.</p>"}]'

Source: Translator v3.0 translate

Migrating from v3.0 to 2026-06-06

v3.0 2026-06-06 Notes

to query parameters

targets[] per input

Each target can choose NMT or LLM.

[{"Text": ...}] body

{"inputs": [{"text": ...}]} body

Property names are camelCase.

detect, breaksentence, dictionary/*

Not available

Use Language detection (Language: PII, Entities, Language Detection and Health); for word alternatives, use an LLM or adaptive custom translation.

includeAlignment, includeSentenceLength

Removed

Split text yourself if you need sentence boundaries.

detectedLanguage.score (v3 score)

detectedLanguage.score

Same meaning.

category (Custom Translator)

category on a target

Custom Translator models still work with NMT targets.

Global endpoint only for keys

Custom-subdomain endpoint for Entra ID and LLM

Keep the region header with keys on the global endpoint.

Source: Migrate to 2026-06-06

Other options

  • HTML: set textType to html to translate markup without breaking tags. Use class="notranslate" on elements (for example ISBNs or brand names) that must stay as they are.

  • Profanity: profanityAction NoAction, Marked (with profanityMarker Asterisk or Tag) or Deleted.

  • Headers: Ocp-Apim-Subscription-Region is required with a key on the global endpoint, and X-ClientTraceId helps support trace a request.

Provisioning

In the Azure portal

  1. Use the Foundry resource foundry-bookshelf. For LLM translation, deploy a GPT model (for example gpt-4.1-mini) in the Foundry portal under Models + endpoints.

  2. In the Foundry portal, open Playgrounds → Translator playground to compare NMT and LLM output side by side.

  3. Assign Cognitive Services User to the identity that calls Translator.

With the Azure CLI

az cognitiveservices account deployment create \
  --name "$FOUNDRY" --resource-group "$RG" \
  --deployment-name gpt-4.1-mini \
  --model-name gpt-4.1-mini --model-version "2025-04-14" --model-format OpenAI \
  --sku-name GlobalStandard --sku-capacity 50

Source: Azure CLI reference — az cognitiveservices account deployment create

Use cases

Scenario Feature Why this feature Example input → output

Bookshelf: translate catalog descriptions at publish time

NMT targets es, fr, de; textType=html

Thousands of descriptions; lowest cost per character; HTML preserved.

English description HTML → three localized versions stored with the book in catalog-api

Bookshelf: marketing copy

LLM target with tone=formal

Fewer words, more nuance; tone matters.

Campaign banner → formal French copy

Multilingual chat and support

NMT, both directions

Low latency inside a conversation.

Customer message in Polish → English for the agent, and back

UI and content localization

NMT with a Custom Translator category

Product terminology stays consistent.

Resource strings → localized resource files

E-commerce listings

LLM with adaptive custom translation

Brand voice from reference pairs.

Listing title → localized title in house style

When not to use it

Clean up

az cognitiveservices account deployment delete \
  --name "$FOUNDRY" --resource-group "$RG" --deployment-name gpt-4.1-mini

Source: Azure CLI reference — az cognitiveservices account deployment delete

Related pages

References