Translator - Languages

Service:: Azure AI Services

API Version:: 3.0

Gets the set of languages currently supported by other operations of the Translator Text API. Authentication is not required to get language resources.

Response Body

A client uses the scope query parameter to define which groups of languages it is interested in.

scope=translation provides languages supported to translate text from one language to another language.
scope=transliteration provides capabilities for converting text in one language from one script to another script.
scope=dictionary provides language pairs for which Dictionary operations return data.

A client may retrieve several groups simultaneously by specifying a comma-separated list of names. For example, scope=translation,transliteration,dictionary would return supported languages for all groups.

A successful response is a JSON object with one property for each requested group. The value for each property is as follows.

translation property The value of the translation property is a dictionary of (key, value) pairs. Each key is a BCP 47 language tag. A key identifies a language for which text can be translated to or translated from. The value associated with the key is a JSON object with properties that describe the language
- name- Display name of the language in the locale requested via Accept-Language header.
- nativeName- Display name of the language in the locale native for this language.
- dir- Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages.

{
  "translation": {
  ...
  "fr": {
  "name": "French",
  "nativeName": "Français",
  "dir": "ltr"
  },
...
 }
}

transliteration property The value of the transliteration property is a dictionary of (key, value) pairs. Each key is a BCP 47 language tag. A key identifies a language for which text can be converted from one script to another script. The value associated with the key is a JSON object with properties that describe the language and its supported scripts
- name- Display name of the language in the locale requested via Accept-Language header.
- nativeName- Display name of the language in the locale native for this language.
- scripts- List of scripts to convert from. Each element of the scripts list has properties-
  - code- Code identifying the script.
  - name- Display name of the script in the locale requested via Accept-Language header.
  - nativeName- Display name of the language in the locale native for the language.
  - dir- Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages.
  - toScripts- List of scripts available to convert text to. Each element of the toScripts list has properties code, name, nativeName, and dir as described earlier.

{
  "transliteration": {
    ...
    "ja": {
      "name": "Japanese",
      "nativeName": "日本語",
      "scripts": [
        {
          "code": "Jpan",
          "name": "Japanese",
          "nativeName": "日本語",
          "dir": "ltr",
          "toScripts": [
            {
              "code": "Latn",
              "name": "Latin",
              "nativeName": "ラテン語",
              "dir": "ltr"
            }
          ]
        },
        {
          "code": "Latn",
          "name": "Latin",
          "nativeName": "ラテン語",
          "dir": "ltr",
          "toScripts": [
          {
            "code": "Jpan",
            "name": "Japanese",
            "nativeName": "日本語",
            "dir": "ltr"
          }
          ]
        }
      ]
    },
  ...
  }
}

dictionary property The value of the dictionary property is a dictionary of (key, value) pairs. Each key is a BCP 47 language tag. The key identifies a language for which alternative translations and back-translations are available. The value is a JSON object that describes the source language and the target languages with available translations.
- name- Display name of the source language in the locale requested via Accept-Language header.
- nativeName- Display name of the language in the locale native for this language.
- dir- Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages.
- translations- List of languages with alterative translations and examples for the query expressed in the source language. Each element of the translations list has properties
  - name- Display name of the target language in the locale requested via Accept-Language header.
  - nativeName- Display name of the target language in the locale native for the target language.
  - dir- Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages.
  - code- Language code identifying the target language.


"es": {
  "name": "Spanish",
  "nativeName": "Español",
  "dir": "ltr",
  "translations": [
    {
      "name": "English",
      "nativeName": "English",
      "dir": "ltr",
      "code": "en"
    }
  ]
},

The structure of the response object will not change without a change in the version of the API. For the same version of the API, the list of available languages may change over time because Microsoft Translator continually extends the list of languages supported by its services.

The list of supported languages will not change frequently. To save network bandwidth and improve responsiveness, a client application should consider caching language resources and the corresponding entity tag (ETag). Then, the client application can periodically (for example, once every 24 hours) query the service to fetch the latest set of supported languages. Passing the current ETag value in an If-None-Match header field will allow the service to optimize the response. If the resource has not been modified, the service will return status code 304 and an empty response body.

Response Header

ETag - Current value of the entity tag for the requested groups of supported languages. To make subsequent requests more efficient, the client may send the ETag value in an If-None-Match header field.

X-RequestId - Value generated by the service to identify the request. It is used for troubleshooting purposes.

GET {Endpoint}/Languages?api-version=3.0

With optional parameters:

GET {Endpoint}/Languages?api-version=3.0&scope={scope}

URI Parameters

Name	In	Required	Type	Description
Endpoint	path	True	string	Supported Cognitive Services endpoints
api-version	query	True	string	Version of the API requested by the client. Value must be 3.0.
scope	query		string[]	A comma-separated list of names defining the group of languages to return. Allowed group names are- `translation`, `transliteration` and `dictionary`. If no scope is given, then all groups are returned, which is equivalent to passing `scope=translation,transliteration,dictionary`. To decide which set of supported languages is appropriate for your scenario, see the description of the response object.

Request Header

Name	Required	Type	Description
Accept-Language		string	The language to use for user interface strings. Some of the fields in the response are names of languages or names of regions. Use this parameter to define the language in which these names are returned. The language is specified by providing a well-formed BCP 47 language tag. For instance, use the value `fr` to request names in French or use the value `zh-Hant` to request names in Chinese Traditional. Names are provided in the English language when a target language is not specified or when localization is not available.
X-ClientTraceId		string	A client-generated GUID to uniquely identify the request. Note that you can omit this header if you include the trace ID in the query string using a query parameter named ClientTraceId.

Responses

Name	Type	Description
200 OK	LanguagesResult	Success
Other Status Codes	ErrorMessage	Error response.

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Ocp-Apim-Subscription-Region

Type: apiKey
In: header

Examples

Languages success example

Sample request

HTTP

GET https://api.cognitive.microsofttranslator.com/Languages?api-version=3.0&scope=translation

Sample response

Status code:: 200

{
  "translation": {
    "af": {
      "name": "Afrikaan",
      "nativeName": "Afrikaans",
      "dir": "ltr"
    },
    "ar": {
      "name": "Arabic",
      "nativeName": "العربية",
      "dir": "rtl"
    },
    "ja": {
      "name": "Japanese",
      "nativeName": "日本語",
      "dir": "ltr"
    },
    "ko": {
      "name": "Korean",
      "nativeName": "한국어",
      "dir": "ltr"
    },
    "th": {
      "name": "Thai",
      "nativeName": "ไทย",
      "dir": "ltr"
    },
    "zh-Hans": {
      "name": "Chinese Simplified",
      "nativeName": "简体中文",
      "dir": "ltr"
    },
    "zh-Hant": {
      "name": "Chinese Traditional",
      "nativeName": "繁體中文",
      "dir": "ltr"
    }
  }
}

Definitions

Name	Description
Dictionary
Error
ErrorMessage
LanguageCode
LanguagesResult	Example of a successful languages request
Scripts
ToScripts
Translation
translation.LanguageCode
Translations
Transliteration
transliteration.LanguageCode

Dictionary

Object

Name	Type	Description
languageCode	LanguageCode

Error

Object

Name	Type	Description
code	string
message	string

ErrorMessage

Object

Name	Type	Description
error	Error

LanguageCode

Object

Name	Type	Description
dir	string
name	string
nativeName	string
translations	Translations[]

LanguagesResult

Object

Example of a successful languages request

Name	Type	Description
dictionary	Dictionary
translation	Translation
transliteration	Transliteration

Scripts

Object

Name	Type	Description
code	string
dir	string
name	string
nativeName	string
toScripts	ToScripts[]

ToScripts

Object

Name	Type	Description
code	string
dir	string
name	string
nativeName	string

Translation

Object

Name	Type	Description
languageCode	translation.LanguageCode

translation.LanguageCode

Object

Name	Type	Description
dir	string
name	string
nativeName	string

Translations

Object

Name	Type	Description
code	string
dir	string
name	string
nativeName	string

Transliteration

Object

Name	Type	Description
languageCode	transliteration.LanguageCode

transliteration.LanguageCode

Object

Name	Type	Description
name	string
nativeName	string
scripts	Scripts[]

Share via

Translator - Languages

Response Body

Response Header

URI Parameters

Request Header

Responses

Security

Ocp-Apim-Subscription-Key

Ocp-Apim-Subscription-Key

Ocp-Apim-Subscription-Region

Examples

Languages success example

Sample request

Sample response

Definitions

Dictionary

Error

ErrorMessage

LanguageCode

LanguagesResult

Scripts

ToScripts

Translation

translation.LanguageCode

Translations

Transliteration

transliteration.LanguageCode