Microsoft Azure

Azure AI Services: Translator Text

Introduction The Microsoft Translator Text API provides a JSON-based Web API. It provides: * Translation between any supported languages to any other…

AI & machine learning#openapi

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

Introduction

The Microsoft Translator Text API provides a JSON-based Web API. It provides:

  • Translation between any supported languages to any other supported language.
  • Translation to multiple languages in one request.
  • Transliteration to convert text from one script to another script of the same language.
  • Language detection, translation, and transliteration in one request.
  • Dictionary to lookup alternative translations of a term, to find back-translations and examples showing terms used in context.
  • Rich language detection.

Base URLs

The Translator Text API is available in the following clouds:

DescriptionRegionBase URL
AzureGlobalapi.cognitive.microsofttranslator.com
AzureEuropeapi-eur.cognitive.microsofttranslator.com

Authentication

Subscribe to the Translator Text API, part of Azure Cognitive Services, and use your subscription key from the Azure portal to authenticate. You can follow the steps in https://docs.microsoft.com/en-us/azure/cognitive-services/translator/translator-text-how-to-signup.

The simplest way is to pass your Azure secret key to the Translator service using the http request header Ocp-Apim-Subscription-Key.

If you prefer using a short-lived authentication, you may use your secret key to obtain an authorization token from the token service. In that case you pass the authorization token to the Translator service using the Authorization request header. To obtain an authorization token, make a POST request to the following URL:

EnvironmentAuthentication service URL
Azurehttps://api.cognitive.microsoft.com/sts/v1.0/issueToken

Here are example requests to obtain a token with a lifetime of 10 minutes, given a secret key:

// Pass secret key using header
curl --header 'Ocp-Apim-Subscription-Key:  ' --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken'
// Pass secret key using query string parameter
curl --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key= '

A successful request returns the encoded access token as plain text in the response body. The valid token is passed to the Translator service as a bearer token in the Authorization.

Authorization: Bearer

An authentication token is valid for 10 minutes. The token should be re-used when making multiple calls to the Translator APIs. If you make requests to the Translator API over an extended period of time, you must request a new access token at regular intervals before the token expires, for instance every 9 minutes.

To summarize, a client request to the Translator API will include one authorization header taken from the following table:

HeadersDescription
Ocp-Apim-Subscription-keyUse with Cognitive Services subscription if you are passing your secret key. The value is the Azure secret key for your subscription to Translator Text API.
AuthorizationUse with Cognitive Services subscription if you are passing an authentication token. The value is the Bearer token: Bearer .

All-in-one subscription

The last authentication option is to use a Cognitive Service’s all-in-one subscription. This allows you to use a single secret key to authenticate requests for multiple services.
When you use an all-in-one secret key, you must include two authentication headers with your request. The first passes the secret key, the second specifies the region associated with your subscription.
Ocp-Api-Subscription-Key Ocp-Apim-Subscription-Region
If you pass the secret key in the query string with the parameter Subscription-Key, then you must specify the region with query parameter Subscription-Region.
If you use a bearer token, you must obtain the token from the region endpoint:
https:// .api.cognitive.microsoft.com/sts/v1.0/issueToken.

Available regions are: australiaeast, brazilsouth, canadacentral, centralindia, centraluseuap, eastasia, eastus, eastus2, japaneast, northeurope, southcentralus, southeastasia, uksouth, westcentralus, westeurope, westus, and westus2.

Region is required for the all-in-one Text API subscription.

Errors

A standard error response is a JSON object with name/value pair named error. The value is also a JSON object with properties:

  • code: A server-defined error code.
  • message: A string giving a human-readable representation of the error.

For example, a customer with a free trial subscription receives the following error once the free quota is exhausted:

{
  "error": {
  "code":403000,
  "message":"The subscription has exceeded its…

Endpoints 7

BreakSentence

  • POSTTranslator_BreakSentence/BreakSentence?api-version=3.0&Language=string&Script=stringIdentifies the position of sentence boundaries in a piece of text.

Detect

  • POSTTranslator_Detect/Detect?api-version=3.0Identifies the language of a string of text.

Dictionary/Lookup

  • POSTTranslator_DictionaryLookup/Dictionary/Lookup?api-version=3.0&from=string&to=stringProvides alternative translations for a word and a small number of idiomatic phrases. Each translation has a part-of-speech and a list of back-translations.…

DictionaryExamples

  • POSTTranslator_DictionaryExamples/Dictionary/Examples?api-version=3.0&from=string&to=stringProvides examples that show how terms in the dictionary are used in context. This operation is used in tandem with Dictionary lookup.

Languages

  • GETTranslator_Languages/Languages?api-version=3.0&scope=translationGets the set of languages currently supported by other operations of the Translator Text API. Authentication is not required to get language resources.…

Translate

  • POSTTranslator_Translate/translate?api-version=3.0&from=string&to=string&textType=plain&category=string&profanityAction=NoAction&profanityMarker=string&includeAlignment=true&includeSentenceLength=true&suggestedFrom=string&fromScript=string&toScript=stringTranslates text into one or more languages.

Transliterate

  • POSTTranslator_Transliterate/transliterate?api-version=3.0&language=string&fromScript=string&toScript=stringConverts the text of a language in one script into another type of script. Example- Japanese script "こんにちは" Same word in Latin script "konnichiha"

API details

Base URL
https://api.cognitive.microsofttranslator.com
Authentication
An API key in the Ocp-Apim-Subscription-Key header
An API key in the Ocp-Apim-Subscription-Key header
An API key in the Ocp-Apim-Subscription-Region header
Operations
7 operations on 7 pathsPOST 6GET 1
Main resources
BreakSentence 1Detect 1Dictionary/Lookup 1DictionaryExamples 1Languages 1Translate 1Transliterate 1
Response formats
application/json
Description format
Swagger 2.0, API version 3.0

How to test the Azure AI Services: Translator Text in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Azure AI Services: Translator Text collection, without the publisher's secrets.
  3. Add your credentialsThis API uses an API key in the Ocp-Apim-Subscription-Key header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Translator_BreakSentence” (POST /BreakSentence?api-version=3.0&Language=string&Script=string), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Azure AI Services: Translator Text?

Introduction The Microsoft Translator Text API provides a JSON-based Web API. It provides: * Translation between any supported languages to any other… It is listed under AI & machine learning and has 7 endpoints.

Who publishes the Azure AI Services: Translator Text?

It is listed from Microsoft Azure's public API description (an OpenAPI document), not published by Microsoft Azure on Swastik Codes. Anyone who controls azure.com can claim the profile by adding a DNS TXT record.

What is the base URL of the Azure AI Services: Translator Text?

Requests go to https://api.cognitive.microsofttranslator.com. Endpoint paths are added to this base URL.

How do I authenticate with the Azure AI Services: Translator Text?

It accepts 3 methods: an API key in the Ocp-Apim-Subscription-Key header; an API key in the Ocp-Apim-Subscription-Key header; an API key in the Ocp-Apim-Subscription-Region header.

How many endpoints does the Azure AI Services: Translator Text have?

7 operations on 7 paths (6 POST, 1 GET). The largest groups are BreakSentence, Detect, Dictionary/Lookup, DictionaryExamples.

Is forking the Azure AI Services: Translator Text free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.