はじめの一歩

開始するには、以下のステップに従ってください

ステップ1: Sandboxアカウントを作成して、APIキーを取得します。

あらゆるAPIの呼び出しは、APIキーを用いて承認される必要があります。テスト中は、Sandbox環境をご利用いただき、そこからあなたのキーを生成してください。このチュートリアルでは、Sandboxアカウントの作成方法をご説明して、Gengoの翻訳APIを呼び出すためのAPIキーを生成できるようにします。

まず、 無料のSandboxアカウントを作成 する必要があります。

ログイン後にAccountセクションに行き、右側にあるメニューから "API settings" をクリックしてください。

ここにあなたのAPIキーが保存されます。別のキーを生成するには "Generate Key" をクリックしてください。

各パブリックキーには、対応するプライベートキーとコールバックURLがあります。パブリックキーはあなたを識別するもので、あなたのログイン名と似た働きをします。プライベートキーはいわばあなたのパスワードなので、絶対に秘密にしてください。他人に知られた場合、その人はあなたのアカウントにアクセスできてしまいます。コールバックURLは、案件の進行状況についてステータスアップデートをGengoからあなたのサーバーやアプリケーションに送ってほしい場合に役立ちます。

生成したパブリックキーとプライベートキーをコピーして、ご自分のアプリケーションで利用できるようにしましょう。

#!/usr/bin/python
# -*- coding: utf-8 -*-

PUBLIC_KEY = 'rspZJxEnswelpvS0)tdwM]7uPjkcgR%@k_mN[Z1ac_3a=#EN%r=]cKwxq98-XQdK'
PRIVATE_KEY = 'IlUyZP5TISBSxRzEm0mil$L}-0FxeX(24W1d#TkY{qNkh42Q3B}m2)XJi_nYqrl^'

これだけです! 次のステップでは、APIコールの例をいくつかご紹介します。

ステップ2: あなたのAPIキーを使って、Sandbox環境で遊んでみましょう

ベーシックGETコール

このチュートリアルでは、APIの呼び出しを行う方法を数種類のPHPスクリプトをコマンドラインで使用しながら具体的にご説明しています。これらすべての例では、以下の定数値を仮定しています。

#!/usr/bin/python
# -*- coding: utf-8 -*-

PUBLIC_KEY = 'your public key'
PRIVATE_KEY = 'your private key'
URL = 'http://api.sandbox.gengo.com/v2/'
RESPONSE_TYPE = 'json'
header = {"Accept": "application/{0}".format(RESPONSE_TYPE)}

言語ペアの読み出し

まずは、単純な呼び出しを行い、翻訳対応している言語ペアのリストを検索します。

#!/usr/bin/python
# -*- coding: utf-8 -*-

from hashlib import sha1
import hmac
import json
import requests
import time

if __name__ == '__main__':
    PUBLIC_KEY = 'your public key'
    PRIVATE_KEY = 'your private key'

    URL = "http://api.gengo.com/v2/translate/service/language_pairs"
    header = {"Accept": "application/json"}

    data = {
        "api_key": PUBLIC_KEY,
        "ts": str(int(time.time()))
    }

    # use your private_key to create an hmac
    data["api_sig"] = hmac.new(
        PRIVATE_KEY,
        data["ts"],
        sha1
    ).hexdigest()

    get_language_pair = requests.get(URL, headers=header, params=data)
    res_json = json.loads(get_language_pair.text)

    if res_json["opstat"] != "ok":
        msg = "API error occured.\nerror msg: {0}".format(
            res_json["err"]
        )
        raise AssertionError(msg)
    else:
        print(res_json)

戻り値

{
  "opstat": "ok",
  "response": [
    {
      "tier": "standard",
      "lc_tgt": "en",
      "lc_src": "de",
      "unit_price": 0.05,
      "currency": "USD"
    },
    {
      "tier": "pro",
      "lc_tgt": "en",
      "lc_src": "de",
      "unit_price": 0.10,
      "currency": "USD"
    },
    ...
    ...
    ...,
    {
      "tier": "pro",
      "lc_tgt": "en",
      "lc_src": "pt-br",
      "unit_price": 0.10,
      "currency": "USD"
    }
  ]
}

返ってくる値は、品質レベル (tier) と単価を含む各対応言語ペアに関するデータです。

以上は、Gengoの翻訳APIを通じてデータを検索する方法のごく単純な例です。

ベーシックPOSTコール

今度は、人力翻訳用に案件の注文をいくつか提出してみましょう。Sandbox環境では、ユーザーは仮ポイントを素早く追加して、案件の注文を簡単に提出できるようになっています。まずはログインし、あなたのアカウントに仮ポイントを適宜追加しましょう。

仮ポイントを追加したら、jobs-post.pyのスクリプトの例を開き、フィールドを編集して2件の案件が提出できるようにします。'body_src'フィールドに翻訳用のテキストを適宜追加した後、ソース言語、ターゲット言語、レベルの各パラメータが希望通りであるかを確認しましょう。また、各案件と関連付けるカスタムデータを送信することもできます。これは、あなたに対するサービスに特化したデータで、その他の用途には一切使用されません。カスタムデータは案件がリクエストされるつど、全文そのままがリターンされます。

#!/usr/bin/python
# -*- coding: utf-8 -*-

from hashlib import sha1
import hmac
import json
import requests
import time

if __name__ == '__main__':
    PUBLIC_KEY = 'your public key'
    PRIVATE_KEY = 'your private key'

    URL = "http://api.gengo.com/v2/translate/jobs"
    header = {"Accept": "application/json"}

    data = {
        "api_key": PUBLIC_KEY,
        "ts": str(int(time.time()))
    }

    # use your private_key to create an hmac
    data["api_sig"] = hmac.new(
        PRIVATE_KEY,
        data["ts"],
        sha1
    ).hexdigest()

    job1 = {
        'slug': 'job test 1',
        'body_src': 'one two three four',
        'lc_src': 'en',
        'lc_tgt': 'ja',
        'tier': 'standard',
        'auto_approve': 1,
        'custom_data': 'some custom data untouched by Gengo.',
    }
    job2 = {
        'slug': 'job test 2',
        'body_src': 'five six seven eight',
        'lc_src': 'en',
        'lc_tgt': 'ja',
        'tier': 'standard',
        'comment': 'This one has a comment',
    }

    jobs = {'job_1': job1, 'job_2': job2}
    data["data"] = json.dumps({'jobs': jobs}, separators=(',', ':'))

    post_job = requests.post(URL, data=data, headers=header)
    res_json = json.loads(post_job.text)

    if not res_json["opstat"] != "ok":
        msg = "API error occured.\nerror msg: {0}".format(
            res_json["err"]
        )
        raise AssertionError(msg)
    else:
        print(res_json)

"translate/jobs " エントリーポインのドキュメントをご覧いただき、その他にどんなパラメータが利用できるかを確認されることをお勧めします。ただしこの例では、案件のグループ化をオフにしています (そうすると、各案件を異なる翻訳者が担当できます)。

では、この2件の案件を送信してみましょう:

python jobs-post.py

このレスポンスでは、ご注文に関する各種のデータを教えてくれます:

{
  "opstat": "ok",
  "response": {
    "order_id": 914451,
    "job_count": 2,
    "credits_used": 0.40,
    "currency": "USD"
  }
}

案件の post からのレスポンスに含まれる最も重要な情報の1つは order id です。これは、ご注文に関する情報 (注文された各翻訳の案件IDなど) を取り出すときにも必要になります: