Translating a text

Overview

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. The function name is 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=<callback function name>]
key

API key.

text

The text to be translated.

You can use several text parameters in the request.

Attention.

For the source text, use the URL encoding.

Limitations:

  • For POST requests, the maximum size of the text you pass is 10,000 characters.

  • In GET requests, limits aren't set on the text you pass. Instead, they're set on the entire query string that may include other parameters besides the text.

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

lang

Translation direction.

Can be set using one of the following methods:

  • With a pair of language codes (“from”-“to”) separated with a hyphen. For example, en-ru indicates a translation from English to Russian.
  • With a 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

Currently, the only available option is to include the automatically defined source language in the response. This corresponds to the parameter value 1.

If the source language is set explicitly, meaning the lang parameter contains a pair of codes, the fist code sets the source language. This means that the options parameter doesn't let you switch to automatic language detection. However, it lets you know whether the source language was specified correctly in the lang parameter.

callbackName of the callback function. Used to get a JSONP response.
key

API key.

text

The text to be translated.

You can use several text parameters in the request.

Attention.

For the source text, use the URL encoding.

Limitations:

  • For POST requests, the maximum size of the text you pass is 10,000 characters.

  • In GET requests, limits aren't set on the text you pass. Instead, they're set on the entire query string that may include other parameters besides the text.

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

lang

Translation direction.

Can be set using one of the following methods:

  • With a pair of language codes (“from”-“to”) separated with a hyphen. For example, en-ru indicates a translation from English to Russian.
  • With a 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

Currently, the only available option is to include the automatically defined source language in the response. This corresponds to the parameter value 1.

If the source language is set explicitly, meaning the lang parameter contains a pair of codes, the fist code sets the source language. This means that the options parameter doesn't let you switch to automatic language detection. However, it lets you know whether the source language was specified correctly in the lang parameter.

callbackName of the callback function. Used to get a JSONP response.
Note. All special characters must be escaped.
Example request
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=<API key>]
 & [text=<text to translate>]
 & [lang=<translation direction>]
 & [format=<text format>]
 & [options=<translation options>]
key

API key.

text

The text to be translated.

You can use several text parameters in the request.

Attention.

For the source text, use the URL encoding.

Limitations:

  • For POST requests, the maximum size of the text you pass is 10,000 characters.

  • In GET requests, limits aren't set on the text you pass. Instead, they're set on the entire query string that may include other parameters besides the text.

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

lang

Translation direction.

Can be set using one of the following methods:

  • With a pair of language codes (“from”-“to”) separated with a hyphen. For example, en-ru indicates a translation from English to Russian.
  • With a 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

Currently, the only available option is to include the automatically defined source language in the response. This corresponds to the parameter value 1.

If the source language is set explicitly, meaning the lang parameter contains a pair of codes, the fist code sets the source language. This means that the options parameter doesn't let you switch to automatic language detection. However, it lets you know whether the source language was specified correctly in the lang parameter.

key

API key.

text

The text to be translated.

You can use several text parameters in the request.

Attention.

For the source text, use the URL encoding.

Limitations:

  • For POST requests, the maximum size of the text you pass is 10,000 characters.

  • In GET requests, limits aren't set on the text you pass. Instead, they're set on the entire query string that may include other parameters besides the text.

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

lang

Translation direction.

Can be set using one of the following methods:

  • With a pair of language codes (“from”-“to”) separated with a hyphen. For example, en-ru indicates a translation from English to Russian.
  • With a 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

Currently, the only available option is to include the automatically defined source language in the response. This corresponds to the parameter value 1.

If the source language is set explicitly, meaning the lang parameter contains a pair of codes, the fist code sets the source language. This means that the options parameter doesn't let you switch to automatic language detection. However, it lets you know whether the source language was specified correctly in the lang parameter.

Note. All special characters must be escaped.
Example request
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!

Response codes

Description of response codes.

Value Description
200

The operation was completed successfully
401

Invalid API key
402

The API key is blocked
404

The daily limit on the amount of translated text is exceeded
413

The maximum allowed text size is exceeded
422

The text can't be translated
501

The specified translation direction isn't supported
Value Description
200

The operation was completed successfully
401

Invalid API key
402

The API key is blocked
404

The daily limit on the amount of translated text is exceeded
413

The maximum allowed text size is exceeded
422

The text can't be translated
501

The specified translation direction isn't supported