gengoとは人力翻訳サービスですが、APIも提供されているということで試してみました。
Sandboxというテスト環境が提供されているのでそれを使っていきます。
https://gengo.com/ja/developers/
ログイン後に右上のAccountボタンからAccountページへ移動後に「Generate Key」ボタンを押すことで、API認証用のキーを取得することができます。
生成されたPublic KeyとPrivate Keyをコードに埋め込むことで認証を行えます。
また、右側の「Add credits」ボタンを押してテスト用の疑似料金を課金しておきましょう。 creditsが足りない場合、翻訳依頼時にエラーとなってしまいます。
https://developers.gengo.com/client_libraries/
今回はphpで行うのでphpライブラリをインストールします。
ライブラリ内のexamplesフォルダに各種サンプルコードが含まれているのでキー部分を入力して、動作確認してみるといいと思います。
postTranslateJobs.phpを実行して翻訳依頼をしてみて、戻り値のjobIdを getTranslateJobs.phpに指定してあげると何となく動作しているなというのが感じられるのではないでしょうか。
init.phpを読み込んだ後に、 Gengo_Api::factoryで jobsを扱うオブジェクトを取得し、postJobsを実行を実行するだけで翻訳依頼ができるようですね。
init.phpでちょっと癖のある処理がかかれていて、set_include_pathでライブラリのlibsディレクトリをインクルードパスに追加したあとに、 spl_autoload_registerでInitのautoloadメソッドをautoloadに登録しています。
Initのautoloadメソッド
クラス名がGengo,Zend_から始まるクラスの場合、クラス名のファイルを読み込む処理をしています。 何かgengoに関するクラスを作成して、Gengoから始まるクラス名にした場合、ここの処理に引っかかってしまうので注意しましょう。
ちょっと脱線してしまいましたが、翻訳依頼を出すことにおいて大事なのはパラメーターを理解することだと思います。
下記URLの「Job Payload - for submissions」に一覧が載っています。
https://developers.gengo.com/v2/api_methods/payloads/
必須項目としては当然、文章（body_src）、文章言語（lc_src）、翻訳言語（lc_tgt）というものがありますが、任意のパラメーターが結構たくさんあります。
便利そうだと思ったパラメーターをピックアップしてみました。
auto_approve 1 (true) / 0 (false) :
自動的に承認状態にするためのパラメーターです。 翻訳内容の編集フローが必要ないプログラムではこの値を1にするといいでしょう。
tone :
翻訳内容のトーンを指定できます。 "Informal/Friendly/Business/Formal/Other..."
comment :
翻訳作業に対してコメントを投げることができます。 「It is strongly encouraged to provide a detailed comment for the translator」とあるように、gengo側としても翻訳者にコメントを出すことを勧めているようです。
custom_data :
カスタムデータです。 依頼時に指定したものが翻訳ジョブに紐づけられて、そのままの形で取得できます。
例えば複数アカウントをもったプログラムで、それぞれが翻訳依頼を出せるようなシステムの場合、アカウントのID指定してあげれば、アカウントごとの利用従量などが判別できるのではないでしょうか。
翻訳依頼時のレスポンスですが、基本的には下記のようなシンプルなものです。
ただし、翻訳依頼が同じ内容だった場合下記のような、以前翻訳した内容を返します。
システム実装するうえで、この戻り値の差異をハンドリングする必要がありますね。
ただし、パラメーターのforceを1に設定すれば、同じ翻訳依頼が既にあった場合も通常の翻訳依頼として処理することができるようです。（前者の戻り値）
下記URLからSandbox管理画面にログインします。
翻訳依頼がされたものが pendingに、翻訳完了したものがapprovedに表示されています。
翻訳処理を行う場合は、detail で詳細画面に移行後に、set for preview を押すことで、自動的に翻訳されます。 auto_approvedが1の場合はapprovedになり、0の場合はreviewableとなります。
各種ジョブのステータスは下記のURLに詳細が記載されています。
https://developers.gengo.com/v2/job_statuses/
稀に翻訳依頼を投げてもなかなか管理画面上に表示されない場合がありました。 APIを通してジョブ情報を取得すると、queued （システム処理中）となっていて、一晩寝かせたらavailable （翻訳可能）となっていて正常に表示されていました。
一晩寝かせてもダメな場合はサポートに問い合わせしてはどうでしょうか。 開発者サポート
別の箇所でバグを踏んでしまい問い合わせしてみましたが、かなり早くレスポンスを頂けました。
ジョブIDが解っている場合は上記のように取得でき、翻訳が完了している場合はレスポンスの body_tgt に翻訳された文章が入っています。 レスポンスの詳細は下記のURLの「Job Payload - for responses」にあります。 https://developers.gengo.com/v2/api_methods/payloads/
また、getJobsメソッドの第三引数に取得用のパラメーターとして、status, timestamp_after（指定したタイムスタンプ以後に依頼されたもの）, count（取得数： 初期値10, 最大200）が指定できます。
情報の取得方法としてコールバックURLが指定でき、各種作業後にデータを取得できるようです。 https://developers.gengo.com/v2/callback_urls/
ただ今回のテスト環境でコールバックでのデータの取得はうまくいきませんでした。
原因はよく解りませんでしたが、上記のページに「 If the end point is not reachable, we suggest using the GET /translate/order/{id}/ endpoint to receive the translation.」とあり、 上手くいかない場合はクライアントサイドからID指定して情報取得しにきてくださいとのことなので、それに従ってコールバックでの取得を諦めました。
そのほかにも、翻訳内容の修正依頼やキャンセル等できるようですので、もっと詳しく知りたい方は公式ドキュメントを見てみるといいと思います。
何か間違った記載等ありましたらご指摘頂けると助かりますので、宜しくお願いします。
Sandboxというテスト環境が提供されているのでそれを使っていきます。
１．Sandboxアカウント作成
下記のページからSandboxアカウントが作成できます。https://gengo.com/ja/developers/
ログイン後に右上のAccountボタンからAccountページへ移動後に「Generate Key」ボタンを押すことで、API認証用のキーを取得することができます。
生成されたPublic KeyとPrivate Keyをコードに埋め込むことで認証を行えます。
また、右側の「Add credits」ボタンを押してテスト用の疑似料金を課金しておきましょう。 creditsが足りない場合、翻訳依頼時にエラーとなってしまいます。
２．phpライブラリのインストール
クライアントプログラム用のライブラリが提供されているのでそれをインストールします。https://developers.gengo.com/client_libraries/
今回はphpで行うのでphpライブラリをインストールします。
ライブラリ内のexamplesフォルダに各種サンプルコードが含まれているのでキー部分を入力して、動作確認してみるといいと思います。
postTranslateJobs.phpを実行して翻訳依頼をしてみて、戻り値のjobIdを getTranslateJobs.phpに指定してあげると何となく動作しているなというのが感じられるのではないでしょうか。
３．翻訳依頼を出してみる
まずは examplesのpostTranslateJobs.phpのコードを見てみましょう。
/**
* Submits one or several jobs to translate.
*/
require_once '../init.php';
// TODO: this example assumes you replaced the 2 values below.
$api_key = '';
$private_key = '';
$job1 = array(
'type' => 'text',
'slug' => 'API Job test',
'body_src' => 'First test.',
'lc_src' => 'en',
'lc_tgt' => 'ja',
'tier' => 'standard',
// 'force' => 1, // optional. Default to 0.
// 'auto_approve' => 1, // optional. Default to 0.
'custom_data' => '1234567日本語',
'callback_url' => ''
);
$job2 = array(
'type' => 'text',
'slug' => 'API Job test',
'body_src' => 'second test.',
'lc_src' => 'en',
'lc_tgt' => 'ja',
'tier' => 'standard',
// 'force' => 1, // optional. Default to 0.
// 'auto_approve' => 1, // optional. Default to 0.
'custom_data' => '1234567日本語',
'callback_url' => ''
);
$jobs = array($job1, $job2);
// Get an instance of Jobs Client
$job_client = Gengo_Api::factory('jobs', $api_key, $private_key);
// Post the jobs. The second parameter is optional and determinates whether or
// not the jobs are submitted as a group (default: false).
$job_client->postJobs($jobs, true);
// Display the server response.
echo $job_client->getResponseBody();
init.phpを読み込んだ後に、 Gengo_Api::factoryで jobsを扱うオブジェクトを取得し、postJobsを実行を実行するだけで翻訳依頼ができるようですね。
init.phpでちょっと癖のある処理がかかれていて、set_include_pathでライブラリのlibsディレクトリをインクルードパスに追加したあとに、 spl_autoload_registerでInitのautoloadメソッドをautoloadに登録しています。
Initのautoloadメソッド
/**
* We use our own autoloader, but restricted to Gengo classes
**/
public static function autoload($classname)
{
if (false !== strpos($classname, 'Gengo') ||
false !== strpos($classname, 'Zend_') )
{
$classpath = str_replace('_', '/', $classname) . '.php';
require_once $classpath;
}
}
クラス名がGengo,Zend_から始まるクラスの場合、クラス名のファイルを読み込む処理をしています。 何かgengoに関するクラスを作成して、Gengoから始まるクラス名にした場合、ここの処理に引っかかってしまうので注意しましょう。
ちょっと脱線してしまいましたが、翻訳依頼を出すことにおいて大事なのはパラメーターを理解することだと思います。
下記URLの「Job Payload - for submissions」に一覧が載っています。
https://developers.gengo.com/v2/api_methods/payloads/
必須項目としては当然、文章（body_src）、文章言語（lc_src）、翻訳言語（lc_tgt）というものがありますが、任意のパラメーターが結構たくさんあります。
便利そうだと思ったパラメーターをピックアップしてみました。
auto_approve 1 (true) / 0 (false) :
自動的に承認状態にするためのパラメーターです。 翻訳内容の編集フローが必要ないプログラムではこの値を1にするといいでしょう。
tone :
翻訳内容のトーンを指定できます。 "Informal/Friendly/Business/Formal/Other..."
comment :
翻訳作業に対してコメントを投げることができます。 「It is strongly encouraged to provide a detailed comment for the translator」とあるように、gengo側としても翻訳者にコメントを出すことを勧めているようです。
custom_data :
カスタムデータです。 依頼時に指定したものが翻訳ジョブに紐づけられて、そのままの形で取得できます。
例えば複数アカウントをもったプログラムで、それぞれが翻訳依頼を出せるようなシステムの場合、アカウントのID指定してあげれば、アカウントごとの利用従量などが判別できるのではないでしょうか。
翻訳依頼時のレスポンスですが、基本的には下記のようなシンプルなものです。
{
"opstat": "ok",
"response": {
"group_id": 16822,
"order_id": "102285",
"job_count": 2,
"credits_used": "0.20",
"currency": "USD"
}
}
ただし、翻訳依頼が同じ内容だった場合下記のような、以前翻訳した内容を返します。
{
"opstat": "ok",
"response": {
"jobs": [
[
{
"job_id": "218344",
"slug": "API Job test",
"body_src": "First test.",
"lc_src": "en",
"lc_tgt": "ja",
"unit_count": "2",
"tier": "standard",
"credits": "0.10",
"currency": "USD",
"status": "available",
"eta": 25308,
"ctime": 1343120409,
"auto_approve": "0",
"custom_data": "1234567日本語",
"body_tgt": "最初のテスト。",
"mt": 1
}
]
]
}
}
システム実装するうえで、この戻り値の差異をハンドリングする必要がありますね。
ただし、パラメーターのforceを1に設定すれば、同じ翻訳依頼が既にあった場合も通常の翻訳依頼として処理することができるようです。（前者の戻り値）
Sandbox上での翻訳処理
実際の運用用のgengoアカウントを使う際は、翻訳依頼を投げたら翻訳されるのを待っているだけでいいのですが、テスト環境ですので、自分で翻訳処理をする必要があります。下記URLからSandbox管理画面にログインします。
翻訳依頼がされたものが pendingに、翻訳完了したものがapprovedに表示されています。
翻訳処理を行う場合は、detail で詳細画面に移行後に、set for preview を押すことで、自動的に翻訳されます。 auto_approvedが1の場合はapprovedになり、0の場合はreviewableとなります。
各種ジョブのステータスは下記のURLに詳細が記載されています。
https://developers.gengo.com/v2/job_statuses/
稀に翻訳依頼を投げてもなかなか管理画面上に表示されない場合がありました。 APIを通してジョブ情報を取得すると、queued （システム処理中）となっていて、一晩寝かせたらavailable （翻訳可能）となっていて正常に表示されていました。
一晩寝かせてもダメな場合はサポートに問い合わせしてはどうでしょうか。 開発者サポート
別の箇所でバグを踏んでしまい問い合わせしてみましたが、かなり早くレスポンスを頂けました。
翻訳情報の取得
まずはgetTranslateJobsのコードを見てみましょう。
/**
* Retrieves a list of jobs by their ids.
*/
require_once '../init.php';
// TODO: this example assumes you replaced the 3 values below.
$api_key = '';
$private_key = '';
$jobs = array( 700605, 700606 ); // an array of job ids.
// Get an instance of Job Client
$job_client = Gengo_Api::factory('jobs', $api_key, $private_key);
// Get the jobs.
$job_client->getJobs($jobs);
// Show the server response in depth if you need it.
echo $job_client->getResponseBody();
$job = json_decode( $job_client->getResponseBody() );
print_r( $job );
/**
* Typical answer: the list of jobs corresponding to the ids.
{"opstat":"ok","response":{"jobs":[
{"job_id":"384994","body_src":"plop plop!","lc_src":"en","lc_tgt":"ja","unit_count":"2","tier":"standard","credits":"0.10","status":"available","eta":"","ctime":1313504670,"auto_approve":"0","custom_data":"1234567\u65e5\u672c\u8a9e"},
{"job_id":"384995","body_src":"hello!","lc_src":"en","lc_tgt":"ja","unit_count":"1","tier":"standard","credits":"0.05","status":"available","eta":"","ctime":1313504671,"auto_approve":"0","custom_data":"custom data 3"}
]}}
*/
ジョブIDが解っている場合は上記のように取得でき、翻訳が完了している場合はレスポンスの body_tgt に翻訳された文章が入っています。 レスポンスの詳細は下記のURLの「Job Payload - for responses」にあります。 https://developers.gengo.com/v2/api_methods/payloads/
また、getJobsメソッドの第三引数に取得用のパラメーターとして、status, timestamp_after（指定したタイムスタンプ以後に依頼されたもの）, count（取得数： 初期値10, 最大200）が指定できます。
情報の取得方法としてコールバックURLが指定でき、各種作業後にデータを取得できるようです。 https://developers.gengo.com/v2/callback_urls/
ただ今回のテスト環境でコールバックでのデータの取得はうまくいきませんでした。
原因はよく解りませんでしたが、上記のページに「 If the end point is not reachable, we suggest using the GET /translate/order/{id}/ endpoint to receive the translation.」とあり、 上手くいかない場合はクライアントサイドからID指定して情報取得しにきてくださいとのことなので、それに従ってコールバックでの取得を諦めました。
まとめ
gengoAPIのテスト環境で翻訳依頼から翻訳された情報の取得までを行ってみました。そのほかにも、翻訳内容の修正依頼やキャンセル等できるようですので、もっと詳しく知りたい方は公式ドキュメントを見てみるといいと思います。
何か間違った記載等ありましたらご指摘頂けると助かりますので、宜しくお願いします。