站点级 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 中配置：

zensical.toml i18n 配置

[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/  (规范英文版)
docs/zh-CN/  (或 docs/zh/)
docs/ja/  (或 docs/ja-JP)
docs/ko/  (或 docs/ko-KR)

Frontmatter¶

每个翻译文件必须携带 YAML frontmatter，包含 lang 字段：

翻译文件 frontmatter

---
title: 文档标题
lang: zh-CN
---

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¶

Issue	解决方案
语言切换器未显示	确保 `i18n` 块已配置，且每个 `alternate_languages.lang` 有对应的目录
链接损坏	确认内部链接使用相对路径（无语言前缀）
Frontmatter 未解析	确保每个文件以 `---` 开头，后跟 Markdown 内容
搜索无法按语言区分	使用 `uv run --group docs python scripts/build-docs.py` 重新构建