Описание программного интерфейса

Ядро-переводчик ЯРП можно использовать из программной среды через интерфейс, основанный на HTTP и XML. Японский текст и сопутствующие параметры передаются через данные POST-запроса в формате XML в кодировке UTF-8, машинный перевод возвращается в формате XML же. За один запрос можно заказать перевод нескольких фрагментов японского текста.

Запросы надо отправлять на следующий адрес:
http://www.yarp-online.ru/tran.php

Формат запроса

<YARP Key="Key">
  <Fragment Ref="RefID" Encode="Encode"
    Literal="Literal" ContextCode="ContextCode">
    <JText>JText</JText>
  </Fragment>
   ...
</YARP>

Смысл параметров такой:

• Key - это идентификатор учетной записи пользователя. Он же "ключ".
• RefID - это произвольная текстовая строка, которая идентифицирует фрагмент в системе пользователя. Можно не указывать.
• Encode - это числовой параметр (0/1), указывающий, нужно ли кодировать спецсимволы HTML/XML в выводе. По умолчанию 1 - кодировать.
• Literal - это числовой параметр (0/1). Если 1 - включается режим подстрочного перевода, без попыток синтеза русской фразы.
• ContextCode - это числовой параметр (0..12). Служит для выбора толкования многозначных японских слов. Определены следующие коды контекста:
  0. Нейтральный
  1. Общетехнический
  2. Электротехника
  3. Компьютеры
  4. Автомобили
  5. Фотография
  6. Точные науки
  7. Естественные науки
  8. Культура
  9. Экономика
  10. Право
  11. Военное дело
  12. Спорт
• JText - это, собственно, то, что надо перевести. В кодировке UTF-8.

Элементов <Fragment> можно указывать несколько. Параметры перевода берутся по умолчанию.

Формат ответа

<YARP Error="Error">
 <Fragment Ref="RefID" ID="ID" ErrorCode="ErrorCode" Error="Error">
  <RText>RText</RText>
 </Fragment>
 ...
</YARP>

Смысл полей такой:

• ErrorCode - числовой код ошибки.
• Error - текстовое описание ошибки. По-русски, в кодировке UTF-8.
• RText - перевод на русский в кодировке UTF-8.
• RefID - копия поля RefID из запроса.
• ID - числовой идентификатор фрагмента в системе ЯРП. Может пригодиться для последующего обсуждения перевода с тех. поддержкой.

Если атрибут Error присутствует в элементе <YARP>, это значит, что произошла ошибка глобального характера; элементов <Fragment> в ответе не будет. Если атрибуты Error или ErrorCode присутствуют в элементе <Fragment>, это означает, что произошла ошибка при переводе фрагмента и элемента <RText> в этом фрагменте нету.

Фрагменты в ответе идут в том же порядке, что и в запросе. Количество фрагментов тоже одинаковое - если при переводе фрагмента будет ошибка, он все равно будет присутствовать в ответе, с соответствующим кодом. Разбор текста через API недоступен.

Выдача ключей

Ключи для доступа в програмный интерфейс выдаются администрацией. Условия доступа - квота и цена - подлежат обсуждению в каждом конкретном случае отдельно. Чтобы получить ключ, пишите администрации. В письме объясните суть своего проекта, предполагаемые объемы перевода и природу подлежащих переводу текстов.

Примеры использования

Все примеры хранят запрос во внешнем файле in.xml. Ключ, который в нем прописан, рабочим не является. Подробности разбора, форматирования и вывода перевода зависят от специфики проекта, и поэтому в примерах отсутствуют.

На JavaScript c использованием библиотеки MSXML:

var xh = new ActiveXObject("MSXML2.XMLHTTP");
var doc = new ActiveXObject("MSXML2.DOMDocument");
doc.load("in.xml");
xh.open("POST", "http://www.yarp-online.ru/tran.php", false);
xh.send(doc);
WScript.Echo(xh.responseXML.xml);


Данный пример можно запускать непосредственно из Windows, сохранив его как файл с расширением .js, при условии, что файл in.xml находится в той же папке и в нем указан корректный ключ.

---

На PHP с использованием библиотеки CURL. Требует PHP версии не меньше 5.1.3.

<?php
$in = file_get_contents("in.xml");
$cu = curl_init("http://www.yarp-online.ru/tran.php");
curl_setopt_array($cu, array(
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => array('Content-Type: text/xml'),
  CURLOPT_POSTFIELDS => $in,
  CURLOPT_HEADER => false,
  CURLOPT_RETURNTRANSFER => true
  ));
$out = curl_exec($cu);
echo "<pre>".htmlspecialchars($out)."</pre>";
?>

Примеры для прочих языков и платформ могут быть добавлены по мере необходимости.