多语言与 Wiki 系统

本页讲解本博客的特色功能——多语言多 Wiki 系统：一套配置管理多个 Wiki 文档集（docs/api/tutorial），每个 Wiki 可有多语言版本（zh-cn/en），缺翻译时自动回落默认语言，并输出正确的 canonical/hreflang 供搜索引擎收录。本页同时是 Wiki 页面的创建与维护手册。

本文对应 docs/superpowers/specs/2026-08-16-multilang-wiki-design.md 设计文档；配置以 userConfig/_config.tmp.yml 的 preference 段为权威源。

1. 功能总览

2. 配置详解（preference.wiki）

配置（主题配置，preference.wiki 段）：

preference:
  wiki:
    enable: true            # 多语言 Wiki 系统总开关
    default_lang: zh-cn     # 默认语言（无前缀路径使用）
    langs:                  # 支持的语言列表
      - zh-cn
      - en
    lang_meta:              # 语言下拉菜单元数据（偏好面板展示）
      zh-cn:
        name: 简体中文
        flag: 🇨🇳
      en:
        name: English
        flag: 🇬🇧
    wikis:                  # 注册的 Wiki 列表
      - docs
      - api
      - tutorial

  # 中文繁简转换（原 footer.translate，2026-08-16 迁移聚合）
  translate:
    enable: true

兼容别名（配置末尾）：

# 主题代码继续读 theme.wiki（不迁移全部引用点）
wiki: *wiki_pref

说明：

• preference 是用户偏好聚合段（面板/语言/繁简统一管理）；wiki: *wiki_pref 是 YAML 锚点别名，主题代码读 theme.wiki 时拿到同一份配置，两者不要拆开改；锚点 &wiki_pref 定义在模板 preference.wiki 处（preference: wiki: &wiki_pref），两段需配合使用
• lang_meta 的 name/flag 用于语言下拉菜单展示，新增语言时必须补
• default_lang 不写进 URL 前缀（/docs/ 即中文），其他语言写（/en/docs/）

3. 语言切换（偏好面板）

用途：读者在页面右上角偏好面板切换语言/繁简。

• 语言切换：面板语言下拉框列出 lang_meta 中所有语言（带国旗），切换后跳转到当前页面的对应语言版本
• 繁简转换：preference.translate.enable 控制中文繁简转换按钮；默认方向由 zhDefaultEncoding 决定（1 繁体 / 2 简体）
• 记忆偏好：用户选择存入 localStorage，下次访问自动生效

4. Wiki 页面创建流程

用途：新建一个 Wiki（或往已有 Wiki 加页面）。以创建 tutorial Wiki 为例（本篇文档即其产物），共 4 步：

① 建页面目录（source/{wiki}/）：

mkdir -p source/tutorial/config   # 页面按章节放子目录

② 写页面文件（front-matter 必须含 layout: wiki + wiki: <名称>）：

---
title: 全局配置
layout: wiki
wiki: tutorial
---

# 全局配置

正文内容……

③ 配侧栏（source/_data/{wiki}-sidebar.yml，章节 → 页面映射）：

开始使用:
  overview: index.html
  install: install.html
配置参考:
  global: global.html
  multilingual: multilingual.html

④ 注册 Wiki（preference.wiki.wikis 加一项）：

preference:
  wiki:
    wikis:
      - docs
      - api
      - tutorial   # ← 新增

完成：访问 /tutorial/ 即进入该 Wiki，左侧栏自动按 sidebar.yml 渲染章节树（支持折叠），页面顶部有 Wiki 内导航。

5. 侧栏数据格式

文件：source/_data/{wiki}-sidebar.yml（如 docs-sidebar.yml、tutorial-sidebar.yml）。

格式：章节名: 页面key: 页面.html——键是页面文件的 slug，值是相对该 Wiki 根目录的 HTML 路径：

# tutorial-sidebar.yml 示例
功能指南:
  layout: layout.html
  tag-plugins: tag-plugins.html
配置参考:
  global: global.html
  nav-home: nav-home.html
  post: post.html
  widgets: widgets.html
  code-highlight: code-highlight.html
  multilingual: multilingual.html

说明：

• 章节顺序 = 渲染顺序；章节内页面顺序 = 文件内顺序
• 页面文件名（slug）与 {wiki}-sidebar.yml 中的键必须一致，否则侧栏链接 404
• 新增页面 = ① 建 md 文件 ② 在 sidebar.yml 对应章节加一行，两步缺一不可

6. 多语言与翻译

目录约定：翻译文件放在 source/{lang}/{wiki}/ 下，与源文件同名同路径：

source/
├── docs/                  # 默认语言（zh-cn）：docs Wiki 中文页面
│   ├── index.md
│   ├── setup.md
│   └── …
├── en/
│   ├── docs/              # docs Wiki 英文翻译
│   │   ├── index.md
│   │   ├── setup.md
│   │   └── …
│   ├── api/
│   └── tutorial/
└── _data/
    ├── docs-sidebar.yml
    └── tutorial-sidebar.yml

翻译要点：

• 英文页面 front-matter 同样写 layout: wiki + wiki: docs，并加 lang: en——侧栏链接前缀依赖 page.lang（wiki_sidebar 用 page.lang || default_lang），不写会被当作默认语言处理，链接指向 /docs/ 而非 /en/docs/
• lang_meta 中的语言代码与目录名一致（en ↔ /en/）
• 侧栏数据只维护默认语言一份，翻译版沿用

7. 回落机制（fallback）

用途：某语言的页面没翻译时，访问该语言路径仍返回内容，不白屏。

流程（生成层回落，由 scripts/helpers/wiki.js 检测）：

访问 /en/docs/setup/
  → /en/docs/setup/ 英文版存在？ → 渲染英文版（html lang=en, canonical=/en/docs/setup/）
  → 不存在 → 渲染默认语言内容（html lang=zh-CN, canonical=/docs/setup/, 顶部显示提示条）

效果：英文缺失的页面会显示"该页面暂无英文版，已显示中文"提示条，且 canonical 指向默认语言，避免搜索引擎收录重复内容。中文页面永远完整（默认语言不回落）。

8. SEO（canonical / hreflang）

输出规则（每个 Wiki 页面自动生成）：

说明：路径前缀（非 query string）+ hreflang + canonical 是 Google 多语言 SEO 的标准实践；sitemap 由 hexo-generator-sitemap 统一输出，Wiki 页面自动包含。

9. 常见操作

新增 Wiki

1. 建 source/{新wiki}/ 目录与页面（front-matter：layout: wiki + wiki: {新wiki}）
2. 写 source/_data/{新wiki}-sidebar.yml 侧栏
3. preference.wiki.wikis 加一项

新增语言

1. preference.wiki.langs 加语言代码（如 ja）
2. preference.wiki.lang_meta 补 name/flag
3. 建 source/{lang}/{wiki}/ 放翻译文件

新增文章（已有 Wiki）

1. 写 source/tutorial/xxx.md（front-matter 同上）
2. _data/tutorial-sidebar.yml 对应章节加一行
3. 可选：翻译到 source/en/tutorial/xxx.md

常见排查

• 侧栏链接 404：sidebar.yml 键与 md 文件名不一致
• 页面不显示侧栏：front-matter 缺 layout: wiki 或 wiki 名与 wikis 注册不一致
• 改了配置不生效：rm -f db.json && hexo generate（见「开发注意事项」）

附：多语言与 Wiki 速查表