WEB-Transer＠SDK

翻訳サーバーREST API

本ドキュメントは株式会社クロスランゲージの翻訳サーバーSDKの一部です。ユーザーは、SDKライセンスの制限と条件に準じてのみ本ドキュメントを使用することができます。

リクエスト要件

サーバーへの全てのリクエストは以下の規則に準じて有効でなければなりません。

メソッド

GETメソッドに対応する全てのAPIメソッドは、POSTを使ってコールすることもできます。POSTでリクエストする場合、全てのパラメータはそのリクエストの本文内で指定されなければなりません。

データエンコーディング

全てのリクエストURLは、有効なUTF-8エンコーディングを使用しなければなりません。無効なUTF-8を使用するとエラーになります。

全てのパラメータ値は、パーセントエスケープによって適切にＵＲＬエスケープされなければなりません。

バイナリ・データの翻訳は不可となります。0x00から0x1Fまでの全ての文字範囲(TAB (0x09)、LF (0x0A) 、CR (0x0D) を除く)は翻訳前に半角スペース文字 (0x20) に置き換えられます。

URL長

GETメソッドを使ったリクエストURLの最大長は20,000バイトです。POST bodyにはURLエンコードデータ長の制限はありません。

UTF-8とURLエンコード後は日本語一文字が9バイトとなるため、GETリクエストでの日本語最大長は約2000文字に制限されます。このような制限を回避するため全てのリクエストでPOSTメソッドを使用することを推奨します。

ライセンス要件

翻訳サーバーへの全てのコールによって、ライセンスは提供される。このライセンスは様々な方法で適用されます。すべてのメソッドでプレイン・テキストの代わりにハッシュ化されたパスワードが使用されます。

HTTPヘッダー

"Cross-Licence"ヘッダーを使用してＨＴＴＰリクエストでユーザーIDとハッシュ化されたパスワードを提供します。以下、例となります。

GET /clsoap/user HTTP/1.0
Cross-Licence: userid ce7276de4e2f5eb2c864f01a6121553db0923b65

リクエスト・パラメータ

URLパラメータとしてHTTPリクエストでユーザーIDとハッシュ化されたパスワードを提供します。以下、例となります。

GET /clsoap/user?key=userid+ce7276de4e2f5eb2c864f01a6121553db0923b65 HTTP/1.0

HTTP認証

Basic認証もしくはDigest HTTP認証によって、ユーザーIDとハッシュ化されたパスワードを提供します。

【Basic認証】
HTTPとHTTPSリクエストによって、HTTP Basic認証は承認される。
【Digest認証】
HTTP Digest認証は、HTTPリクエストにのみ承認される。HTTPSリクエストによってdigest認証を実施することは不可および不必要となります。

エラー

エラーがサーバー側で発生した場合は、有効なJSONもしくはJSONPレスポンスが可能ならば返されます。このデータは常にHTTPステータス・コードの200として返されます。実際のHTTPステータス・コードはJSONデータのレスポンスより読み取れます。このエラーレスポンスオブジェクトはコールバックされたか否かにかかわらず同じフォーマットです。コールバックされた場合、エラーオブジェクトが最初のパラメータとして渡されます。

エラーフォーマット

{
    "error": {
        "code": CODE,
        "message": "MESSAGE"
    }
}

コード

CODE値はHTTPステータス・コードで通常は以下のうちの一つになります。

400クライアントが無効なリクエストを発行しました。リクエスト内のエラーを修正し、サーバーに再度リクエストを発行してください。
401サーバーに有効なライセンスキーが与えられていません。リクエストをリトライする前に、上記で紹介したメソッドのいずれかで有効なライセンスキーが提供されているか確認してください。
500リクエストを処理中にサーバーで内部エラーが発生しました。再度リクエストを実行しても処理できる可能性は低くなります。
503サーバーが一時的にビジーで、リクエストを処理できませんでした。しばらく待ってから再度リクエストを実行してください。

メッセージ

MESSAGEはプレイン・テキストのエラーメッセージで、エラーについての詳細を提供します。

一般的なエラーメッセージは以下の通りです。以下メッセージリストはエラーの一部となります。

Invalid UTF-8 character in parameter: PARAM, offset: COUNT
不正な、長すぎる、もしくは無効なUTF-8文字が、バイトオフセットCOUNT周辺のリクエスト・パラメータのPARAMで見つかりました。
Missing required parameter: PARAM
PARAMパラメータが必要であるが、提供されていません。
Invalid value for parameter: PARAM
パラメータPARAMに提供された値が有効ではありません。
Internal Server Error
サーバーの内部エラー。
Service Unavailable
サービスがビジーかもしくは翻訳サービスが一時的に使用できません。

ユーザーの詳細

ユーザーAPIで、現ユーザーが利用できるサーバーエンジン、辞書およびその他リソースを処理要求することができます。

URL

/clsoap/user

メソッド

GET, POST

パラメータ

key=LICENCE オプション 当該サービスのユーザーライセンスを提供します。
uilang=LANGUAGE オプション 全ユーザーの表示可能なテキストをリクエストされた言語で返すリクエストです。この言語は、言語コードの1つで、"en" = 英語、"ja" = 日本語となります。指定しない場合は、デフォルトとして日本語が指定されます。

レスポンスフォーマット

レスポンス・オブジェクトは以下のフォーマットになります。

{
    "user": {
        "userid": "hogehoge",
        "username": "ほげほげ",
        "features": "TEXT TMUL UGTS REST",
        "timezone": "Japan"
    },
    "engines": {
        "EJ": {
            "from": "en",
            "to": "ja",
            "reverse": "JE",
            "display": "英語 - 日本語"
        },
        "JE": {
            "from": "ja",
            "to": "en",
            "reverse": "EJ",
            "display": "日本語 - 英語"
        }
    }
}

"ユーザー"オブジェクトは、当該ユーザーに関する全ての情報を含みます。

"エンジン"オブジェクトは、当該ユーザーが利用できるエンジンのリストを含みます。

翻訳

翻訳APIは、テキストおよびHTML翻訳の機能を提供します。

URL

/clsoap/translate

メソッド

GET, POST

パラメータ

key=LICENCE オプション サービスのユーザーライセンスを提供します。HTTPリクエストヘッダもしくはHTTP認証のいずれかを使用してユーザーライセンスが提供される場合、URLを指定する必要はありません。
e=ENGINE 必須 使用する翻訳エンジンを指定します。翻訳エンジンは/clsoap/userへリクエストして返されたユーザー情報のエンジンIDの内、一つでなければなりません。
p=PROFILE オプション 翻訳で使用するエンジンプロパティのプロファイルを指定します。指定しない場合、エンジンプロパティはデフォルトプロファイルを使用します。
t=TEXT 必須 翻訳されたテキストもしくはHTMLを指定します。複数エントリの指定が可能で、それぞれのファイルは別のブロックとして翻訳されます。指定の順番通りに翻訳結果が別々に返されます。
format=TYPE オプション "t"パラメータのデータをフォーマットを指定します。"text"はテキストデータ、"html"はhtmlデータとして使用してください。これらのパラメータが指定されない場合は、テキストデータがデフォルトとして使用されます。
sent=true オプション センテンスセグメント情報が翻訳されたテキストとして返すようリクエストします。
equiv=true オプション equiv情報が翻訳されたテキストとして返すようリクエストします。

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

レスポンス・オブジェクトは以下のフォーマットになります。

{
    "t": [
        {
            "text": "これは、テストです。",
            "sent": [
                ["M","ja",0,15,0,10]
            ],
            "equiv": {
                "org": [
                    [0,0,4],
                    [2,8,1],
                    [3,10,4],
                    [4,5,2],
                    [9,14,1]
                ],
                "txn": [
                    [0,0,2],
                    [1,2,1],
                    [3,4,3],
                    [4,7,1],
                    [6,8,1],
                    [9,9,1]
                ]
            }
        }
    ]
}

当該レスポンスを発生させるリクエストは以下の通りです。

http://SERVER/clsoap/translate?e=EJ&t=This+is+a+test.&sent=true&equiv=true

レスポンス・オブジェクトは、以下のメンバーを含みます。

t結果ブロックの配列となる。リクエストされたそれぞれの"t"パラメータに対して、この配列のエントリが対応しています。最初の"t"パラメータは、t[0]、2番目は、t[1]、等々となります。詳細は以下のt オブジェクトをご参照ください。

t オブジェクト

"t"配列のそれぞれのオブジェクトは、以下のエントリを含みます。

text 翻訳されたテキストもしくはHTMLデータ。
sent テキストのセグメントエントリの配列。詳細は以下の sent配列をご参照ください。
equiv ワードequivエントリの配列。詳細は以下のequivオブジェクトをご参照ください。

sent 配列

"sent"配列は、リクエストがテキスト翻訳およびセンテンス・データが"sent=true"でリクエストされている場合にのみ返されます。センテンス・データはHTML翻訳には対応していません。"sent"配列のそれぞれのオブジェクトは、以下項目を含む固定長配列となります。

[ TEXTTYPE, LANGUAGE, ORGSTART, ORGLEN, TXNSTART, TXNLEN ]

それぞれの子配列の内容は以下の通りです。

TEXTTYPE セグメント型を指定する一文字の文字列。セグメント型はテキストがどのように生成されたかを説明します。例えば、"M"型は、機械翻訳によって生成されたセグメントで、"S"型は、ソース側から単にコピーされた (場合によっては修正された) 空白エントリとなります。この文字はCrossConstants.js ファイルの定数CR_TEXTTYPEの内一つに一致します。
TLANGUAGE 入力する言語コード。ほとんどの場合、翻訳目的の言語と同じになりますが、翻訳エンジンが翻訳結果を生成できない場合、当該項目は翻訳元の言語となります。
TORGSTART オリジナル・テキストにおけるセグメントの最初の開始インデックス。インデックスはUTF-16のコードポイントで表される。
TORGLEN オリジナル・テキストにおけるセグメントの長さ。インデックスはUTF-16コードポイントで表される。
TTXNSTART 翻訳テキストにおけるセグメントの最初の開始インデックス。インデックスはUTF-16コードポイントで表される。
TTXNLEN 翻訳テキストおけるセグメントの長さ。インデックスはUTF-16コードポイントで表される。

上記の例より、セグメント部分は、["M","ja",0,15,0,10]のみとなります。このセグメントは、TEXTTYPE = "M", LANGUAGE = "ja", ORGSTART = 0, ORGLEN = 15, TXNSTART = 0, TXNLEN = 10という値となります。元テキストの "This is a test."は翻訳テキストの"これは、テストです。"に対応します。

equiv オブジェクト

equiv オブジェクトは、リクエストがテキスト翻訳およびequiv データがパラメータ"equiv=true"としてリクエストされた時のみに返されます。equiv データはHTML翻訳では対応していません。equiv オブジェクトは同等情報の関連する配列を含む"org"と"txn"オブジェクトを含みます。"org"配列は、オリジナル・テキストと同等のエントリを含み、"txn"配列は、翻訳テキストの同等エントリを含みます。

"org"および"txn"オブジェクト配列は同一フォーマットのエントリを含みます。これらのオブジェクト配列のそれぞれのフォーマットエントリは、以下の項目を含む固定長配列となります。

[ ID, START, LENGTH ]

各子配列の内容は以下の通りです。

ID 同じIDの"org"と"txn"の配列の項目は、同じ単語もしくはフレーズに関連します。いくつかのIDのいずれの配列にも、0、ひとつもしくは多数のエントリがあるものとして、関係性はN:Mであることにご留意ください。
START テキスト内の単語もしくはフレーズの開始インデックス。インデックスはUTF-16コードポイントで表される。"org"配列のエントリで、当該インデックスはオリジナル・テキストに関連しています。"txn"配列のエントリで、当該インデックスは翻訳テキストに関連しています。
LENGTH テキスト内の単語もしくはフレーズの長さ。長さはUTF-16コードポイントで表される。

上記の例より、ID 3を持つ"org"および"txn"の配列に一つのエントリがあります。"org"エントリは、 [3,10,4]で、ID = 3、START = 10 (オリジナル・テキスト内)、LENGTH = 4となり、これは"test"という単語になります。 "txn"エントリは、 [3,4,3]で、ID=3、START=4（翻訳テキスト内）、LENGTH=3となり、これは"テスト"という単語になります。