Languages and translations

すべてのパスは Public API base URL からの相対パスです。各リクエストに X-Api-Key、本文を送る書き込みには Content-Type: application/json を付けます。言語ルートは、どの言語が存在し公開されているかを管理します。翻訳ルートは、翻訳されたテキストを編集します。

言語の操作

成功時はすべて 200 を返します。翻訳ドキュメントの ID ではなく、en や ja などの言語コードを指定してください。

追加した言語は非公開の状態で作成されます。翻訳サービスが内容を準備し、自動翻訳の有無は現在のプランと利用枠で決まります。レスポンスが確認できず再試行する場合は、先に GET /languages でそのコードが追加済みか確認してください。

PATCH で受け付けるのは status フィールド 1 つだけで、値は published または unpublished です。ほかのフィールドを含むと拒否されます。言語を公開しても、デフォルト言語は変わりません。公開はプランの言語数の上限に含まれ、デフォルト言語と公開済みの言語がすでに上限に達している場合、ルートは 403 PLAN_LIMIT を返します。ステータスの変更はストアフロントに反映されます。

curl -X PATCH 'https://app.chatty.net/v1/languages/ja' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"status":"published"}'

デフォルト言語の変更と削除

デフォルト言語の変更には confirm: true が必要です。選択した言語がデフォルトかつ公開状態になり、以前の言語のデフォルト指定が解除されます。指定した言語がなければ、先に作成されます。以前のデフォルト言語の公開状態は、ストアのプランに従います。

curl -X PUT 'https://app.chatty.net/v1/languages/default' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"code":"ja","confirm":true}'

デフォルト言語は削除できません。先に別の言語をデフォルトにしてから、以前のコードを削除してください。削除すると保存済みの翻訳ドキュメントが消去されます。非公開にする操作とは異なります。

翻訳コンテンツの編集

{code} はすでに存在する言語コードです。先に POST /languages で追加してください。未知のコードは 404 NOT_FOUND と Translation not found を返します。本文は厳密に検証されます。

GET /translations/{code} は、保存済みの翻訳をセクションごとに返します。読み取りで何かが作成されることはありません。

{
  "data": {
    "id": "translation_123",
    "language": "fr",
    "isDefault": false,
    "status": "unpublished",
    "isAutoTranslate": false,
    "Show Navigation": {"Search": "Chercher"},
    "Help center": {},
    "FAQs": {"category_123": {"question": "Livraison", "questions": [{"questionId": "question_123", "question": "...", "answer": "..."}]}},
    "FAQ Suggestions": {"suggestion_123": {"question": "...", "answer": "..."}}
  }
}

この例は抜粋で、FAQ page や Campaign などのセクションも含まれます。

フィールドの編集。 PATCH /translations/{code} は、path と value を持つ fields を 1〜1,000 件受け付けます。path は次のいずれかのセクション、またはその中のキーである必要があります：Show Navigation、FAQ page、FAQs、Campaign、Help center、Synced Widget Copy、emailReplyHint。language や isDefault など、それ以外の path は 400 VALIDATION_FAILED と Translation path is not editable を返します。Show Navigation と Help center では、セクション全体を文字列のオブジェクトとして送ることもできます。メールのテキストにはリンクを含められません。デフォルト言語の変更は、ウィジェットのコピーとヘルプセンターにも反映されます。

FAQ の編集。 カテゴリのルートは、翻訳したカテゴリ名を question として受け取ります（最大 10,000 文字）。質問のルートには categoryId、question、answer が必要です（answer は最大 100,000 文字）。提案 FAQ のルートには question と answer が必要です。カテゴリ、質問、提案はその言語にすでに存在している必要があり、存在しない場合は 404 NOT_FOUND を返します。

リセット。 POST /translations/{code}/reset は、その言語の生成済みの翻訳を再構築します。autoTranslate: true を指定すると、その言語の自動翻訳も有効になります。リセットはストアごとに、すべての言語、キー、MCP を合わせて 1 時間あたり 5 回までで、次の呼び出しは 429 RATE_LIMITED を返します。

自動翻訳には有料プランと、空きのある自動翻訳の枠が必要です。autoTranslate: true を送信した場合、またはその言語がすでに自動翻訳を使っている場合、無料プランは 403 PLAN_RESTRICTED を返し、利用枠が埋まっていると 403 AUTO_TRANSLATE_LIMIT を返します。

すべての書き込みは、呼び出したキーとともに監査ログに記録されます。

エラー

エラーの形式は次のとおりです：{"error":{"code":"VALIDATION_FAILED","message":"Only status (published or unpublished) can be updated"}}.

MCP tool reference では、言語の読み取りに get_settings_resource、言語の変更に manage_languages、翻訳に manage_translations を使用します。OAuth では、manage_translations は読み取りのみ可能です。action、code、body の指定方法は、同リファレンスをご覧ください。