サイト全体の i18n

サイト全体の i18n (MkDocs)¶

pyrs-yaml のドキュメントサイトは、MkDocs Material テーマの組み込み i18n を使用して サイト全体の国際化 をサポートしています。ユーザーは英語（en）、中国語（zh-CN）、日本語（ja-JP）、韓国語（ko-KR）でドキュメントを表示できます。

ランタイムのエラーメッセージ i18n ガイドについては、guides/i18n.md で set_language() / get_language() を参照してください。

How It Works¶

各言語は独自の URL パス（/zh-CN/、/ja-JP/、/ko-KR/）を持ち、zensical.toml で設定された右上隅の言語切り替え機能を備えた 1 つのナビゲーションを共有します:

[project.extra]
alternate = [
    {name = "English", link = "/pyrs-yaml/en/", lang = "en"},
    {name = "中文", link = "/pyrs-yaml/zh/", lang = "zh"},
    {name = "日本語", link = "/pyrs-yaml/ja/", lang = "ja"},
    {name = "한국어", link = "/pyrs-yaml/ko/", lang = "ko"},
]

Directory Structure¶

各ロケールは docs/<lang>/ 以下に存在し、英語の docs/en/ ツリーをミラーリングします:

docs/en/  (canonical English)
docs/zh-CN/  (or docs/zh/)
docs/ja/  (or docs/ja-JP)
docs/ko/  (or docs/ko-KR)

Frontmatter¶

翻訳されたファイルはすべて、lang フィールドを持つ YAML フロントマターを 必ず 含める必要があります:

---
title: ドキュメントタイトル
lang: ja-JP
---

Link Rules¶

• 内部リンクに言語プレフィックスを 含めないでください — 相対パス（quick-start.md）を使用してください。
• コード例は言語間で変更されません。
• ライセンスの法的テキストは英語のままです。見出しと説明のみが翻訳されます。

Verification¶

# 4 言語すべてをビルド
uv run --group docs python scripts/build-docs.py

# 開発用に単一言語をプレビュー
uv run --group docs python -m zensical serve --config-file zensical.toml --dirty

Troubleshooting¶