Azure Translator adaptive custom translation

Azure Translator adaptive custom translation (AdaptCT) is a runtime translation adaptation capability available in Microsoft Foundry. It improves large language model (LLM) outputs, such as GPT-5.1, using a compact set of reference sentence pairs.

With AdaptCT, upload 5–10,000 prealigned source–target segment pairs (≤250 characters each). The service creates the adaptive dataset in minutes, which you can apply through the Azure Translator 2026-06-06 APIs.

AdaptCT uses few-shot retrieval at inference—no large training or separate deployment. It retrieves similar segments per request from the adaptive dataset to guide terminology, context, and style.

Compare adaptive and custom translation

The following comparison highlights when to choose adaptive custom translation versus a fully trained Custom Translator model.

Key differences

Use the following decision guide to evaluate implementation effort, update speed, and operational impact before you commit to data preparation, training, and deployment workflows.

• Custom translator: Best when you need a dedicated, production-deployed neural translation model trained on a large parallel corpus. This path involves full model training and deployment, and updates typically follow a retrain-and-redeploy cycle that can take up to ~48 hours depending on dataset size and service capacity.

• Adaptive custom translation: Best when you need rapid, iterative control of terminology, phrasing, or style without creating a new model artifact. Instead of fine-tuning, the service builds a dataset from aligned sentence pairs in minutes and applies retrieval at inference time to select similar segments per request to guide terminology, context, and style.

Adaptive custom translation base URL

Here's the base URL for all adaptive custom translation API requests:

   https://<your-resource-name>.cognitiveservices.azure.com/translator/customtranslator/api/texttranslator/v1.0/

Authentication

Each request to an adaptCT API must include an authentication header. This header passes along a Foundry resource secret key and authentication token, which is used to validate your subscription for a service or group of services.

• Authenticate with a secret key.
• Authenticate with an access token.
• Authenticate with Microsoft Entra ID.

For more information about Azure resources, see Azure resources for Azure AI translation.

Required headers

Include the following headers in every request to ensure the service can authenticate and route your call correctly.

How to create and use an adaptive dataset

1. You must use a Foundry resource. To learn how to create and manage a Foundry resource see Create your first Foundry resource
2. Create workspace
3. Import adaptive documents (TMX/TSV)
4. Create adaptive dataset
5. To translate with adaptive dataset see Use Text Translation API

API operations

The Adaptive custom translation API is organized into three main operation categories.

Workspace adaptive dataset operations

• Get All workspaces
• Get workspace
• Create workspace

Document operations

• Get Adaptive Documents
• Import Adaptive Documents (TMX/TSV)
• Get Import Job Status

Adaptive dataset operations

• Create adaptive dataset
• Get adaptive dataset
• Get all adaptive datasets
• Delete adaptive dataset

Workspace operation reference

Get all workspaces

Retrieves all workspaces available to the authenticated user.

Request URL

   GET /workspaces/

Request example

Windows

curl -X GET "https://<your-resource-name>.cognitiveservices.azure.com/translator/customtranslator/api/texttranslator/v1.0/workspaces/" ^
 -H "Ocp-Apim-Subscription-Key: <your-key>" ^
 -H "Ocp-Apim-Subscription-Region: <your-region>"

Linux/macOS

curl -X GET "https://<your-resource-name>.cognitiveservices.azure.com/translator/customtranslator/api/texttranslator/v1.0/workspaces/" \
 -H "Ocp-Apim-Subscription-Key: <your-key>" \
 -H "Ocp-Apim-Subscription-Region: <your-region>"

Get workspace

Retrieves details for a specific workspace.

Request URL

   GET /workspaces/<workspaceId>

Parameters

Request example

Windows

curl -X GET "https://<your-resource-name>.cognitiveservices.azure.com/translator/customtranslator/api/texttranslator/v1.0/workspaces/<workspaceId>" ^
 -H "Ocp-Apim-Subscription-Key: <your-key>" ^
 -H "Ocp-Apim-Subscription-Region: <your-region>"

Linux/macOS

curl -X GET "https://<your-resource-name>.cognitiveservices.azure.com/translator/customtranslator/api/texttranslator/v1.0/workspaces/<workspaceId>" \
 -H "Ocp-Apim-Subscription-Key: <your-key>" \
 -H "Ocp-Apim-Subscription-Region: <your-region>"

Create workspace

Create a workspace in Microsoft Foundry after creating your Foundry resource and project.

1. Select a project.
2. Select Build > Models > AI Services > Azure Translator - Text Translation > Adaptive LLM. The workspace is created automatically.
3. Retrieve the workspace ID by creating your first adaptive dataset in the playground using the Adaptive LLM tab (the GUID in <GUID>-adaptive-general), or by calling Get all workspaces.

Document operations

Get documents

Retrieves a paginated list of documents in a project.

Request URL

  GET /documents?workspaceId=<workspaceId>&pageIndex={pageIndex}

Parameters

Request headers

Request example

Windows

curl -X GET "https://<your-resource-name>.cognitiveservices.azure.com/translator/customtranslator/api/texttranslator/v1.0/documents?workspaceId=<workspaceId>&pageIndex=0" ^
 -H "Authorization: Bearer <token>"

Linux/macOS

curl -X GET "https://<your-resource-name>.cognitiveservices.azure.com/translator/customtranslator/api/texttranslator/v1.0/documents?workspaceId=<workspaceId>&pageIndex=0" \
 -H "Authorization: Bearer <token>"

Import documents (TSV, TMX)

Imports adaptive documents in TSV and TMX format to a project.

Request URL

   POST /documents/import?workspaceId=<workspaceId>

Parameters

Request headers

Request body (multipart form data)

DocumentDetails JSON format

[{
  "DocumentName": "string",
  "DocumentType": "Adaptive",
  "FileDetails": [{
    "Name": "string",
    "LanguageCode": "string",
    "OverwriteIfExists": boolean
  }]
}]

TMX request example

English to supported target language, for example, French.

Windows

curl -X POST "https://<your-resource-name>.cognitiveservices.azure.com/translator/customtranslator/api/texttranslator/v1.0/documents/import?workspaceId=<workspaceId>" ^
 -H "Authorization: Bearer <token>" ^
 -F "DocumentDetails=[{\"DocumentName\": \"my-document\",\"DocumentType\": \"Adaptive\",\"FileDetails\": [{\"Name\": \"data.tmx\",\"LanguageCode\": \"en\",\"OverwriteIfExists\": true}]}]" ^
 -F "FILES=@path/to/data.tmx"

Linux/macOS

curl -X POST "https://<your-resource-name>.cognitiveservices.azure.com/translator/customtranslator/api/texttranslator/v1.0/documents/import?workspaceId=<workspaceId>" \
 -H "Authorization: Bearer <token>" \
 -F "DocumentDetails=[{\"DocumentName\": \"my-document\",\"DocumentType\": \"Adaptive\",\"FileDetails\": [{\"Name\": \"data.tmx\",\"LanguageCode\": \"en\",\"OverwriteIfExists\": true}]}]" \
 -F "FILES=@path/to/data.tmx"

Get import job status

Retrieves the status of a document import job.

Request URL

   GET /documents/import/jobs/<jobId>

Parameters

Request headers

Request example

Windows

curl -X GET "https://<your-resource-name>.cognitiveservices.azure.com/translator/customtranslator/api/texttranslator/v1.0/documents/import/jobs/<jobId>" ^
 -H "Authorization: Bearer <token>"

Linux/macOS

curl -X GET "https://<your-resource-name>.cognitiveservices.azure.com/translator/customtranslator/api/texttranslator/v1.0/documents/import/jobs/<jobId>" \
 -H "Authorization: Bearer <token>"

Adaptive dataset operations reference

Create adaptive dataset

Creates a new dataset for adaptive translation using specified documents.

Request URL

   POST /index?workspaceId=<workspaceId>

Parameters

Request headers

Request body

{
  "documentIds": ["string"],
  "IndexName": "string",
  "SourceLanguage": "string",
  "TargetLanguage": "string"
}

Parameters

Request example

Windows

curl -X POST "https://<your-resource-name>.cognitiveservices.azure.com/translator/customtranslator/api/texttranslator/v1.0/index?workspaceId=<workspaceId>" ^
 -H "Content-Type: application/json" ^
 -d "{\"documentIds\": [\"1457362\"],\"IndexName\": \"my-index\",\"SourceLanguage\": \"en\",\"TargetLanguage\": \"de\"}"

Linux/macOS

curl -X POST "https://<your-resource-name>.cognitiveservices.azure.com/translator/customtranslator/api/texttranslator/v1.0/index?workspaceId=<workspaceId>" \
 -H "Content-Type: application/json" \
 -d "{\"documentIds\": [\"1457362\"],\"IndexName\": \"my-index\",\"SourceLanguage\": \"en\",\"TargetLanguage\": \"de\"}"

Get adaptive dataset

Retrieves details for a specific dataset.

Request URL

   GET /index/{indexId}

Parameters

Request example

Windows

curl -X GET "https://<your-resource-name>.cognitiveservices.azure.com/translator/customtranslator/api/texttranslator/v1.0/index/<indexId>"

Linux/macOS

cucurl -X GET "https://<your-resource-name>.cognitiveservices.azure.com/translator/customtranslator/api/texttranslator/v1.0/index/<indexId>"

Get all adaptive datasets

Retrieves all datasets in a project.

Request URL

   GET /index?workspaceId=<workspaceId>

Parameters

Request example

Windows

curl -X GET "https://<your-resource-name>.cognitiveservices.azure.com/translator/customtranslator/api/texttranslator/v1.0/index?workspaceId=<workspaceId>"

Linux/macOS

curl -X GET "https://<your-resource-name>.cognitiveservices.azure.com/translator/customtranslator/api/texttranslator/v1.0/index?workspaceId=<workspaceId>"

Delete adaptive dataset

Deletes a specific language pair dataset.

Request URL

   DELETE /index/<indexId>

Parameters

Request example

Windows

curl -X DELETE "https://<your-resource-name>.cognitiveservices.azure.com/translator/customtranslator/api/texttranslator/v1.0/index/<indexId>"

Linux/macOS

curl -X DELETE "https://<your-resource-name>.cognitiveservices.azure.com/translator/customtranslator/api/texttranslator/v1.0/index/<indexId>"

Translate with adaptive dataset ID

Use Text Translation API

Error responses

The API returns standard HTTP status codes. Common error responses:

Best practices

• Authentication: Use MI or access token
• Error Handling: Implement proper error handling and retry logic for API calls
• Project Organization: Use descriptive names for projects and adaptive datasets to organize related adaptive documents and datasets
• Document Management: Ensure TSV and TMX files are properly formatted with well aligned source-target pairs. Examples are available, in Foundry: select Build > Models > AI Services > Azure Translator - Text Translation > Adaptive LLM > Documents.

Troubleshooting

Authentication Errors:

• Verify your Azure tokens are valid and not expired.
• Check that all required environment variables are set.
• Ensure your Azure services are properly configured.

Index Creation Issues:

• Verify documents are properly uploaded before creating indices.
• Check that the Custom Translator API endpoint is accessible.
• Ensure your subscription is active.

Next steps

• Learn about custom translator models
• Learn about the text translation API
• Explore Foundry for advanced AI capabilities