多言語コンテンツをGitで管理すべき理由
ホスティング型CMSと翻訳プラットフォームを併用すると、情報源が分散し整合性が失われます。英語のMDX、翻訳データ、変更履歴をすべて1つのリポジトリにまとめることで、この問題を解決できます。これがScribeの基本モデルです。
View as Markdown多言語サイトの多くは、最終的に3つの情報源を抱えることになります。ホスティング型CMSのコンテンツ、翻訳プラットフォームの翻訳データ、そしてGitのコードです。それぞれが独自のバージョン管理、アクセス制御、そして「最新状態」の基準を持っています。これらを常に同期させ続けるのは骨の折れる作業であり、ズレが生じるのが当たり前の状態になってしまいます。
もっとシンプルなモデルがあります。すべてをリポジトリにまとめるのです。
Gitがすでに解決していること
普段のコード管理ワークフローは、コンテンツ管理における厄介な問題をすでに解決しています。
- レビュー: コンテンツの変更はプルリクエストとして扱われます。公開前に誰かが差分を確認できます。
- ロールバック: 誤った編集があっても、サポートチケットを切る必要はありません。単にリバートするだけです。
- アトミック性: コンテンツとそれをレンダリングするコードは同時にデプロイされます。スキーマの変更とそれに伴うコンテンツの移行も、1つのコミットで完了します。
- 履歴: プラグインがなくても、
git logを使えば「誰がいつ変更したか」がすぐにわかります。
ファイルベースのCMSなら、これらすべてが標準で備わっています。問題は、すべてのページを10の言語に展開したときに何が起こるかです。
翻訳における課題
最も単純なアプローチは、言語ごとにファイルを用意することです(about.en.mdx、about.fr.mdx、about.ja.mdxなど)。しかし、この方法はすぐに破綻します。10言語対応となると、50ページのサイトが500ファイルに膨れ上がります。チーム内にその言語を読める人がいなければレビューは不可能です。さらに、about.fr.mdxが最新の英語テキストを反映しているのか、それとも3ヶ月前のバージョンのままなのかを知る術もありません。
Scribeは、この2つの懸念事項を分離します。
- 英語コンテンツはMDXファイル: ドキュメントごとに1つのファイルを作成し、Zodスキーマで検証します。これは人間が書き、レビューする部分です。
- 翻訳データは1つのSQLiteファイルに集約: 翻訳データはMDXと同じ場所にコミットされます。各翻訳は、英語ソースのハッシュ値、およびそのソースの当時のスナップショットと紐付けられます。
このハッシュこそが、ズレをなくす決め手です。英語の段落を1つ編集すると、すべての言語で該当するドキュメントだけが明確に「古い状態」になります。scribe translateを実行すれば、そのドキュメントのみが再翻訳されます。知らないうちに翻訳が遅れることはなく、scribe statusを使えば、どのコミット時点でも正確な翻訳カバレッジを確認できます。
構造的にサーバーが不要
すべてがリポジトリ内のファイルであるため、ホスティングするものは何もありません。ランタイムはビルド時にディスクからMDXとSQLiteを読み込み、完全に型付けされたドキュメント(リスト、ルックアップ、リレーション、hreflang代替、サイトマップエントリなど)をフレームワークに渡します。リクエスト時に呼び出すCMS APIも、ローテーションが必要なトークンもありません。ベンダーの障害でコンテンツがダウンすることもありません。読み込みの仕組みについては、ランタイムAPIをご覧ください。
AIエージェントとの最高の相性
このモデルには、おそらく最も強力とも言える新たな利点があります。それは、AIエージェントがリポジトリの扱いを得意としている点です。コーディング支援エージェントはすでに、ファイルの検索、プレーンテキストとしてのMDXの読み込み、ブランチでの編集、プルリクエストの作成方法を熟知しています。これをホスティング型CMSでやろうとすると、見出しを1つ変更する前に、APIやトークン、カスタム連携の設定に追われることになります。
ガードレール機能もそのまま引き継がれます。FrontmatterはZodスキーマによって検証され、すべての本文はMDXとしてコンパイルされる必要があるため、エージェントが不正なドキュメントを保存することはできません。ビルドの前にscribe validateがそれを検知します。さらに、すべての編集はコミットとして扱われるため、AIによる変更も人間による変更と同様に、差分確認、レビュー、承認のプロセスを経ることになります。このサイト自体もまさにそのように運営されており、ドキュメントや変更履歴のメンテナンスの大部分をエージェントが行い、人間がその差分をレビューしています。
このモデルが適さないケース
正直にお伝えします。GitベースのCMSは、コンテンツを編集する人がファイルやプルリクエストの操作に慣れているか、編集者とリポジトリの間に技術者が介在することを前提としています。編集者がWYSIWYGインターフェースや公開ボタンを必要としているなら、ホスティング型CMSを選ぶのが正解です。Scribeには、翻訳の閲覧、検索、検査を行うためのローカル環境用のstudioが同梱されていますが、執筆自体は普段のエディタで行います。
しかし、チームがすでにGitを中心とした開発を行っているなら、コンテンツや翻訳のために2つ目、3つ目のシステムを追加することは、単に管理の負担を増やすだけです。1つのリポジトリ、1つのレビューフロー、1回のデプロイ。これで完結します。
試してみる
必要なセットアップは、1つの設定ファイルとMDXファイルのフォルダのみです。
pnpm add scribe-cms zod better-sqlite3