システム概要

翻訳フロー

Diagram coming soon!

翻訳結果の受け取り

myGengo翻訳システムに送られた案件は、システムの性質上、非同期に処理されます。 これは、翻訳案件を依頼してから完了するまでに多少の時間が必要なことを意味します。 送信した案件の翻訳が完了したかを確認するには二つの方法があります。 一つ目の方法がURLのポーリング、もうひとつがコールバックの指定です。

ポーリング

各案件にはユニークなURLが割り振られ、そのURLにアクセスすることで該当する案件のステータスを確認することができます。 典型的なレスポンスは、案件のステータス("incomplete"(未完了)、"reviewable"(承認待ち)など)と、もし翻訳が完了し承認済みの場合、翻訳された文章を返します。 まだ案件が未完了の場合には、一時的な措置として機械翻訳された文章が返されます。 あまりにも頻繁にポーリングされた場合、アカウントの停止などを受ける可能性がありますので、必要以上のアクセスは避けるようお願いいたします。 ポーリングによりステータスを確認する際は、最短でも30分は間隔をあけてアクセスするようお勧めします。

コールバック

コールバックを設定すると、案件が完了された際に指定されたURLに通知を送信します。 それぞれのapi_key(ユーザーアカウントのセクションから取得することができます)には、案件の翻訳が完了し、依頼者の承認待ちとなった段階で、myGengoが通知を送るためのデフォルトのコールバックURLを指定しておくことができます。 PayPalが提供しているIPNの方法同様、コールバックを指定することで、翻訳が完了した際に即時にそのステータスを反映できるシステムを実現できます。 コールバックの詳しい処理内容については コールバックの手法のセクションをご覧ください。

翻訳結果の承認

案件の翻訳が完了した後、その翻訳内容を依頼者に承認していただく必要があります。 myGengo APIでは、案件が直ちに自動承認されるよう設定していただくこともできますし、翻訳内容を画像ファイル(JPEG)にしたプレビューで毎回確認することも可能です。 翻訳の完了から72時間以内に承認されなかった案件は、自動的に承認済みとなり料金が発生します。

支払い / ポイント数

現行バージョンのmyGengo翻訳APIをご利用いただくには、ユーザーアカウントを登録した上で翻訳に必要となるポイント数を事前にチャージしておいていただく必要があります。 もし案件が送られた際に翻訳処理に必要なポイント残高が確認できなかった場合、レスポンスにてその旨伝えられます。

手法

myGengo翻訳APIはRESTをベースにしたアーキテクチャに準拠しています。 このAPIにおいてはリソース(URL、エントリーポイント)が案件の挙動を左右するので、例えば対象にするリソースへの（HTTPメソッドの)PUTリクエストは案件のステータス変更の要求として解釈されます。 もし特定のHTTPメソッド(特にPUTやDELETEなど)の送信が許可されていない環境の場合、リクエスト情報に"_method"パラメータを設定することでHTTPメソッドを上書きすることができます。

リクエストフォーマット

すべてのAPI呼び出しにはapi_keyパラメータの付与が必須です。 認証付きAPI呼び出しには、さらに有効な署名をapi_sigパラメータとして付与する必要があります。 もしAPI呼び出しがPOST又はPUTメソッドの場合、各リソースごとに必要とされるパラメータは、dataというパラメータで一段階ラップする必要があります。

例えば、PUTメソッドで呼び出されるAPIには下記のようなパラメータが送信されることになるでしょう。

array(
'api_key' => ...,
'_method'  => 'put',
'api_sig' => ...
'data' => ...
)

一方GETメソッドで呼び出されるAPIには下記のようなパラメータを付与することになるでしょう

?api_key=...&api_sig=...&lc_src=..

レスポンスフォーマット

すべてのAPIのレスポンスには少なくとも1組（多くの場合2組以上）のkey-valueペアのデータがセットされます。 1つ目のキーは常に"opstat"という名前ですが、2つ目のキーの名前は処理が成功したか失敗したかにより変動します。 処理が成功した場合"response"という名前のキーが付与され、例えば{"opstat":"ok","response":"..."}といった内容になります。 一方、処理に失敗した場合は"err"という名前のキーになり、{"opstat":"error","err":{"code":...}}といった返信になります。 

現行のmyGengo翻訳APIでは、レスポンスにJSONとXMLの2種類のフォーマットをサポートしています。 それぞれのフォーマットの、処理に成功した場合と失敗した場合のレスポンスメッセージの例は [リクエストとレスポンスの例] のセクションに記載されています。 レスポンスフォーマットはAPIリクエストの際に"Accept: application/json"などのようにHTTPヘッダに記述することにより指定することができます。 もしくは"format"というパラメータを付与することでも指定することができます。 もし同時にこれら両方のやり方で指定されていた場合、"format"パラメータによる指定が優先されます。 デフォルトのレスポンスフォーマットはJSONです。

エンコーディング

myGengoではすべてのデータはUTF-8でエンコードされている前提で処理し、またレスポンスのデータにもUTF-8を使用します。 不具合の発生を避けるため、UTF-8をご利用いただくようよくご注意ください。