API経由のローカライズ：文字列、メール、ドキュメントをエンドツーエンドで処理

エディターでできることは、すべてスクリプトでもできます。インポート、用語集と翻訳メモリを使った多言語への翻訳、レビュー、エクスポートです。本ガイドでは、APIキーから訳文の取得までを案内したあと、一連の流れの各部分を順に説明します。 網羅的な仕様はインタラクティブなAPIリファレンスとOpenAPI JSONにあります。transept.ai/developersは、本ガイドを1ページにまとめたものです。 料金はクレジットで計算します（FastモードまたはStandardモードでは原文1語につき1クレジット、Proモードでは3クレジット）。APIレスポンスのフィールドにも同じ名前を使っています（estimatedCredits、spendable）。

APIキーの取得

アプリの［設定］→［開発者］で発行します（APIキーはStarterプランとProプランで使えます）。シークレットは一度しか表示されないため、その場でコピーしてください。リクエストではAuthorization: Bearer tsk_live_…としてヘッダーでのみ送り、URLには含めないでください。

キーにはスコープが設定されています。フルアクセス、または領域（ドキュメント、実行、用語集、スタイルガイド、翻訳メモリ、Webhook、プロジェクト）ごとの読み取り／書き込み権限を指定できます。キーのスコープ外のリクエストには、不足している権限を示す403が返されます。キーから別のキーを発行することはできません。キーの管理はアプリ内でのみ行えます。

5回のリクエストで完結する基本フロー

キーの動作確認、ドキュメントの作成、費用の見積もり、実行の開始、そして訳文の取得までを順に行います。

export KEY="tsk_live_…"
BASE="https://app.transept.ai/api/public/v1"

# 1: who am I, what can this key do, what's the balance?
curl -s $BASE/me -H "Authorization: Bearer $KEY"

# 2: a document plus its target-language fan-out, in one call
curl -s -X POST $BASE/documents \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"title": "Welcome email", "content": "# Welcome\n\nStart your free trial.",
       "content_type": "markdown", "source_language": "en",
       "target_language": "de", "target_languages": ["fr", "uk"]}'
# → { document_id, language_group: [ {id, target_language}, … ] }

# 3: price it (free, no side effects), then run it across every language
curl -s $BASE/workflow-templates -H "Authorization: Bearer $KEY"   # discover ids

curl -s -X POST $BASE/group-runs/estimate \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"document_id": "<master>", "template_id": "end_to_end", "target_languages": "all"}'
# → { lanes: [ {language, estimatedCredits, minCredits} ], totals: {sufficient} }

curl -s -X POST $BASE/group-runs \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-2026-08-05" \
  -d '{"document_id": "<master>", "template_id": "end_to_end", "target_languages": "all"}'
# → { id: <group_run_id>, runs: [ {job_id, language, block_count} ] }

# 4: wait by polling, or get pushed a signed event instead
curl -s $BASE/group-runs/<group_run_id> -H "Authorization: Bearer $KEY"
# → { status, runs: [ {language, status, progress, gate} ] }

# 5: read the results in the format your pipeline wants
curl -s "$BASE/documents/<version-id>/content?format=markdown" \
  -H "Authorization: Bearer $KEY"

最初から身につけておきたい習慣が3つあります。まず見積もりを取ること（無料です。見積もりは下限から上限までの範囲で示され、上限で確保した分は実際の消費額で精算されます）、ジョブを作成するPOSTではIdempotency-Keyを送ること（再試行しても二重に課金されず、最初の結果がそのまま返されます）、そしてポーリングの代わりにWebhookを登録すること（POST /webhooks {url, events: ["group_run.completed"]}）です。Webhookの配信にはHMAC署名が付き、再試行と配信ログにも対応しています。

3種類の入力形式

文章とメール

content_type: "html"を指定してPOST /documentsを実行すると、書式設定、リンク、テンプレートのプレースホルダーを維持したまま翻訳できます。format=htmlを指定すれば、同じ構造の翻訳済みメールが返されます。リクエストを自分で送らない方法もあります。ワークフローのトリガーを「リクエストボディ」に設定し、ESP、Zapier／n8n、CIの送信先をトリガーURLにします：

# the trigger URL (with its secret) comes from the workflow's trigger card;
# the secret IS the auth, so no Authorization header
curl -s -X POST $BASE/hooks/<trigger-secret> \
  -H "Content-Type: application/json" \
  -d '{"content": "<h1>Welcome!</h1><p>Your trial starts today.</p>",
       "content_type": "html",
       "title": "Trial welcome",
       "external_id": "welcome-v4"}'
# → 202 { run id, document_id, created }

# raw bodies work too: POST the markdown/HTML itself with its Content-Type
curl -s -X POST $BASE/hooks/<trigger-secret> \
  -H "Content-Type: text/markdown" \
  --data-binary $'# Welcome\n\nStart your free trial.'

トリガーの設定により、リクエストごとに新規ドキュメントを作成するか、指定した1つのドキュメントを更新するかを選択できます（更新時はコンテンツの位置合わせが行われ、変更されたブロックのみが再翻訳されます）。24時間以内の重複リクエストは、external_idまたはコンテンツのハッシュ値に基づいて重複排除されます。 詳細については、Webhookトリガーをご覧ください。

ファイル

ファイル本体に加え、source_language、target_language、および任意のtarget_languages[]とproject_idを指定して、POST /documents/upload（マルチパート）を実行します。DOCXはラウンドトリップに対応しており、エクスポート時に元のファイルへ訳文が再挿入されるため、スタイルやレイアウトはそのまま残ります。CSV、PO、XLIFFはキー付きユニットとして取り込まれ、元の形式のままエクスポートされます。 形式の詳細や列のマッピングについては、文字列ファイルをご覧ください。

文字列カタログ

各文字列は、固定のid、source、および任意のcontext、max_length、placeholdersを持つユニットです：

curl -s -X POST $BASE/documents/import-strings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"document": {
        "format": "transept-strings", "version": 1, "source_locale": "en",
        "target_locales": ["de", "fr", "uk"],
        "metadata": {"name": "App UI"},
        "units": [
          {"id": "app.save", "source": "Save", "context": "Toolbar button"},
          {"id": "app.greeting", "source": "Welcome, {name}", "context": "Dashboard header"}
        ]}}'
# → { processing_job_id }; poll GET /document-jobs/{id}

コンテキストは翻訳者向けの指示としてモデルに渡されます。max_lengthは、超えた場合に短くして再試行することで守られます。プレースホルダーは保護され、複数形は言語ごとに展開されます。ファイル内にすでにある訳文は、無料で現在の訳文として登録され、翻訳メモリにも追加されます。翻訳先の言語が指定されていない場合は、翻訳先のないドキュメントをインポートするのではなく、呼び出し自体がno_target_languagesで失敗します。 一連の手順はAPI経由で文字列カタログをローカライズするで説明しています。

1つのメールテンプレートを3言語に翻訳

メールテンプレートの具体的な活用例です。Liquidタグは翻訳中もそのまま維持されます。

# the template body goes in as HTML; three target languages fan out
curl -s -X POST $BASE/documents \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"title": "Trial welcome", "content_type": "html", "source_language": "en",
       "target_languages": ["de", "fr", "uk"],
       "content": "<h1>Welcome, {{ first_name | default:\"friend\" }}!</h1><p>Your trial starts today.</p>"}'

{{ first_name | … }}はモデルに渡る前にマスクされ、そのままの形で復元されます。例外は1つだけです。フォールバックのfriendは受信者の目に触れる文言なので、この部分だけは翻訳され、それを囲むタグは翻訳されません。クイックスタートと同じようにグループ実行を開始し、言語ごとに訳文を取得します：

curl -s "$BASE/documents/<de-version-id>/content?format=html" \
  -H "Authorization: Bearer $KEY"
# → the same HTML with German copy, Liquid intact; paste it into the ESP's de variant

完全自動化の手法：ペイロードWebhookトリガーを使用すれば、ESPからテンプレートを直接受け取り、受信時にワークフローを実行して、group_run.completed Webhookで翻訳済みHTMLを返却できます。 プラットフォーム固有の仕様（BrazeのタグやMailchimpの条件分岐）については、ESPメールテンプレートおよびメールローカライズガイドをご覧ください。

用語集、スタイルガイド、翻訳メモリ

用語集を作成し、同じ呼び出し内で初期用語を登録します：

curl -s -X POST $BASE/glossaries \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name": "Product terms", "source_language": "en",
       "terms": [{"source_term": "Transept", "target_term": "Transept",
                  "do_not_translate": true}]}'

既存の用語集に用語を追加します（GET /glossariesで、キーから参照できる用語集の一覧を取得できます）：

curl -s -X POST $BASE/glossaries/<id>/terms/bulk \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"terms": [
        {"source_term": "workspace", "target_term": "Arbeitsbereich"},
        {"source_term": "run", "target_term": "Lauf", "notes": "the noun: a workflow execution"}
      ]}'

信頼できるドキュメントから生成することもできます。POST /glossaries/{id}/auto-buildとPOST /styleguides/generateを使い、それぞれ無料の…/estimateエンドポイントで見積もりを取得できます。どちらもクレジットを消費し、API経由ではauto_apply: trueの指定が必須です。ヘッドレス実行にはレビューの手順がないため、結果は完了時にそのまま確定します。進捗はGET /generation-jobs/{id}をポーリングして確認してください。 アプリ内でレビューしてから確定する方法は、ドキュメントから生成をご覧ください。 一度紐付ければ、以降の実行ではAPI、MCP、エディターのどこから実行しても、追加費用なしで適用されます：

curl -s -X PATCH $BASE/documents/<id>/translation-settings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"glossary_ids": ["<glossary_id>"], "styleguide_version_ids": ["<active_version_id>"]}'

スタイルガイドは有効なバージョンID（GET /styleguides/{id}で取得）によって紐付けられます。[]を指定すると紐付けが解除されます。どちらもPOST /documentsでのドキュメント作成時にも設定できます。 UIでの操作については、用語集およびスタイルガイドをご覧ください。 翻訳メモリは紐付けの必要がありません。完了した翻訳はすべて自動的にインデックス化され、再利用されます。検索（POST /translation-memory/query、無料）、TMX/XLIFFからの登録（POST /translation-memory/import、無料）、全体のエクスポート（GET /translation-memory/export-tmx）ができます。 詳細については、翻訳メモリおよび既存の翻訳を取り込むをご覧ください。

チーム

チームキーはチームのプールから課金され、チームのプロジェクト、用語集、スタイルガイド、翻訳メモリを引き継ぎます。チーム内にドキュメントを作成するには、チームプロジェクトのproject_idを指定します（GET /projectsで確認できます。チームプロジェクトにはteam_idが付与されています）。それ以外の動作は個人利用とまったく同じです。 チームやプロジェクトの設定はアプリ内で行えます。プロジェクト、チームと招待をご覧ください。

実行とレビューゲート

POST /runsは1つの言語バージョンを対象とし、POST /group-runsはすべての翻訳先の言語へ展開して、必要に応じて未作成の言語バージョンを作成します。どちらも無料で見積もりを取得でき、Idempotency-Keyヘッダーに対応し、キャンセルもできます。 ワークフローのステップがレビューを待つに設定されている場合、実行は一時停止します。GET /runs/{id}はgate_pending: trueと、レビューで検出された内容の要約を返します。 一時停止中に人が行う操作は、レビューパネルおよびガイド付きレビューをご覧ください。スクリプト側の処理は次のとおりです：

# continue downstream steps (all blocks, or a reviewed subset):
curl -s -X POST $BASE/runs/<id>/gate/approve \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"approved_block_ids": ["…"]}'    # omit the field to approve all

# a gate with nothing downstream is dismissed instead:
curl -s -X POST $BASE/runs/<id>/gate/acknowledge -H "Authorization: Bearer $KEY"

ゲートが自動的に続行することはありません。スクリプト、MCP経由のアシスタント、またはアプリ内の人間のいずれかが承認エンドポイントを呼び出す必要があります。続行すると残りのステップに課金されるため、まずはPOST /runs/<id>/gate/estimate（承認時と同じリクエストボディで、副作用はありません）で費用を見積もってください。MCP経由では、run_gate_approveはconfirm: trueを指定して再度呼び出されるまで、その費用を返します。実行開始時にゲートを事前承認するフラグはありません。処理を一切一時停止させたくない場合は、レビューステップを含まないワークフローを使用してください。

出力フォーマット

言語バージョンIDに対してGET /documents/{id}/content?format=<f>を実行します：

マスタードキュメントに対してformat=stringsを指定すると、1回の呼び出しですべての言語が返され、そのままコミットできます。

差分のみを更新

文字列カタログの場合は、現在のファイル全体を再送信します。差分の抽出はサーバー側で行われます：

# 1: re-import the complete current corpus; Transept diffs it by unit id
curl -s -X POST $BASE/documents/<master>/import-strings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d @app-ui.tstrings.json > delta.json
# → { units: {added, changed, unchanged, removed}, delta_block_ids: {<doc_id>: [block ids]} }

# 2: feed delta_block_ids VERBATIM into a group run; only those blocks translate
jq -n --slurpfile d delta.json \
  '{document_id: $d[0].master_document_id, template_id: "end_to_end",
    target_languages: "all", block_ids: $d[0].delta_block_ids}' \
| curl -s -X POST $BASE/group-runs \
    -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" --data-binary @-

変更のない文字列は訳文とレビュー状態が維持され、1件の文字列を修正した場合に消費されるクレジットは1件分のみです（再インポート時にrun: {template_id}をインラインで渡すと、同じ呼び出し内で差分を実行できます）。 これは変更された箇所だけを実行するのAPI側の動作です。 原文が変更された文章のドキュメントの場合は、POST /documents/{id}/resync-sourceでブロックの再同期を行います。変更のないブロックは訳文が維持され、変更されたブロックには未更新マークが付き、変更分のみを対象とする実行ではそれらだけが処理されます。再同期では保存されている原文ファイルが再解析されるため、原文の編集はブロックを直接修正するのではなくインポート経由で行ってください。

AIアシスタント（MCP）

https://app.transept.ai/api/public/v1/mcpでは、同じ一連の流れをエージェント用のツールとして使えます（me_get → document_create → group_run_estimate／group_run_start → group_run_get → document_content_get）。接続にはOAuthを使います（ブラウザーで承認するだけで、キーの貼り付けは不要です。ヘッドレス環境ではBearerキーも使えます）。ツールは付与された権限に従い、クレジットを消費する操作は必ず先に見積もりを返します。実行にはアシスタントによる明示的な確認が必要です。 クライアントごとの設定手順については、AIアシスタントの接続をご覧ください。

FAQ

見積もり、再インポート、初期登録された訳文にクレジットは消費されますか？

いいえ、消費されません。見積もりは無料で副作用もなく、カタログの再インポートも無料です（差分の計算はサーバー側で行われます）。ファイル内にすでにある訳文も、完了済みの作業として追加費用なしで反映されます。クレジットが消費されるのは、TranseptのAIがテキストを処理するとき（翻訳、リライト、チェック、または用語集やスタイルガイドの作成）のみで、料金一覧のレートが適用されます。上限で見積もられたクレジットは実際の消費額に基づいて確定し、未使用の確保分は解放されます。

自動化でレビューゲートをスキップできますか？

いいえ、できません。レビュー待ちに設定されたワークフローステップは、何らかの手段で承認されるまで実行を一時停止します。承認には、スクリプトによるゲート承認エンドポイントの呼び出し、またはアプリ内での人間による操作が必要です。パイプラインを最初から最後まで完全に自動で実行したい場合は、レビューステップを含まないようにワークフローを設定してください。設置されたゲートをスキップするフラグはありません。

APIはFreeプランでも利用できますか？

いいえ、利用できません。APIキー、MCP、WebhookはStarterプランおよびProプランで提供されており、Freeプランではいずれも利用できません。これらのプランでは、エディター上と同様にクレジット残高によって利用が制限されます。アカウントがFreeプランに移行する前に作成されたキーは、取り消しできるように一覧に表示されたまま残りますが、StarterまたはProに戻るまで動作しません。

手動でエクスポートせずにメールテンプレートをローカライズするにはどうすればよいですか？

メール配信プラットフォームの送信先にペイロードWebhookトリガーを指定します。POSTされたテンプレート本文がドキュメントとなり、ワークフローで翻訳され、翻訳が反映された同じ構造のHTMLが返されます。プレースホルダーやテンプレート構文は一連の処理全体を通して保護されます。プラットフォームごとの詳細な仕組みについては、メールローカライズガイドをご覧ください。

エンドポイントの網羅的なリファレンスはどこにありますか？

インタラクティブなSwaggerリファレンスをご覧ください。n8n、Zapier、コードジェネレーターにインポートできるのと同じOpenAPI仕様（生のJSON）から生成されています。本ガイドは全体の流れをつかむための入り口で、正式な仕様はOpenAPI仕様のほうです。