Documentation

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
[no-highlight[

API key. It is issued free of charge.

]no-highlight]
=<API key> & text
[no-highlight[

The text to translate.

Tip. 

You can use multiple text parameters in a request.

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).

]no-highlight]
=<text to translate> & lang
[no-highlight[

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.
]no-highlight]
=<translation direction> & [format
[no-highlight[

Text format.

Possible values:

  • plain - Text without markup (default value).
  • html - Text in HTML format.
]no-highlight]
=<text format>] & [options
[no-highlight[

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.

]no-highlight]
=<translation options>] & [callback
[no-highlight[The name of the callback function. Use for getting a JSONP response.]no-highlight]
=<name of the callback function>]
key

API key. It is issued free of charge.

text

The text to translate.

Tip. 

You can use multiple text parameters in a request.

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.
POST /api/v1.5/tr.json/translate?lang=en-ru&key=API-KEY HTTP/1.1
Host: translate.yandex.net
Accept: */*
Content-Length: 17
Content-Type: application/x-www-form-urlencoded

text=Hello World!
HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8
Content-Length: 68
Connection: keep-alive
Keep-Alive: timeout=120
X-Content-Type-Options: nosniff
Date: Thu, 31 Mar 2016 10:50:20 GMT
{
    "code": 200,
    "lang": "en-ru",
    "text": [
        "Здравствуй, Мир!"
    ]
}

XML interface

The response is returned in XML format.

Request syntax

https://translate.yandex.net/api/v1.5/tr/translate ? 
key
[no-highlight[

API key. It is issued free of charge.

]no-highlight]
=<API key> & text
[no-highlight[

The text to translate.

Tip. 

You can use multiple text parameters in a request.

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).

]no-highlight]
=<text to translate> & lang
[no-highlight[

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.
]no-highlight]
=<translation direction> & [format
[no-highlight[

Text format.

Possible values:

  • plain - Text without markup (default value).
  • html - Text in HTML format.
]no-highlight]
=<text format>] & [options
[no-highlight[

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.

]no-highlight]
=<translation options>]
key

API key. It is issued free of charge.

text

The text to translate.

Tip. 

You can use multiple text parameters in a request.

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.
POST /api/v1.5/tr/translate?lang=en-ru&key=API-KEY HTTP/1.1
Host: translate.yandex.net
Accept: */*
Content-Length: 17
Content-Type: application/x-www-form-urlencoded

text=Hello World!
HTTP/1.1 200 OK
Server: nginx
Content-Type: application/xml; charset=utf-8
Content-Length: 68
Connection: keep-alive
Keep-Alive: timeout=120
X-Content-Type-Options: nosniff
Date: Thu, 31 Mar 2016 10:50:20 GMT

<?xml version="1.0" encoding="utf-8"?>
<Translation code="200" lang="en-ru">
    <text>Здравствуй, Мир!</text>
</Translation>

Response codes

Explanations of possible response codes.
ValueDescription
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