Translator v3.0

What's new?

Version 3.0 of the Translator provides a modern JSON-based Web API. It improves usability and performance by consolidating existing features into fewer operations and it provides new features.

• Transliteration to convert text in one language from one script to another script.
• Translation to multiple languages in one request.
• Language detection, translation, and transliteration in one request.
• Dictionary to look up alternative translations of a term, to find back-translations and examples showing terms used in context.
• More informative language detection results.

Base URLs

Requests to Translator are, in most cases, handled by the datacenter that is closest to where the request originated. If there's a datacenter failure when using the global endpoint, the request may be routed outside of the geography.

To force the request to be handled within a specific geography, use the desired geographical endpoint. All requests are processed among the datacenters within the geography.

✔️ Feature: Translator Text

Switzerland service endpoints

Customers with a resource located in Switzerland North or Switzerland West can ensure that their Text API requests are served within Switzerland. To ensure that requests are handled in Switzerland, create the Translator resource in the Resource region Switzerland North or Switzerland West, then use the resource's custom endpoint in your API requests.

For example: If you create a Translator resource in Azure portal with Resource region as Switzerland North and your resource name is my-swiss-n, then your custom endpoint is https​://my-swiss-n.cognitiveservices.azure.com. And a sample request to translate is:

// Pass secret key and region using headers to a custom endpoint
curl -X POST "https://my-swiss-n.cognitiveservices.azure.com/translator/text/v3.0/translate?to=fr" \
-H "Ocp-Apim-Subscription-Key: xxx" \
-H "Ocp-Apim-Subscription-Region: switzerlandnorth" \
-H "Content-Type: application/json" \
-d "[{'Text':'Hello'}]" -v

Custom Translator isn't currently available in Switzerland.

Virtual Network support

The Translator service is now available with Virtual Network (VNET) capabilities in all regions of the Azure public cloud. To enable Virtual Network, See Configuring Azure AI services virtual networks.

Once you turn on this capability, you must use the custom endpoint to call the Translator. You can't use the global translator endpoint ("api.cognitive.microsofttranslator.com") and you can't authenticate with an access token.

You can find the custom endpoint after you create a translator resource and allow access from selected networks and private endpoints.

1. Navigate to your Translator resource in the Azure portal.

2. Select Networking from the Resource Management section.

3. Under the Firewalls and virtual networks tab, choose Selected Networks and Private Endpoints.

   

4. Select Save to apply your changes.

5. Select Keys and Endpoint from the Resource Management section.

6. Select the Virtual Network tab.

7. Listed there are the endpoints for Text translation and Document translation.

   

Here's an example request to call the Translator using the custom endpoint

// Pass secret key and region using headers
curl -X POST "https://<your-custom-___domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Ocp-Apim-Subscription-Region:<your-region>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Metrics

Metrics allow you to view the translator usage and availability information in Azure portal. For more information, see Data and platform metrics.

This table lists available metrics with description of how they're used to monitor translation API calls.