Docsbook
概要

翻訳設定

このページは設定画面です。存在する言語、翻訳に使用するモデル、パスを実行するタイミング、読者が言語を切り替える場所、そして翻訳されたすべてのURLの形式を設定します。パスの実際の仕組みについてはAI翻訳を、結果の品質については翻訳品質とSEOをご覧ください。

自動翻訳と翻訳ワークフローの管理機能は有料プランの一部です — 料金をご覧ください。無料プロジェクトではこのページのすべてを表示でき、プロジェクトの接続時にはソース言語も引き続き自動検出されます。ただし、無料プロジェクトではそのいずれも変更できません。有効な言語とソース言語は同じプラン制限グループに属しているため、翻訳モードやパスの開始の場合と同様に、無料プロジェクトでは両方とも拒否されます。

設定可能な項目#

設定項目 内容
デフォルト（ソース）言語 ドキュメントがすでに記述されている言語。翻訳対象にはなりません。
有効な言語 ドキュメントを追加で公開する言語。
翻訳モデル 翻訳を実行するAIモデル。チャットモデルとは別のものです。
翻訳モード auto、manual、またはexternal — 翻訳処理を開始する方法。
言語切り替え 読者に表示するセレクターの位置（サイドバー、ヘッダー、またはその両方）。

プロジェクトのソース言語#

Docsbook は、ユーザーに尋ねるのではなく、ドキュメントが記述されている言語を検出します。プロジェクトが接続されると、リポジトリの README を読み取り、コードフェンス、インラインコード、画像、リンク、HTML を取り除いたうえで、残ったテキストに対して言語識別子を実行します。

重要なルールは次のとおりです。

  • 除去後の文章が 50 文字未満の場合、または確信を持って判定できない場合は en にフォールバックします。その場合は信頼度が低として記録されるため、パネルでは推測を検出結果として提示するのではなく、最有力候補 — 確認してください と表示できます。確信を持って検出された場合は、信頼度が高として記録され、自動検出 と表示されます。自分で設定すると あなたが設定 と表示され、固定されます。
  • 検出器が認識するのは、Docsbook がサポートする 15 個のコードだけです。そのセットに含まれない言語の README は、en フォールバックに移行します。
  • ソース言語を翻訳対象として有効にすることはできません。渡された場合は enabled_languages から除外され、翻訳処理でも明示的にスキップされます。言語が有効かどうかを確認する前に、理由 is_source_language によってスキップされます。これは UI の入力検証ではなく構造上のガードです。古いデータベースの行や直接の API 呼び出しによって、プロジェクトが英語を英語に翻訳する費用を負担することはありません。
  • 英語だけが特別扱いされるわけではありません。ドキュメントがドイツ語で記述されたプロジェクトでは、上記すべてが鏡像のように適用されます。

言語を有効にする#

  1. ドキュメントサイトを開きます。
  2. Float Widget → 翻訳タブ。
  3. 希望する言語にチェックを入れます。
  4. ダイアログを確認します。処理がバックグラウンドで開始されます。

言語スイッチャーがすでにサイトに表示されている場合は、それを開いて言語を有効化を押すと、同じタブに移動します。この入口は所有者であるあなた、または管理者プレビューでのみ表示され、読者には決して表示されません。

言語を有効にしても、APIレベルで自動的に翻訳されるわけではありません。update_languages がセットを設定し、run_translation_pass（またはモード独自のトリガー）が処理を実行します。パネルではこの2つが自動的に結び付けられているため、ボックスにチェックを入れると処理が開始されます。

ダイアログはまず実行内容の見積もりを表示します#

何も支出される前に、確認ダイアログには、全ページのうちまだ翻訳されていないページ数、推定費用、残高が表示されます。実行に必要な残高が足りない場合は、残高でドキュメントの何割をカバーできるかが示され、チャージする選択肢が提示されます。また、翻訳可能な分を翻訳することも実際に選択できます。残高で対応できるページは今すぐ翻訳され、残りは残高が足りるようになった時点で自動的に処理されます。

見積もりは選択したモデルに基づいて算出されるため、見積もりと請求は同じモデルについてのものです。これを明示的に説明する必要があるのは、以前はそうではなかったためです。見積もりではあるモデルの料金を算出しながら、実行には別のモデルを使用していました。

翻訳モデルの選択#

設定 ▸ 翻訳 ▸ 翻訳モデルでモデルを選択します。これは、読者チャットが使用するモデルとは意図的に別の設定です。文章の翻訳と、ツールを使って質問に答えることは異なる作業であり、一方を動かす測定値がもう一方まで動かす理由はありません。

何も選択しない場合、ピッカーではデフォルトとして(default)が表示され、現在はGPT-5.6 Lunaです。各オプションには100万トークンあたりの料金が表示されるため、より安価なモデルなら残高をより多くのページに使え、言語の読み取りがうまくいかない場合は、より高性能なモデルをワンクリックで選択できます。管理モードでは、Docsbookのカタログにあるモデルのみが使用されます。料金はモデルの公開価格で請求され、認識されないモデルを選ぶと、表示されていない料金で請求されることになるためです。

独自の翻訳APIキーを持ち込む場合、そのカードのモデルは自由入力フィールドになり、実行料金はプロジェクト残高ではなく、利用するプロバイダーから請求されます。独自のキーを持ち込んでも、無料プロジェクトで翻訳が利用可能になるわけではありません。制限はコストではなく、プランによって決まります。

翻訳を実行するタイミングを選択#

モード 実行のトリガー
自動 ドキュメント化されたページを変更するプッシュによって、そのページが有効なすべての言語で再キューに追加されます。
手動 自動的には何も開始されません。今すぐ翻訳を押すか、エージェントに依頼します。
外部 Webhook 自動的には何も開始されません。Docsbook が translation.needed を発行し、独自のパイプラインで処理を決定します。

自動では、Docsbook は Webhook に反応するのではなく、リポジトリをポーリングします。ワークスペースはおよそ 15 分ごとに確認され、1 回の実行で調べられるワークスペースは 4 つだけです。そのため、プッシュした瞬間ではなく、その時間枠内のおよそいつからキャッチアップが始まると考えてください。遅れているページは、まだ一度も翻訳されていないページより先に翻訳されます。古い翻訳は、ドキュメントがもはや述べていないことを読者に積極的に伝えてしまいますが、未翻訳のページは元の内容にフォールバックするだけで、役に立たないにとどまるためです。

エージェントは set_translation_mode MCP ツールでモードを設定します。

// auto: Docsbook follows new commits and re-translates the pages they changed
set_translation_mode({ workspace_id: 42, mode: "auto" })
 
// external: nothing runs here; your pipeline listens for translation.needed
set_translation_mode({ workspace_id: 42, mode: "external", external_webhook_url: "https://example.com/hooks/translate" })

external モードでは、translation.needed イベントを受信し、独自のパイプラインを実行して、結果を upload_translation で返します。Webhook URL を一度も指定していない状態で external を設定すると、黙って受け入れられるのではなく拒否されます。

言語切り替えの配置#

切り替えはサイドバー、ヘッダー、またはその両方に表示できます。ヘッダーへの配置は独立したワークスペース設定です。サイドバーでは、モバイルでのみ切り替えを表示するよう追加設定することもできます。これにより、横幅の広いデスクトップのヘッダーには表示し、狭いレイアウトでは重複表示しないようにできます。

配置 適しているケース
ヘッダー 目につきやすく、海外の利用者を対象とする場合に適しています
サイドバー ヘッダーがすでにいっぱいの場合に、ヘッダーのスペースを節約できます

どちらか一方を選択してください。同じ画面に同じコントロールを2回表示すると、ノイズになります。ヘッダーのオプションまたはサイドバーのコントロールで設定できます。

有効な言語がないサイトでは、項目が1つだけ入ったコントロールを表示するのではなく、切り替え自体を表示しません。

翻訳されたページのURL#

ロケールは常にパスセグメントであり、サブドメインではありません。https://fr.docsbook.io/…は存在せず、言語のみのサブドメインは、同じコンテンツに対する2つ目のアドレスにならないよう、意図的に404として提供されます。

https://<user>.docsbook.io/<repo>/<path>          → your source language
https://<user>.docsbook.io/fr/<repo>/<path>       → French
https://<user>.docsbook.io/ja/<repo>/<path>       → Japanese

カスタムドメインではリポジトリセグメントがなくなり、ロケールは先頭の位置を維持します。

https://docs.example.com/<path>                   → your source language
https://docs.example.com/fr/<path>                → French

知っておくべき点が2つあります。

  • カスタムドメインを持つワークスペースの正規URLは、そのドメインです。翻訳ページでもオリジナルページでも、docsbook.ioミラーではありません。2つを混在させると、ページ自身の正規URLが指していない場所をhreflang近隣ページが指すことになります。
  • /en/…は存在しますが、別個のページではありません。英語は/<repo>/<path>と/en/<repo>/<path>で同一に提供され、プレフィックス付きの形式はプレフィックスなしの形式を正規URLとして宣言します。そのため、互いに競合することなく、インデックス可能な1つのページに統合されます。

Docsbookでホストされるサイトの一部、つまりプロダクト自体のドキュメントやショーケースプロジェクトは、リポジトリセグメントの後にロケールを置いた状態で、apexドメイン上に提供されます（https://docsbook.io/<repo>/fr/<path>）。Docsbookは、それらの正規URLとhreflangを、ルーティングを行うのと同じ関数から構築します。そのため、広告するURLは、リダイレクトではなく常に200を返すURLになります。

言語をオフにする#

翻訳タブでチェックを外すか、その言語専用ページのスイッチを使用します。何も破棄されないため、確認は求められません：

  • 保存された翻訳は保持されます。言語を再びオンにしても、変更されていないページについて再度料金が発生することはありません。新規ページと編集されたページのみが翻訳されるため、以前使用していた言語を再有効化しても、ほぼ瞬時に、ほぼ無料で利用を再開できます。
  • その言語のレポートページも保持されるため、「これを再びオンにすべきか？」という判断を、すでに得られている読者数とコストに基づいて行えます。
  • 無効にしたロケールの URL にアクセスした読者は、ソース言語版に移動します。

制限#

  • コードは15種類で、地域バリエーションはありません。 pt は1つのページセットでブラジルとポルトガルをカバーし、zh は1つのページセットで簡体字と繁体字をカバーします。保存される言語列は5文字に対応しているため、pt-BR のようなコードも保存できますが、製品内で生成または提供されることはありません。
  • 自動モードはWebhookではなく、ポーリングです。 プッシュは次回のスキャン時に取得されます。稼働中のフリートが混雑している場合、1つのワークスペースでスキャンが行われるまでの待ち時間が15分を超えることがあります。約1時間プロジェクトがスキャンされていない場合、言語ごとのパネルでは予定どおりであるかのように装わず、スキャンの期限超過として表示します。
  • 言語切り替えは、読者向けに提供される唯一の言語コントロールです。 Docsbook は Accept-Language によって読者をリダイレクトせず、地理情報に基づくルーティングも行いません。言語設定を指定していない読者には、サイトで設定されたデフォルトが適用されます。
  • モデルの選択は言語ごとではなく、ワークスペースごとです。 1つのプロジェクト内で、日本語をポーランド語よりも高性能なモデルで翻訳することはできません。

Updated

このページは役に立ちましたか？

提供： Docsbook