SearchImagesVideo
Search

Yandex.Translate API:

Login

Developer's guide
View as PDF
← Ctrl previousnext Ctrl →

translate method

Translates the text.

Description

Translation translate(string key, string lang, string text[], string format, string options);

Input parameters

Input parameters can be passed either using an HTTP GET request (see the example), or using an HTTP POST request where the parameters are passed in the body of the HTTP request.

Sample request:

XML interface:

https://translate.yandex.net/api/v1.5/tr/translate?key=APIkey&lang=en-ru&text=To+be,+or+not+to+be%3F&text=That+is+the+question.

JSON interface:

https://translate.yandex.net/api/v1.5/tr.json/translate?key=APIkey&lang=en-ru&text=To+be,+or+not+to+be%3F&text=That+is+the+question.

JSONP interface (for the "myCallback" function):

https://translate.yandex.net/api/v1.5/tr.json/translate?key=APIkey&lang=en-ru&text=To+be,+or+not+to+be%3F&text=That+is+the+question.&callback=myCallback

List of input parameters.

Parameter Type Description
Mandatory
key string API key. Get a free API key on this page.
lang string

Translation direction (for example, "en-ru" or "ru"). Format:

  1. A pair of language codes separated by a dash. For example, "en-ru" specifies to translate from English to Russian.
  2. Single language code. For example, "ru" specifies to translate to Russian. In this case, the language of the original text is detected automatically.
text string[]

The text to be translated.

Restrictions:

  • For POST requests, the maximum size of the text being passed is 10000 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 request string is 10 KB.
Optional
format string

Text format.

Possible values:

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

Translation options.

Possible values:

  • 1 - Automatically detect language. For example, if the lang parameter has reversed the translation direction for a pair, the service automatically detects the text language and returns it in the detected tag: 
    http://translate.yandex.net/api/v1.5/tr/translate?key=APIkey&lang=en-ru&text=привет&options=1
    <Translation code="200" lang="en-ru">
  <detected lang="ru"/>
  <text>привет</text>
</Translation>

Returns

In the XML interface, it returns the Translation structure, which contains the translated text. For example:

<?xml version="1.0" encoding="utf-8"?>
<Translation code="200" lang="en-ru">
   <text>Быть или не быть?</text>
   <text>Вот в чем вопрос.</text>
</Translation>

Elements of the response XML schema:

  • Translation — The root element, which contains text elements (one per fragment). The code attribute contains the return code (see the table) and the lang attribute, which is the language code of the text fragment detected by the service.
  • text — An array of strings with translated text (for the XML interface, a sequence of <text> elements). The number of items in the array corresponds to the number of text parameters in the request.

Table 2.  Error codes

Code Value Description
ERR_OK 200

Operation completed successfully.
ERR_KEY_INVALID 401

Invalid API key.
ERR_KEY_BLOCKED 402

This API key has been blocked.
ERR_DAILY_REQ_LIMIT_EXCEEDED 403

You have reached the daily limit for requests (including calls of the detect method).
ERR_DAILY_CHAR_LIMIT_EXCEEDED 404

You have reached the daily limit for the volume of translated text (including calls of the detect method).
ERR_TEXT_TOO_LONG 413

The text size exceeds the maximum.
ERR_UNPROCESSABLE_TEXT 422

The text could not be translated.

ERR_LANG_NOT_SUPPORTED 501

The specified translation direction is not supported.

In the JSON interface, instead of XML elements, JavaScript objects are returned with the same names and semantics:

{
   "code": 200,
   "lang": "en-ru",
   "text": [
      "Быть или не быть?",
      "Вот в чем вопрос."
    ]
}

In the JSONP interface, the same JavaScript objects are returned to a callback function (for example, "myCallback"):

myCallback({
   "code": 200,
   "lang": "en-ru",
   "text": [
      "Быть или не быть?",
      "Вот в чем вопрос."
    ]
})