Translate text

Translates text to the specified language.

In this section:

JSON and JSONP interfaces

The response is returned in JSON format. If the callback parameter is set, the JSON object is wrapped in a function with the name specified in this parameter (JSONP).

Request syntax

https://translate.yandex.net/api/v1.5/tr.json/translate
 ? key=<API key>
 & text=<text to translate>
 & lang=<translation direction>
 & [format=<text format>]
 & [options=<translation options>]
 & [callback=<name of the callback function>]
Query parameters
key*

API key. It is issued free of charge.

text*

The text to translate.

You can use multiple text parameters in a request.

Attention.

The source text must be URL-encoded.

Restrictions:

  • For POST requests, the maximum size of the text being passed is 10,000 characters.

  • In GET requests, the restriction applies not to the text itself, but to the size of the entire request string, which can contain other parameters besides the text.

    The maximum size of the string is from 2 to 10 KB (depending on the browser version).

lang*

The translation direction.

You can set it in either of the following ways:

  • As a pair of language codes separated by a hyphen (“from”-“to”). For example, en-ru indicates translating from English to Russian.
  • As the target language code (for example, ru). In this case, the service tries to detect the source language automatically.
format

Text format.

Possible values:

  • plain - Text without markup (default value).
  • html - Text in HTML format.
options

The only option available at this time is whether the response should include the automatically detected language of the text being translated. This corresponds to the value 1 for this parameter.

If the language of the text being translated is defined explicitly, meaning the lang parameter is set as a pair of codes, the first code defines the source language. This means that the options parameter does not allow switching to automatic language detection. However, it does allow you to understand whether the source language was defined correctly in the lang parameter.

callbackThe name of the callback function. Use for getting a JSONP response.
Query parameters
key*

API key. It is issued free of charge.

text*

The text to translate.

You can use multiple text parameters in a request.

Attention.

The source text must be URL-encoded.

Restrictions:

  • For POST requests, the maximum size of the text being passed is 10,000 characters.

  • In GET requests, the restriction applies not to the text itself, but to the size of the entire request string, which can contain other parameters besides the text.

    The maximum size of the string is from 2 to 10 KB (depending on the browser version).

lang*

The translation direction.

You can set it in either of the following ways:

  • As a pair of language codes separated by a hyphen (“from”-“to”). For example, en-ru indicates translating from English to Russian.
  • As the target language code (for example, ru). In this case, the service tries to detect the source language automatically.
format

Text format.

Possible values:

  • plain - Text without markup (default value).
  • html - Text in HTML format.
options

The only option available at this time is whether the response should include the automatically detected language of the text being translated. This corresponds to the value 1 for this parameter.

If the language of the text being translated is defined explicitly, meaning the lang parameter is set as a pair of codes, the first code defines the source language. This means that the options parameter does not allow switching to automatic language detection. However, it does allow you to understand whether the source language was defined correctly in the lang parameter.

callbackThe name of the callback function. Use for getting a JSONP response.
Note. All special characters must be escaped.

XML interface

The response is returned in XML format.

Request syntax

https://translate.yandex.net/api/v1.5/tr/translate
 ? key=<API key>
 & text=<text to translate>
 & lang=<translation direction>
 & [format=<text format>]
 & [options=<translation options>]
Query parameters
key*

API key. It is issued free of charge.

text*

The text to translate.

You can use multiple text parameters in a request.

Attention.

The source text must be URL-encoded.

Restrictions:

  • For POST requests, the maximum size of the text being passed is 10,000 characters.

  • In GET requests, the restriction applies not to the text itself, but to the size of the entire request string, which can contain other parameters besides the text.

    The maximum size of the string is from 2 to 10 KB (depending on the browser version).

lang*

The translation direction.

You can set it in either of the following ways:

  • As a pair of language codes separated by a hyphen (“from”-“to”). For example, en-ru indicates translating from English to Russian.
  • As the target language code (for example, ru). In this case, the service tries to detect the source language automatically.
format

Text format.

Possible values:

  • plain - Text without markup (default value).
  • html - Text in HTML format.
options

The only option available at this time is whether the response should include the automatically detected language of the text being translated. This corresponds to the value 1 for this parameter.

If the language of the text being translated is defined explicitly, meaning the lang parameter is set as a pair of codes, the first code defines the source language. This means that the options parameter does not allow switching to automatic language detection. However, it does allow you to understand whether the source language was defined correctly in the lang parameter.

Query parameters
key*

API key. It is issued free of charge.

text*

The text to translate.

You can use multiple text parameters in a request.

Attention.

The source text must be URL-encoded.

Restrictions:

  • For POST requests, the maximum size of the text being passed is 10,000 characters.

  • In GET requests, the restriction applies not to the text itself, but to the size of the entire request string, which can contain other parameters besides the text.

    The maximum size of the string is from 2 to 10 KB (depending on the browser version).

lang*

The translation direction.

You can set it in either of the following ways:

  • As a pair of language codes separated by a hyphen (“from”-“to”). For example, en-ru indicates translating from English to Russian.
  • As the target language code (for example, ru). In this case, the service tries to detect the source language automatically.
format

Text format.

Possible values:

  • plain - Text without markup (default value).
  • html - Text in HTML format.
options

The only option available at this time is whether the response should include the automatically detected language of the text being translated. This corresponds to the value 1 for this parameter.

If the language of the text being translated is defined explicitly, meaning the lang parameter is set as a pair of codes, the first code defines the source language. This means that the options parameter does not allow switching to automatic language detection. However, it does allow you to understand whether the source language was defined correctly in the lang parameter.

Note. All special characters must be escaped.

Response codes

Explanations of possible response codes.

Value Description
200

Operation completed successfully
401

Invalid API key
402

Blocked API key
404

Exceeded the daily limit on the amount of translated text
413

Exceeded the maximum text size
422

The text cannot be translated
501

The specified translation direction is not supported
Value Description
200

Operation completed successfully
401

Invalid API key
402

Blocked API key
404

Exceeded the daily limit on the amount of translated text
413

Exceeded the maximum text size
422

The text cannot be translated
501

The specified translation direction is not supported