Autolingual Translation API仕様

#概要

Autolingual Translation APIは、お客様のサーバーなどから任意のテキストを送信し、Autolingualによる翻訳結果を受け取れるAPIです。

通常のAutolingualによるサイト翻訳では、Webサイトに埋め込んだSDKが収集したWebサイト上のテキストを翻訳します。 Autolingual Translation APIをご利用いただくと、サイト上に表示されていないテキストも、サイト翻訳と同じ翻訳エンジン・辞書で翻訳できます。

Autolingual Translation APIはBusinessプラン以上でご利用いただけます。

#こんな場合におすすめ

メールの文章や帳票内のテキストなど、Webサイト以外で利用するテキストを翻訳したい
自社システムやCMSの管理画面から、Autolingualの翻訳を呼び出したい
サイト翻訳で登録した辞書や翻訳編集の内容を、サイト外のテキストにも反映させたい

#できること

プロジェクトの元言語のテキストを、プロジェクトに設定済みの翻訳先言語に翻訳します。
1回のリクエストで複数のテキスト（最大100件）をまとめて翻訳できます。
翻訳結果には、以下のAutolingual側の設定が反映されます。
- 辞書登録：辞書に登録された用語は、辞書の内容にしたがって翻訳されます。
- 翻訳編集（全ページに適用）：翻訳テキスト管理画面やライブ編集などで、全ページに適用する形で修正した訳文がある場合、その訳文が返ります。
Autolingual Translation APIで翻訳したテキストは、翻訳テキスト管理画面にも表示されます。訳文を修正したい場合は、翻訳テキスト管理画面から編集していただくと、次回以降のリクエストから修正後の訳文が返るようになります。
- 翻訳テキスト管理画面の絞り込みの「適用範囲」で「Autolingual Translation API」にチェックを入れると、Autolingual Translation APIで利用されたテキストのみを表示できます。

#ご利用の流れ

プロジェクト画面の「設定」＞「APIキー管理」からAPIキーを発行します。
- 詳細は下記ドキュメントをご参照ください。【プロジェクト設定画面】3-7.APIキー管理
お客様のシステムから、APIキーを付けてAutolingual Translation APIを呼び出します。

#使い方

#エンドポイント

POST <https://api.autolingual.io/v1/translations>

#リクエストヘッダー

ヘッダー	内容
Authorization	`Bearer {APIキー}` の形式で、発行したAPIキーを指定します。
Content-Type	`application/json` を指定します。

#リクエストボディ

項目	型	必須	内容
targetLanguageCode	文字列	必須	翻訳先の言語コード（例：`en`）。プロジェクトに設定済みの翻訳先言語のみ指定できます。
texts	文字列の配列	必須	翻訳したいテキスト。1回のリクエストで最大100件、合計10,000文字まで指定できます。

※翻訳元の言語は、プロジェクトに設定されている元言語が使用されます。リクエストで指定することはできません。

※言語コードについては、下記ドキュメントをご参照ください。

‣ 言語コード一覧

#リクエストの例

curl -X POST "<https://api.autolingual.io/v1/translations>" \\
  -H "Authorization: Bearer al_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \\
  -H "Content-Type: application/json" \\
  -d '{
    "targetLanguageCode": "en",
    "texts": ["限定商品", "本日のおすすめ"]
  }'

#レスポンスの例

{
  "data": {
    "sourceLanguageCode": "ja",
    "targetLanguageCode": "en",
    "results": [
      { "text": "限定商品", "translatedText": "Limited Edition" },
      { "text": "本日のおすすめ", "translatedText": "Today's Recommendations" }
    ]
  }
}

各項目の説明：

sourceLanguageCode：翻訳元の言語コード（プロジェクトの元言語）
targetLanguageCode：翻訳先の言語コード
results：翻訳結果の配列。text が送信したテキスト、translatedText が翻訳結果です。
- results は、リクエストの texts と同じ順序・同じ件数で返ります。
- 同じテキストが複数含まれている場合も、それぞれに対して翻訳結果が返ります。
- 空文字や空白のみのテキストは翻訳対象にならず、送信したテキストがそのまま返ります。

#上限

項目	上限
1リクエストあたりのテキスト件数	100件
1リクエストあたりの合計文字数	10,000文字
リクエスト数	1プロジェクトあたり60リクエスト／分

大量のテキストを翻訳される場合は、上記の範囲に収まるように分割してリクエストしてください。

#エラー

エラー時は、以下の形式でレスポンスが返ります。

{
  "error": {
    "code": "usageLimitReached",
    "message": "Monthly auto-translated characters limit reached."
  }
}

error.code には、エラー内容ごとに決められた文字列が入ります。お客様のシステムで処理を分岐させる場合は、error.code をご利用ください（message は変更される場合があります）。

HTTPステータス	code	内容
400	`invalidRequest`	リクエストの形式が不正です（JSONとして解釈できない、必須項目がない、型が正しくない、`texts` が空など）。
400	`unsupportedTargetLanguage`	`targetLanguageCode` が、プロジェクトの翻訳先言語に設定されていません。
400	`tooManyTexts`	`texts` の件数が100件を超えています。
400	`totalCharactersLimitExceeded`	`texts` の合計文字数が10,000文字を超えています。
401	`invalidApiKey`	APIキーが指定されていない、形式が不正、または無効（削除済み）です。
402	`usageLimitReached`	月間の自動翻訳文字数が上限に達しています。
403	`featureNotEnabled`	対象プロジェクトでAutolingual Translation APIが有効になっていません。
429	`rateLimitExceeded`	リクエスト数の上限（60リクエスト／分）を超えています。時間をおいて再度リクエストしてください。
500	`internalError`	サーバー側で予期せぬエラーが発生しました。時間をおいて再度リクエストしてください。繰り返し発生する場合はサポートまでお問い合わせください。

#翻訳文字数の消費について

Autolingual Translation APIで新たにAI翻訳を行った文字数は、サイト翻訳と同じ「自動翻訳文字数」として計上され、ご契約プランの上限に含まれます。
すでに翻訳済みのテキスト（過去にAutolingual Translation APIまたはサイト翻訳で翻訳されたテキスト）は、保存済みの訳文が返るため、文字数は消費されません。
自動翻訳文字数が上限に達している場合、Autolingual Translation APIはリクエスト全体をエラー（402 usageLimitReached）で返します。原文のままの結果が返ることはありません。
ページ数・PV数の上限は、Autolingual Translation APIの利用には影響しません。

#注意事項

Autolingual Translation APIが扱えるのはプレーンテキストのみです。HTMLタグを含むテキストを送信した場合、タグは翻訳対象の文字列としてそのまま扱われるため、意図した翻訳結果にならない場合がございます。
翻訳元の言語はプロジェクトの元言語として扱われます。元言語以外のテキストを送信した場合、正しい翻訳結果にならないことがあります。
Autolingual Translation APIには「どのページのどの箇所か」という情報がないため、特定ページにのみ適用した翻訳編集は反映されません。 Autolingual Translation APIの結果に反映されるのは、辞書登録と、全ページに適用した翻訳編集です。
Autolingual Translation APIで翻訳したテキストは、ページ内の前後の文脈が存在しないため、文脈を考慮したAI翻訳の対象外となります。