Translator 3.0: Detect

Grein
08/28/2024

Identifies the language of a piece of text.

Request URL

Send a POST request to:

https://api.cognitive.microsofttranslator.com/detect?api-version=3.0

See Virtual Network Support for Translator service selected network and private endpoint configuration and support.

Request parameters

Request parameters passed on the query string are:

Query parameter	Description
api-version	Required parameter. Version of the API requested by the client. Value must be `3.0`.

Request headers include:

Headers	Description
Authentication headers	Required request header. See available options for authentication.
Content-Type	Required request header. Specifies the content type of the payload. Possible values are: `application/json`.
Content-Length	Optional. The length of the request body.
X-ClientTraceId	Optional. A client-generated GUID to uniquely identify the request. You can omit this header if you include the trace ID in the query string using a query parameter named `ClientTraceId`.

Request body

The body of the request is a JSON array. Each array element is a JSON object with a string property named Text. Language detection is applied to the value of the Text property. The language autodetection works better with longer input text. A sample request body looks like that:

[
    { "Text": "Ich würde wirklich gerne Ihr Auto ein paar Mal um den Block fahren." }
]

The following limitations apply:

The array can have at most 100 elements.
The entire text included in the request can't exceed 50,000 characters including spaces.

Response body

A successful response is a JSON array with one result for each string in the input array. A result object includes the following properties:

language: Code of the detected language.
score: A float value indicating the confidence in the result. The score is between zero and one and a low score indicates a low confidence.
isTranslationSupported: A boolean value that is true if the detected language is one of the languages supported for text translation.
isTransliterationSupported: A boolean value that is true if the detected language is one of the languages supported for transliteration.
alternatives: An array of other possible languages. Each element of the array is another object the following properties: language, score, isTranslationSupported, and isTransliterationSupported.

An example JSON response is:

[

    {

        "language": "de",

        "score": 1.0,

        "isTranslationSupported": true,

        "isTransliterationSupported": false

    }

]

Response headers

Headers	Description
X-RequestId	Value generated by the service to identify the request and used for troubleshooting purposes.

Response status codes

The following are the possible HTTP status codes that a request returns.

Status Code	Description
200	Success.
400	One of the query parameters is missing or not valid. Correct request parameters before retrying.
401	The request couldn't be authenticated. Check that credentials are specified and valid.
403	The request isn't authorized. Check the details error message. This code often indicates that all free translations provided with a trial subscription are used.
429	The server rejected the request because the client exceeded request limits.
500	An unexpected error occurred. If the error persists, report it with: date and time of the failure, request identifier from response header `X-RequestId`, and client identifier from request header `X-ClientTraceId`.
503	Server temporarily unavailable. Retry the request. If the error persists, report it with: date and time of the failure, request identifier from response header `X-RequestId`, and client identifier from request header `X-ClientTraceId`.

If an error occurs, the request returns a JSON error response. The error code is a 6-digit number combining the 3-digit HTTP status code followed by a 3-digit number to further categorize the error. Common error codes can be found on the v3 Translator reference page.

Examples

The following example shows how to retrieve languages supported for text translation.

curl -X POST "https://api.cognitive.microsofttranslator.com/detect?api-version=3.0" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'What language is this text written in?'}]"

Deila með