ドキュメント本文へスキップ
API

翻訳をプレビューする

送信時の `translate` が生成するであろう内容を、何も送らず何も保存せずに返します。

POSTapi.openemail.uk/emails/translate

実際の呼び出しを、ご自身のキーで自分のワークスペースに対して実行します。

POST /emails/translate

送信時の translate が生成するであろう内容を、何も送らず何も保存せずに返します。

リクエスト

送信時に解決されるのと同じ 3 つのオプションから封筒を除いたものを、送信パスが呼ぶのと同じ関数に通します。この同一性こそがこのエンドポイントの価値のすべてです。独自コードによるプレビューは守れない約束であり、両者がずれた日には、誰かの画面に映っているものと受信者の受信トレイにあるものが食い違い、それを知らせるものは何もありません。

パラメーター

tostring必須
書き込む言語です。BCP-47 コード（`de`）、英語名（"German"）、またはその言語自身の名称（"Deutsch"）。レスポンスはどのコードに解決されたかを返すので、連絡先ごとに言語を保存するならその形式を保存してください。
htmlstring
HTML 本文、最大 1 メガバイト。html、text、subject のいずれか 1 つは必須です。
textstring
プレーンテキスト部分。`html` とは独立に翻訳され、長さのチェックも別です。
subjectstring
件名の文字列です。送信時の `translate` の下にあるブール値とは異なります。この 2 つは別の問いです。あちらはすでに保持している件名を翻訳するかどうかを指定するもので、こちらは件名そのものを渡すものです。
fromstring
元の言語を、同じ 3 つの形式のいずれかで指定します。指定すると検出の呼び出しを省略できます。
includeOriginalboolean
返される `html` に、翻訳の下へ原文をすでに含めるかどうか。既定は true です。

他と同様、未知のキーは 422 です。html、text、subject のいずれも含まないリクエストは html に対する 422 で、「One of html, text or subject is required」と返ります。

プレビューする

これから送る内容を人に見せる前に、コンポーザーが行う往復です。

curl
curl -X POST "$OE/emails/translate" -H "$AUTH" -H "Content-Type: application/json" \  -d '{    "subject": "Your September invoice",    "html": "<p>Invoice attached. Payment is due on the 14th.</p>",    "to": "de"  }'
レスポンス
{  "object": "translation",  "language": { "code": "de", "label": "German", "native": "Deutsch", "flag": "🇩🇪", "rtl": false },  "detectedSourceLanguage": {    "code": "en", "label": "English", "native": "English", "flag": "🇬🇧", "rtl": false  },  "subject": "Ihre Rechnung für September",  "html": "<p>Rechnung im Anhang. Zahlbar bis zum 14.</p>\n<div style=\"margin:28px 0 0;padding:14px 0 0;border-top:1px solid #d6dae0\">\n<div style=\"margin:0 0 10px;font-size:12px;line-height:1.5;color:#6b7280\">Ursprüngliche Nachricht (English)</div>\n<div><p>Invoice attached. Payment is due on the 14th.</p></div>\n</div>",  "text": null,  "includeOriginal": true}

送らなかったフィールドについて、html、text、subject は欠落ではなく null として返ります。そのためクライアントは、何を要求したかを覚えていなくても回答を描画できます。

detectedSourceLanguage は、検出が判断を保留したときに null になります。これは失敗ではなく、実際の回答です。名前・数字・リンクばかりの本文には読み取るものがなく、その結果として生じるのは、原文のキャプションに言語名が入らないことだけです。

includeOriginal が返されるのは、それが html の内容を変えるからです。オンのとき本文にはすでに翻訳の下に原文が入っているので、自分でもう 1 部追加すると 2 回送ることになります。

プレビュー、編集、送信

これが想定している流れは、プレビュー → 編集 → 送信です。人に翻訳を見せ、手を入れてもらい、承認された内容を、リクエストに translate をまったく付けない通常の html と subject として送信します。こうすれば、承認された内容が一字一句そのまま送出されます。

curl
curl -X POST "$OE/emails" -H "$AUTH" -H "Content-Type: application/json" \  -d '{    "from": "[email protected]",    "to": ["[email protected]"],    "subject": "Ihre Rechnung für September",    "html": "<p>Rechnung im Anhang. Zahlbar bis zum 14.</p>"  }'

プレビューの後に translate を付けて送信すると、2 度目の翻訳が行われ、編集内容は捨てられます。誰も読んでいない文言で送信されることになり、それこそがプレビューが防ごうとしている唯一の失敗です。

コストと、行わないこと

  • モデル呼び出しは 3 回（本文、件名、そして元の言語の判定）で、同時に発行されるため、待ち時間は合計ではなく 3 つのうち最長のものになります。from を指定すれば 3 つ目は省かれます。コストは translate 付きで送信する場合と同じなので、修正のたびではなく 1 度だけプレビューしてください。
  • 何も送信されず、行も書き込まれず、id も返りません。後からキャンセルしたり取得したりするものは何もありません。
  • 翻訳するだけで、それ以外は何もしません。校正もせず、文章を改善もせず、メッセージに返信することも決してありません。
  • 名前、会社名、リンク、注文番号、価格、日付は入力したままの形で返るため、翻訳を原文と 1 行ずつ突き合わせて確認できます。
  • 読み取り側とは違い、引用履歴は取り除かれません。渡したものがそのまま翻訳されます。これは本文が今書かれた内容だけであるコンポーザーにとっては正しい挙動で、返信の連鎖全体を投げる場合には知っておく価値があります。
  • emails:send のスコープで動作し、専用のスコープはありません。送信者がすでにできること以上の権限を与えないうえ、同意画面で emails:send と区別のつかないスコープがあると、そのリストに並ぶ他のすべてのスコープの意味がわずかに薄れてしまうからです。

本文は送信時と同じ 1 メガバイトが上限ですが、翻訳そのものは 30,000 文字を超えるものを translation_too_long で拒否します。失敗コードは翻訳付き送信が返すものと同じで、「メールを送信する」に一覧があります。