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

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

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

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

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

この記事では 言語を追加し、翻訳ファイルを接続し、バージョンごとのドキュメントを一緒に維持する ところまで扱います。

言語を追加する #

多言語は Hugo の標準機能なので、テーマに関係なく動作します。hugo.yaml に言語を宣言します。

hugo.yaml — 言語設定 
defaultContentLanguage: ko
defaultContentLanguageInSubdir: true

languages:
  ko:
    languageName: 한국어
    weight: 1
  en:
    languageName: English
    weight: 2

defaultContentLanguageInSubdir: true を与えると、既定の言語も /ko/ の下に入り、すべての言語が同じルールで揃います。言語が二つ以上になると、Hextra は上部に言語切り替えメニューを自動で表示します。

翻訳ファイルを置く #

同じドキュメントの言語別バージョンは、ファイル名のあとに言語コードを付けて並べて置きます。

翻訳ファイルを置く 
content/docs/
├─ getting-started.md       # 既定の言語(韓国語)
└─ getting-started.en.md    # 英語

ファイル名が同じで位置も同じなら、Hugo が両者を同じ記事の翻訳として自動認識します。もし言語ごとに slug を別にしたい場合は、ファイル名の代わりに translationKey でまとめます。

translationKey でまとめる 
---
title: はじめに
translationKey: getting-started
---

英語のファイルにも同じ translationKey を書いておけば、名前が違っても同じ記事の翻訳として接続されます。サイドバーのラベルやボタンのような UI 文字列は、i18n フォルダの翻訳テーブルで言語別に埋めます。

バージョン管理 — 決まった正解はない #

ここで一つ正直に押さえておく点があります。Hugo にはドキュメントのバージョン管理機能が 標準ではありません。 Docusaurus がバージョンスナップショットとバージョン選択ドロップダウンを内蔵で提供するのとは違う点です。そこで Hugo では、バージョンをフォルダで直接分けます。

バージョンごとのフォルダ 
content/docs/
├─ v2/          # 最新
│  ├─ _index.md
│  └─ getting-started.md
└─ v1/          # 過去のバージョン
   ├─ _index.md
   └─ getting-started.md

そして上部メニューに各バージョンへ行くリンクを置き、読者に自分でバージョンを選ばせます。

hugo.yaml — バージョンメニュー 
menu:
  main:
    - name: v2 (最新)
      pageRef: /docs/v2
      weight: 1
    - name: v1
      pageRef: /docs/v1
      weight: 2

バージョンが二つ三つ程度なら、この方式で十分です。ただしバージョンごとに「このページの別バージョン」のような緻密な接続が必要だったり、バージョンが増え続けたりするなら、その機能を内蔵した Docusaurus のほうが合うこともあります。ツール選択は、結局こうした要求がどれだけ強いかにかかっています。

まとめ #

この記事では、言語を追加して翻訳ファイルを接続し、バージョンをフォルダで分けて一緒に維持する方法を扱いました。多言語は Hugo がよく支えてくれる領域で、バージョン管理は少し手間がかかりますが、フォルダ分離で現実的なところで解決できます。

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

X