Starlightでマニュアルを作る #5 多言語とバージョン管理

フレームワーク Starlight Documentation Static Site
読了 3分

#4でドキュメントをインターネットに公開しました。ユーザーが増えると、二つの要求が付いてきます。一つは別の言語でも見たいということ、もう一つは古いバージョンの製品を使う人のために過去のドキュメントも残してほしいということです。今回の記事はその二つを扱います。

今回のシリーズはStarlightでマニュアルを作る全6回です。

  • #1 インストールから最初のドキュメントまで
  • #2 サイドバーと検索 — ドキュメントの情報構造を整える
  • #3 コンテンツ作成 — コードブロック、Mermaid、aside
  • #4 Cloudflare Pagesでデプロイしてドメインを接続する
  • #5 多言語とバージョン管理 ← 今回の記事
  • #6 メンテナンス — 検索、アクセシビリティ、ドキュメント文化

今回の記事は、言語を追加し、バージョンを管理するところまで扱います。

言語を追加する — 組み込みi18n #

多言語はStarlightが標準で備えた機能です。astro.config.mjsのStarlight統合に言語を宣言します。

astro.config.mjs — 多言語 
starlight({
  title: '製品マニュアル',
  defaultLocale: 'ko',
  locales: {
    ko: { label: '한국어' },
    en: { label: 'English', lang: 'en' },
  },
})

ドキュメントは言語別フォルダに同じ名前で置きます。

翻訳ファイルの配置 
src/content/docs/
├─ ko/
│  └─ guides/install.md   # 韓国語
└─ en/
   └─ guides/install.md   # 英語

こう置くとStarlightが両者を同じ記事の翻訳として認識し、上部に言語切り替えメニューを自動で表示します。翻訳していない記事はデフォルト言語で代替されるので、一度に全部を翻訳しなくてもサイトが壊れません。

バージョン管理 — プラグインで #

ここでは正直に押さえておくべき点があります。Starlightのコアにはバージョン管理機能がありません。Docusaurusがバージョンを内蔵しているのとは異なる点です。代わりにstarlight-versionsのようなコミュニティプラグインで加えます。

バージョンプラグインのインストール 
npm install starlight-versions

プラグインをStarlight統合のpluginsに登録すると、現在のドキュメントをバージョンとして凍結し、上部にバージョンセレクターを付けられます。バージョンの要求が強いなら、同じ機能をコアで備えるDocusaurusと比較してみるとよいでしょう。ツールごとのバージョン管理方式の違いはドキュメントサイトジェネレーター比較の記事に整理してあります。

まとめ #

今回の記事では組み込みi18nで言語を追加し、プラグインでバージョン管理を加えました。多言語は手軽に解決でき、バージョン管理は一段階の手間がかかるものの、プラグインで埋められる点を確認しました。

次回は最後の回です。検索、アクセシビリティ、そしてドキュメントを長く生き続けさせる習慣まで、運用の観点を整理してシリーズを締めくくります。

X