本サイトの構成

全体構成

本サイトは、Cloudflare Workers・D1・R2の上でEmDash 0.38系を動かしています。原文の取得、差分の検出、翻訳の下書き作成はGitHub Actionsと生成AIが自動で行い、公開は運営者1名が最終チェックしてから行います。

flowchart LR
    UP["公式GitHub<br/>emdash-cms/emdash"] --> GA["GitHub Actions<br/>同期・差分検出"]
    NPM["npm / レジストリ"] --> GA
    GA --> TR["下訳<br/>Claude API＋用語集"]
    TR --> API["EmDash<br/>下書きとして保存"]
    API --> CMS["EmDash<br/>Workers＋D1＋R2"]
    ED["運営者の最終チェック<br/>管理画面"] --> CMS
    CMS --> WEB["公開サイト<br/>Workers Cache"]

原文の変更は自動で下書きになります。自動処理が公開状態を変えることはありません。

技術スタック

プロジェクトは、Cloudflare版のStarterテンプレートから作成しています。

npm create emdash@latest emdash-ja -- --template cloudflare:starter --pm pnpm --yes

環境

環境は、ローカル（開発）、プレビュー、本番の3つです。D1・R2・KVは環境ごとに別に作り、プレビュー環境を本番のデータベースにはつないでいません。プレビュー環境はWranglerの名前付き環境 preview で、バインディングはすべて書き直しています。秘密の値は pnpm wrangler secret put で登録しています。

選択の理由と他の選択肢は開発環境の持ち方にあります。

Cloudflareのリソース

データベースとメディアの選択はDBとファイル置き場の選び方、実行環境の選択は実行環境の選び方にあります。

コンテンツの持ち方

コンテンツは、9つのコレクション（公式ドキュメントの翻訳、全体像・入門・実践の記事、固定ページ、リリース要約、ニュース、用語集、パッケージ一覧、テンプレート一覧、プラグイン一覧）に分けています。すべてのコレクションで、下書き、リビジョン、プレビューを有効にしています。

• 本文の正本はEmDashのデータベース（D1）だけに置き、履歴はリビジョンで持っています。翻訳結果はGitに持っていません。
• コレクションとフィールドの定義は、シードファイル（seed/seed.json）としてGitで管理しています。公開後にスキーマを変えたときは、emdash export-seed でシードファイルに書き戻します。
• 公式ドキュメントの翻訳84ページは、src/pages/docs/[...path].astro の1つのルートで描画しています。
• 本文の投入は、変換・投入スクリプトがEmDash CLIを呼び出し、下書きとして保存しています。管理画面での手入力はしていません。

選択の理由はコンテンツの正本の置き場所にあります。

認証と権限

管理画面は、EmDash標準のパスキー認証で守っています。Cloudflare Accessは使っていません。人のユーザーは運営者1名だけで、パスキーを複数の端末に登録しています。

自動処理用のユーザーは、管理画面の招待で作り、そのユーザーの個人アクセストークン（ec_pat_ で始まるAPIトークン）でREST APIとMCPサーバーを使っています。組み込みのMCPサーバーは有効にし、AIツールから下書きを編集できるようにしています。トークンに付与する範囲は最小限にし、公開の操作は運営者が管理画面で行います。

選択の理由は管理画面の守り方と生成AIとの分担にあります。

プラグイン

選択の理由はプラグインの使い方にあります。

原文の同期から公開まで

GitHub Actionsが毎日、公式リポジトリの変更と新しいリリースを検知します。運営者が行うのは、通知を受けて、プレビューで確認し、公開することです。

sequenceDiagram
    participant GA as GitHub Actions
    participant AI as 生成AI
    participant CMS as EmDash
    participant OP as 運営者
    GA->>GA: 公式の変更・新リリースを検知
    GA->>AI: 翻訳・解説の生成を依頼
    AI-->>GA: 訳文と解説
    GA->>AI: 別モデルで相互レビュー
    GA->>CMS: 下書きとして保存
    GA->>OP: 変更一覧とプレビューURLを通知
    OP->>CMS: 確認して公開

本番へのデプロイは pnpm build → pnpm wrangler deploy の順で実行します。コアマイグレーションは本番デプロイの前にCIで emdash migrate を実行し、emdash migrate --check で確認します。

EmDashの更新の手順はEmDashの更新の追いかけ方に、人とAIの分担は生成AIとの分担にあります。

巻き戻しの仕組み

戻したいものを6つに分け、それぞれを別の仕組みで守っています。GitHubは、ソースを戻せる場所として、非公開リポジトリ1つを保管庫として使っています。

本番デプロイ、EmDash本体の更新、スキーマ変更、一括投入の直前には、D1の現在の時点（ブックマーク）を自動処理が記録し、通知に載せています。データベースを戻すときは、先に自動処理を止めて書き込みを止めます。管理画面から取れるJSONのバックアップは控えとしてだけ扱い、巻き戻しの手段には数えていません。

事態ごとの戻し方は巻き戻しの備えにあります。

費用

本サイトの費用は、Cloudflare Workersの有料プラン（月額5ドルから）と、D1・R2・KVなどの使用量に応じた料金で決まります。料金の範囲は実行環境の選び方とDBとファイル置き場の選び方にまとめています。本サイトでは、実際にかかっている月額は載せていません。

実践ページとの対応