POST https://app.yarakuzen.com/api

Workflow

The YarakuZen API enables access to the full translation functionality of the YarakuZen web application. The API is designed to be asynchronous. That means that the API will not directly reply to the original request. Instead, it will give a RESPONSE to acknowledge the translation request/order. After the API has finished processing the request, it will then send a CALLBACK to the user’s designated callback server.

As an end-user, you need to do these 2 steps to get translation results.

1. Make a POST request to the YarakuZen API
2. After some time, check your Callback Server for the result.

For more information on how to properly format the POST request, please refer here.

Client

Our API is not language-specific. Clients written in any language that can send HTTP requests will work.
If you don't have a preferred language, a simple client written in PHP is:

• PHP Client - https://github.com/yaraku/yarakuzen-api-php-client

POST Requests

The POST request can be used to access 3 of YarakuZen’s features.

1. Order Translation
2. Order Estimation
3. Machine Translation

$params['publicKey'] = "A30qt7sh1QrOdhvFTHjJoIBCkptwMPm2";
$params['timestamp'] = 1418287283;
$params['signature'] = "77ff2ddad9d9e5eAa6ed07b5ec2e327ac2666fea";
$params['lcSrc'] = "en";
$params['lcTgt'] = "ja";

$params['tier'] = "standard";

$params['texts'][0]['customData'] = "12345";
$params['texts'][0]['text'] = "Hello world!";
$params['texts'][1]['customData'] = "12346";
$params['texts'][1]['text'] = "Hello Japan!";
                        

$params['publicKey'] = "A30qt7sh1QrOdhvFTHjJoIBCkptwMPm2";
$params['timestamp'] = 1418287283;
$params['signature'] = "77ff2ddad9d9e5eAa6ed07b5ec2e327ac2666fea";
$params['lcSrc'] = "en";
$params['lcTgt'] = "ja";

$params['tier'] = "standard";
$params['quote'] = 1;

$params['texts'][0]['customData'] = "12345";
$params['texts'][0]['text'] = "Hello world!";
$params['texts'][1]['customData'] = "12346";
$params['texts'][1]['text'] = "Hello Japan!";
                        

$params['publicKey'] = "A30qt7sh1QrOdhvFTHjJoIBCkptwMPm2";
$params['timestamp'] = 1418287283;
$params['signature'] = "77ff2ddad9d9e5eAa6ed07b5ec2e327ac2666fea";
$params['lcSrc'] = "en";
$params['lcTgt'] = "ja";

$params['persist'] = 1;
$params['machineTranslate'] = 1;

$params['texts'][0]['customData'] = "12345";
$params['texts'][0]['text'] = "Hello world!";
$params['texts'][1]['customData'] = "12346";
$params['texts'][1]['text'] = "Hello Japan!";
                        

See the Parameter section for required and optional arguments, and how to use them.

Parameters

publicKey Your YarakuZen public api key.

timestamp Unix timestamp, as an integer, used to hash the signature.

signature A signature in form of a hash that is used to authenticate the request. It is created in the following way:

$privateKey = 'jU7YpdyPtnwcmoEvk0hgXS14QMh3GCcF'; // Your YarakuZen private api key

$publicKey = 'A30qt7sh1QrOdhvFTHjJoIBCkptwMPm2'; // Your YarakuZen public api key

$timestamp = time(); // A Unix timestamp

$signature = hash_hmac('sha1', $timestamp.$publicKey, $privateKey); // Create a sha1 hash

$params['signature'] = $signature; // Add the sha1 hash as the signature parameter

$params['timestamp'] = $timestamp; // Add the timestamp as a parameter

$params['publicKey'] = $publicKey; // Add the public key as a parameter                        

lcSrc The language code for the language of your source text.

lcTgt The language code for the language you want the text to be translated to.

texts An array of texts that you want to translate, see details.

tier(Optional) The level of the translation you want to order. Don't include it if you do not want to order translation. The tier parameter becomes mandatory when the quote parameter is included.

quote(Optional) Include this parameter and set it to integer 1 if you want to get an estimation. No texts will be ordered and no funds will be charged. The tier parameter becomes mandatory when the quote parameter is included.

persist(Optional) Set this integer to 1 if you want to save the source text and thereby be able to manually translate the text in YarakuZen. Defaults to 0. This will happen automatically if you order translations.

machineTranslate(Optional) Set this integer to 0 if you don't want the request to be machine translated. Defaults to 1.

Text object

customData A container for data that for example can be used to identify the text in the system that sends the request.

text The text you want to translate.
Note that number of characters per text object is limited: 3,000 characters for free accounts and 10,000 for premium/company accounts. If you exceed these limits, you will get apiRequestTextSizeExcessive error in response. Same limits apply to total number of characters in array of text objects. If you exceed number of characters in array of texts, you will get apiRequestSizeExcessive in response.

Response

Here is an example of the Response that the API will return.

{
  "texts": [
    {
      "customData": "12345",
      "text":       "Hello world!"
    },
    {
      "customData": "12346",
      "text":       "Hello Japan!"
    }
  ]
}
                        

This is NOT the final result from the API. Remember, the API is asynchronous and will not reply with any results to your POST request. This response is intended as a confirmation of your API request and acknowledge receipt of it by our API server.

GET Request

The GET request can be used to access your existing data. It is built to be a search functionality and has different capabilities from the POST request.

$params['publicKey'] = "A30qt7sh1QrOdhvFTHjJoIBCkptwMPm2";
$params['timestamp'] = 1418287283;
$params['signature'] = "77ff2ddad9d9e5eAa6ed07b5ec2e327ac2666fea";

$params['customData'] = "12345";
$params['count'] = 10;
                        

Parameters

customData Locally stored identifier.

count(Optional) Max value is 20. If it is not set, it will default to 10.

Response

Here is an example of the Response that the API will return.

{
  "result": [
    {
      "customData": "12345",
      "lcSrc": "en",
      "lcTgt": "ja",
      "unitCount": 2,
      "matchedRate": 100,
      "text": "Hello world!",
      "translation": "世界、こんにちは！"
    },
    {
      "customData": "12345",
      "lcSrc": "en",
      "lcTgt": "ja",
      "unitCount": 2,
      "matchedRate": 0,
      "text": "Hello Japan!",
      "translation": "こんにちは日本！",
    }
  ]
}
                        

Callbacks

Callbacks are always on a "text" level. They are how the API works with POST requests. The Callback is not a direct reply to your initial POST request. Instead, it is a separate communication to the Callback URL specified in your user account settings under Settings > Integrations > API.

The Callback can contain different information depending on the nature of the initial POST request. For example:

{
  "customData":   "12345",
  "price":        20,
  "currency":     "JPY"
  "unitCount":    2,
  "eta":          30,
}
                        

{
  "customData":   "12345",
  "lcSrc":        "en",
  "lcTgt":        "ja",
  "text":         "Hello world!",
  "unitCount":    2,
  "translation":  "世界、こんにちは！",
  "matchedRate":  100,
}
                        

{
  "customData":   "12345",
  "errors": {
    "code": "crowdTranslationExpired",
    "message": "The request to crowd translation has expired"
  }
}
                        

{
  "customData":   "12345",
  "lcSrc":        "en",
  "lcTgt":        "ja",
  "text":         "Hello world!",
  "unitCount":    2,
  "translation":  "こんにちは世界！",
  "matchedRate":  0,
}
                        

{
  "customData":   "12345",
  "lcSrc":        "en",
  "lcTgt":        "ja",
  "text":         "Hello world!",
  "unitCount":    2,
  "translation":  "世界、こんにちは！",
  "matchedRate":  100,
}
                        

Callback Variables

eta The estimated time it takes to translate the text in minutes. If the estimation fails, the value will be NaN.

matchedRate The percentage of sentences in the text that had matches with translations in your Phrases.

unitCount The number of characters or words in the text.

Language codes