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

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

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

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

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

今回の記事は言語を追加し、バージョンをスナップショットとして固定するところまで扱います。どちらもプラグインなしで標準機能でできます。

言語を追加する — 内蔵i18n #

多言語はdocusaurus.config.jsに言語を宣言することから始まります。

docusaurus.config.js — 多言語 
export default {
  i18n: {
    defaultLocale: 'ko',
    locales: ['ko', 'en'],
  },
};

その後、翻訳するテキストの雛形を抽出します。このコマンドが、UI文字列とドキュメントの翻訳用の場所をi18nフォルダに作ってくれます。

翻訳の雛形を生成 
npm run write-translations -- --locale en

英語のドキュメントはi18n/en/docusaurus-plugin-content-docs/current/の下に同じファイル名で置いて翻訳します。特定の言語でプレビューするには--localeを付けて実行します。

英語でプレビュー 
npm run start -- --locale en

上部メニューに言語選択のドロップダウンを加えるには、navbarにlocaleDropdown項目を入れればよいです。

バージョン管理 — 内蔵versioning #

ここでDocusaurusは先のツールたちを上回ります。Hugo編ではバージョン管理機能がなくフォルダで分ける必要があり、MkDocs編ではmikeという別のツールを付けました。Docusaurusはコマンド一つで現在のドキュメントを丸ごとスナップショットとして固定します。

現在のドキュメントを1.0として固定 
npm run docusaurus docs:version 1.0

このコマンドは、いまのdocsの内容をversioned_docs/version-1.0にコピーして凍結します。以降docsを直すと、それは次のバージョンになり、1.0のドキュメントはそのまま残ります。上部にバージョン選択のドロップダウンを加えるには、navbarに項目を入れます。

docusaurus.config.js — バージョンドロップダウン 
navbar: {
  items: [
    { type: 'docsVersionDropdown', position: 'left' },
  ],
}

製品が2.0に上がったら、docs:version 2.0で新しいスナップショットを固定すればよいです。読者はドロップダウンから自分のバージョンを選んで見ることができます。

まとめ #

今回の記事では、内蔵i18nで言語を追加し、内蔵versioningでバージョンをスナップショットとして固定しました。多言語とバージョン管理をどちらも標準で備えている点が、Docusaurusを大規模な製品ドキュメントで強くしている理由です。

次回は最終回です。検索をきちんと付け、アクセシビリティと、ドキュメントを長く生かしておく習慣まで、運用の観点を整理してシリーズを締めくくります。

X