Gengo API Overview (v2)

翻訳の流れ

Gengo APIを利用されると、あなたのアプリをGengoのシステムにつないで、通常のご注文フォームを使わずに人力翻訳をご注文いただけます。人力翻訳は瞬時には完成しないため、弊社のAPIは非同期処理となります。これは、 FlickrTwitter のような一部のWeb APIとは異なり、翻訳者が翻訳を完成する時間が必要となることを意味します。

舞台裏で起こっていること

ご注文いただきますと、Gengoの登録翻訳者に新規案件の通知が送られ、翻訳者は先着順で翻訳に取りかかります。翻訳者は、弊社ウェブサイトの翻訳用インターフェース内で作業します。

案件の送信

Gengoにご注文を送信するプロセスはシンプルです。まず、翻訳したいコンテンツを特定して、そのコンテンツを含む案件ペイロードを “body” のパラメータに作成してください。これは、ボリュームの多い1まとまりのテキスト (Eメールやブログ投稿など) でも、比較的ボリュームの少ない数個のコンテンツ関連の文字列でもOKです。あなたのコードで固有に識別されている各コンテンツは、Gengoの翻訳者にとっては個々の “job (案件)” となります。

あなたのシステムでは、これらはおそらくデータベース内の固有のIDに紐付けされているはずです。Gengoが翻訳をお届けしたときに、システムのどこに追加すべきかが一目瞭然になるように、データベースの各行にどのコンテンツが関連付けられているかを把握しておくことは重要です。これは、“custom_data” のパラメータを利用して行っていただけます。

Gengo APIの最も一般的なご利用方法は、弊社がプッシュ通知をお送りする先をご指定いただく方法です。これを行うためには、”callback_url” を公共アクセスができるエンドポイントに設定してください。翻訳者が翻訳を開始したときや翻訳を完成したときなど、案件にアップデートが発生するたびに、Gengoはアップデート内容をご指定のcallback_urlにPOSTいたします。

翻訳するテキストに関する情報を翻訳者が多く利用できるほど、高い翻訳品質が期待できます。案件に関連する全ての背景情報は、案件を送信する際に “comment” のパラメータに加えられます。たとえば、商品説明と共に使用する写真やブログ記事へのリンクがある場合、ぜひ情報として含めてください。また、Gengoにご注文いただく全案件で一貫した語調を維持されたい場合、スタイルガイドを含めることもご検討ください。

ご注文手続が完了すると、折り返しお手元に”order_id”が届きます。

ご注文ステータスの確認

案件がいったんGengoに送付されると、その案件はいくつかの異なるステータスを経る可能性があります。送付された案件はすべて最初に、キューイングシステムで処理されます。これにより弊社では、非常に大規模なペイロードを大勢のユーザーの方から頂いても年中無休24時間体制で対応させていただくことができます。またこうした案件の担当者決定などの処理も開始し、弊社の翻訳者向けに“available”として表示します。

翻訳者が案件に取りかかった時点で、弊社ではその案件を”pending”と見なします。その案件は、翻訳が完成するまでこのステータスとなります。翻訳が完成すると、案件ステータスは‘reviewable’(翻訳内容を確認して、場合によっては変更希望を弊社翻訳者に伝えたいとお考えのとき) または‘approved’となります。

ご注文案件に関するアップデートは、GETリクエストを /translate/order/ エンドポイントに送っていただければ随時ご確認いただけます。

翻訳のお届け

Gengoでは通常、翻訳者から提出されるつど、完成した案件をあなたのシステムにお届けしています。弊社のシステムから直接アップデートを確認したい場合は、 カンマで区切った案件IDのリストをGET /translate/jobs/{id_1,id_2,id_3}/ に送る方法が最も便利です。

同一ご注文内の完成したjob_idのリストを入手されたい場合には、GET /translate/order/ エンドポイントにリクエストを送り、”jobs_approved”の配列内のデータをご確認いただくのが最も便利です。

翻訳対象外のコンテンツ

時には、ご注文になる案件の中に翻訳不要なテキストを含めたいケースがあるかもしれません。翻訳不要なテキストを案件のワード数には含めずに、担当翻訳者にも翻訳する必要がないと示すには、そのテキストを三重角括弧で [[[こんな風に]]] 囲んでください。三重角括弧を使用される場合は、括弧を閉じることを忘れないようにしてください。また、翻訳対象外のテキストを大きな範囲で含めることは、なるべくお避けください - その場合は、案件をいくつかに分割した方が通常は望ましくなります。

APIで対応している品質レベル

現時点では、弊社のAPIは”standard (スタンダード)” と”pro (プロ)”の品質レベルに対応しています。

詳しくは、弊社の 品質ポリシー ページをご覧ください。

レビューの流れ

弊社では、完成した翻訳をご確認いただくための時間を翻訳提出時から120時間設けています。”approved” にステータスを変更してもよい場合、PUT /translate/job/{id}/ エンドポイントにリクエストを送ってください。

もし逐一案件の承認を行いたくない場合やシステムにその機能がない場合、auto_approveパラメータをtrueにしていただくのが最も簡単です。こうしていただくと案件は翻訳者が翻訳を提出すると同時に承認と見なすことになります。ただしこれはすなわち案件の拒否や訂正の依頼をする権利を放棄することになりますのでご注意下さい。

また、システムがコメントに応答できない場合や返事をするご予定がない場合、「弊社システムでは、翻訳者からのコメントに一切応答できません」といったコメントを追加されることをお勧めします。そうすれば、翻訳者はあなたからの返事を待たずに済むからです。

案件の修正

案件に修正が必要な場合は、translate/job/{id} (PUT) コールと”revise”のアクションを利用してご依頼いただけます。修正のご依頼では、コメント部分でなるべく詳しくご説明いただきますようにお願いします。

このワークフローは、何かしらの自動品質チェック機能を対象コンテンツに追加されたい場合に役立ちます。そうした機能が誤って翻訳者を困らせる恐れもあり得るため、弊社では修正のご依頼回数を最大3回までにさせていただいております。

案件の拒否

Gengoを利用された翻訳にご満足いただけない場合、案件を拒否してポイント返却を受けるか、別の翻訳者に再依頼いただくかのどちらかを選んでいただけます。

すべての案件拒否は、弊社スタッフによって確認されます。弊社では一件一件の案件拒否を真摯に受け止めており、通常は、翻訳者に連絡を取った上で、その翻訳の問題点を確認いたします。

案件を拒否するには、/translate/job/{id} (PUT) コールを使い、actionのパラメータを “reject” にしてください。なお弊社では、案件拒否は人間の手で行っていただくようにお願いしております (翻訳を機械に拒否されたくないからです)。そのため、案件拒否を送信される際にはCAPTCHA認証が必要となりますのでご了承ください。詳細は translate/job/{id} (PUT) ページをご覧ください。

重複案件

ご注文された案件が以前承認された案件と全く同じである場合には、翻訳メモリを使用していない限り、「重複」と考慮され100%割り引かれます。同様のご注文内にある2件以上の案件が全く同じである場合には、通常通りに翻訳されます。

レスポンスのフォーマット

APIのレスポンスには全て、キーと値のペアが最低1対 (おそらく2対) 含まれています。2番目のキーの名称は、その呼び出しが成功したかどうかで変わってきます。予定されたペイロードについて、成功した呼び出しの2番目のキー名は “response” (例: {“opstat” : “ok”, “response” : ”...”} ) 、失敗したレスポンスの2番目のキー名は “err” (例: {“opstat” : “error”, “err” : {“code” : ...}}) となります。

エンコーディング

Gengoでは、全てのデータがUTF-8形式になっていることを前提にしており、レスポンスもUTF-8形式のデータでお送りします。トラブルを未然に防ぐために、ご自身のデータがをUTF-8形式でエンコードしてあるかご確認ください。

リクエスト制限

弊社APIの1分あたりのリクエスト数は現在、発信IPアドレス1件につき150件までとなっています。