Yandex.Translate API Developer's guide

Transcription

1

2 .. Version 1.5 Document build date: This volume is a part of Yandex technical documentation. Yandex helpdesk site: Yandex LLC. All rights reserved. Copyright Disclaimer Yandex (and its applicable licensor) has exclusive rights for all results of intellectual activity and equated to them means of individualization, used for development, support, and usage of the service. It may include, but not limited to, computer programs (software), databases, images, texts, other works and inventions, utility models, trademarks, service marks, and commercial denominations. The copyright is protected under provision of Part 4 of the Russian Civil Code and international laws. You may use or its components only within credentials granted by the Terms of Use of or within an appropriate Agreement. Any infringements of exclusive rights of the copyright owner are punishable under civil, administrative or criminal Russian laws. Contact information Yandex LLC Phone: pr@yandex-team.ru Headquarters: 16 L'va Tolstogo St., Moscow, Russia

3 Contents About this guide... 4 API description... 4 Formatting results... 4 API methods... 5 getlangs method... 5 detect method... 7 translate method... 8 Supported languages Index... 13

4 4 About this guide The developer's guide describes the and explains how to enable and use the service. The guide is intended for web developers who want to add the text translation feature to pages on their web sites. API description Attention! Starting from version 1.5, all API methods must be accessed using a key. Please fill out this simple form to get your free API key. To access the over HTTPS, there are XML and JSON (JSONP) interfaces available. All the interfaces provide identical functionality and use the same set of input parameters. The XML interface returns a response in the form of an XML document, while the JSON interface returns JavaScript objects instead of XML elements, but with the same names and semantics; the JSONP interface returns the same JavaScript objects, but by calling a callback function with the specified name. Formatting results When formatting translation results, you must follow the rules set in the License for using the Yandex.Translate service. Each page that uses data from the Yandex.Translate service must display the text "Powered by Yandex.Translate" with an active hyperlink to the page The font size for the link must be no smaller than the font size for the main text, and the color must match the font color of the main text on the page.

5 API methods 5 API methods getlangs method Returns a list of translation directions supported by the service. Description Langs getlangs(string key, string ui); The service translates between any of the languages in the list of supported languages. To get this list, set the ui parameter when calling the method. Input parameters List of input parameters: Parameter Type Description Mandatory key string API key. Get a free API key on this page. Optional ui string If set, the service's response will contain a list of supported language codes and the corresponding language names (langs): en in English ru in Russian tr in Turkish uk in Ukrainian Sample request: XML interface: JSON interface: JSONP interface (for the "mycallback" function): key=apikey&ui=uk&callback=mycallback Returns In the XML interface it returns an XML document with the root element Langs. For example:

6 API methods 6 <?xml version="1.0" encoding="utf-8"?> <Langs> <dirs> <string>ru-en</string> <string>ru-pl</string> <string>ru-uk</string> <string>ru-de</string> <string>ru-fr</string>... <string>sr-uk</string> </dirs> <langs> <Item key="ru" value="russian"/> <Item key="en" value="english"/> <Item key="pl" value="polish"/>... <Item key="tr" value="turkish"/> <Item key="ro" value="romanian"/> <Item key="sr" value="serbian"/> </langs> </Langs> Error codes Code Value Description ERR_KEY_INVALID 401 Invalid API key. ERR_KEY_BLOCKED 402 This API key has been blocked. In the JSON interface, instead of XML elements, JavaScript objects are returned with the same names and semantics: {"dirs": ["ru-en","ru-pl","ru-uk","ru-de","ru-fr","ru-es","ru-it","ru-bg","ru-cs","rutr","ru-ro","ru-sr","en-ru","en-uk","en-de","en-fr","en-es","en-it","en-cs","entr","pl-ru","pl-uk","uk-ru","uk-en","uk-pl","uk-de","uk-fr","uk-es","uk-it","ukbg","uk-cs","uk-tr","uk-ro","uk-sr","de-ru","de-en","de-uk","fr-ru","fr-en","fruk","es-ru","es-en","es-uk","it-ru","it-en","it-uk","bg-ru","bg-uk","cs-ru","csen","cs-uk","tr-ru","tr-en","tr-uk","ro-ru","ro-uk","sr-ru","sr-uk"], "langs": {"ru":"російська","en":"англійська","pl":"польська","uk":"українська","de":"німе цька","fr":"французька","es":"іспанська","it":"італійська","bg":"болгарська","cs ":"чеська","tr":"турецька","ro":"румунська","sr":"сербська"} } In the JSONP interface, the same JavaScript objects are returned to a callback function (for example, "mycallback"): mycallback( {"dirs":["ru-en","ru-pl","ru-uk","ru-de","ru-fr","ru-es","ru-it","ru-bg","rucs","ru-tr","ru-ro","ru-sr","en-ru","en-uk","en-de","en-fr","en-es","en-it","encs","en-tr","pl-ru","pl-uk","uk-ru","uk-en","uk-pl","uk-de","uk-fr","uk-es","ukit","uk-bg","uk-cs","uk-tr","uk-ro","uk-sr","de-ru","de-en","de-uk","fr-ru","fren","fr-uk","es-ru","es-en","es-uk","it-ru","it-en","it-uk","bg-ru","bg-uk","csru","cs-en","cs-uk","tr-ru","tr-en","tr-uk","ro-ru","ro-uk","sr-ru","sr-uk"], "langs": {"ru":"російська","en":"англійська","pl":"польська","uk":"українська","de":"німе цька","fr":"французька","es":"іспанська","it":"італійська","bg":"болгарська","cs ":"чеська","tr":"турецька","ro":"румунська","sr":"сербська"} })

7 API methods 7 detect method Detects the language of the specified text. Description DetectedLang detect(string key, string text[], string format); 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. Parameter Type Description Mandatory key string API key. Get a free API key on this page. text Optional string[ ] The text to detect the language for. Restrictions: format string Text format. Although the text parameter is an array (you can pass multiple text parameters), only one language tag is returned for the entire text. To detect the language of each text item, call the detect method for each of them. Possible values: plain Text without markup (default value). html Text in HTML format. Sample request: XML interface: JSON interface: JSONP interface (for the "mycallback" function): +world&callback=mycallback Returns In the XML interface it returns the DetectedLang structure, which contains the return code (200 if successful) and the text language code (or an empty string, if the language could not be detected). For example: <?xml version="1.0" encoding="utf-8"?> <DetectedLang code="200" lang="en"/> Error codes Code Value Description ERR_OK 200 Operation completed successfully.

8 API methods 8 Code Value Description ERR_KEY_INVALID 401 Invalid API key. ERR_KEY_BLOCKED 402 This API key has been blocked. ERR_DAILY_REQ_LIMIT _EXCEEDED ERR_DAILY_CHAR_LIMI T_EXCEEDED 403 You have reached the daily limit for requests (including calls of the translate method). 404 You have reached the daily limit for the volume of translated text (including calls of the translate method). In the JSON interface, instead of XML elements, JavaScript objects are returned with the same names and semantics: { } "code": 200, "lang": "en" In the JSONP interface, the same JavaScript objects are returned to a callback function (for example, "mycallback"): mycallback( { "code": 200, "lang": "en" } ) 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: +be,+or+not+to+be%3f&text=that+is+the+question. JSON interface: JSONP interface (for the "mycallback" function):

9 API methods 9 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 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: 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.

10 API methods 10 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 ERR_DAILY_CHAR_LIMI T_EXCEEDED 403 You have reached the daily limit for requests (including calls of the detect method). 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_T EXT ERR_LANG_NOT_SUPPOR TED 422 The text could not be translated. 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": [ "Быть или не быть?", "Вот в чем вопрос." ] })

11 Supported languages Язык Код Albanian sq Arabian ar Armenian hy Azeri az Belarusian be Bosnian bs Bulgarian bg Catalan ca Croatian hr Czech cs Chinese zh Danish da Dutch nl English en Estonian et Finnish fi French fr Georgian ka German de Greek el Hebrew he Hungarian hu Icelandic is Indonesian id Italian it Japanese ja Korean ko Latvian lv Lithuanian lt Macedonian mk Malay ms Maltese mt Norwegian no Polish pl Portuguese pt Romanian ro Russian ru Spanish es Serbian sr Slovak sk Slovenian sl Swedish sv 11

12 12 Язык Thai Turkish Ukrainian Vietnamese Код th tr uk vi

13 Index detect 6 getlangs 5 JSON 4 8, 10 JSONP 5 8, 10 translate 8 XML 5, 7 9

14