多语言与 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 语言段）

配置（主题配置，preference 段，2026-09-08 迁移：从 preference.wiki 提升为全站配置，删重复 langs）：

preference:
  default_lang: zh-cn         # 默认语言（无前缀路径使用，所有组件：wiki/post/搜索）
  fallback_lang: en           # 回落语言：请求语言不存在时先回落此语言（须在 lang_meta enabled 中）
  lang_meta:                  # 语言能力表 + 生效开关：key=语言，enabled=true 才生效
    zh-cn:
      name: 简体中文
      flag: 🇨🇳
      enabled: true
    en:
      name: English
      flag: 🇬🇧
      enabled: true
    de:
      name: Deutsch
      flag: 🇩🇪
      enabled: false
    # ... 9 语言全列（de/en/eo/es/ja/ru/zh-CN/zh-HK/zh-TW），enabled 控制生效
  wiki:
    enable: true            # 多语言 Wiki 系统总开关（wiki 特有开关保留在此）
  # 中文繁简转换（原 footer.translate，2026-08-16 迁移聚合）
  translate:
    enable: true

说明：

• wiki 系统自动扫描 source/{wiki}/ 目录（front-matter layout: wiki）与 source/_data/{wiki}-sidebar.yml，无需配置注册
• 语言能力表 = lang_meta 的 keys（9 语言全支持）；生效语言 = enabled: true 的 keys——未启用的语言不生成回落页、不出现在语言下拉、不作为回落目标
• fallback_lang：回落中间层——请求语言不存在时先回落此语言；默认值 = 首个 enabled 非默认语言
• lang_meta 的 name/flag 用于语言下拉菜单展示，新增语言时必须补
• default_lang 不写进 URL 前缀（/docs/ 即中文），其他语言写（/en/docs/）
• 旧 preference.wiki.default_lang/langs 位置已废弃（2026-09-08 迁移，兼容期 lang-config.js 仍兜底读取）

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

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

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

客户端语言策略（2026-09-10，方案 A 全站跟随）：

• 首访弹窗：无本地偏好且浏览器语言匹配已启用语言（非默认）→ 弹窗询问是否切换；接受则记忆并跳转，拒绝则记住默认语言（不再重复弹）
• 页面加载 / 刷新跟随：有本地偏好 → 任何页面直接按偏好加载对应语言版（head 内联重定向，早于渲染无闪现）；爬虫跳过（SEO）；无多语言版的路径跳过（防 404）
• 面板回显：语言下拉显示本地偏好（localStorage.wiki_lang），而非当前 URL 语言

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 系统自动扫描 source/tutorial/ 目录（front-matter layout: wiki + wiki: tutorial），无需配置注册。访问 /tutorial/ 即进入该 Wiki，左侧栏自动按 tutorial-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/）
• 侧栏数据只维护默认语言一份，翻译版沿用

文章翻译（source/{lang}/_posts/）：与 wiki 同为"同名"约定——

• 中英关联双模式：有 abbrlink 插件 → 相同 abbrlink 关联；无插件 → 同名文件关联（带文件系统兜底检查）
• hexo 原生只认 source/_posts/（en/_posts/ 会被忽略），文章翻译由主题 i18n-post-generator.js 生成 /{lang}/posts/{abbrlink}/
• 有真实翻译 → 真实内容页；无 → 回落页（见 §7）

7. 回落机制（fallback，2026-09-08 统一为三层回落链）

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

回落链（所有模块统一：wiki/post/聚合页/搜索，lang-config.js 解析）：

请求语言存在？        → 用它
→ 不存在 → fallback_lang 存在？ → 回落 fallback_lang
→ 不存在 → default_lang 存在？  → 回落 default_lang
→ 不存在 → 任意可用语言（第 1 个）

流程（生成层回落，由 scripts/generators/{post,wiki}-fallback.js 生成）：

访问 /de/docs/setup/（de 已启用但无翻译）
  → 有 en 翻译 → 回落页内容用 en 版（fallback_lang 生效）+ 提示条"de 不存在，显示 en"
  → 无 en 翻译 → 回落页内容用 zh-cn 版 + 提示条"de 不存在，显示 zh-cn"

效果：

• 内容语言按回落链选择（_fallbackFrom 标记实际语言），提示条显示"xx 语言不存在，显示 yy 语言版本"
• canonical 指向默认语言，避免搜索引擎收录重复内容
• 独立页（about/musics/movies/bb/friends/galleries 等）生成多语言版（/{lang}/{page}/）——界面文案走 i18n key（languages/*.yml），内容保持用户编写语言；由 standalone-page-generator.js 按排除法生成（layout ∉ {wiki, tags, categories, 404}）。导航链接（url_for_lang）对内容路径加语言前缀，指向对应语言版
• **聚合页（tag/category/archive）**按 enabled 语言生成多语言版（只生成无提示条）

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. 完成——wiki 系统自动扫描，无需配置注册

新增语言

1. preference.lang_meta 加语言代码 + name/flag/enabled: true（9 语言能力表内可直接启用）
2. 可选：设 preference.fallback_lang 为该语言（作为回落中间层）
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 名与 source/_data/{wiki}-sidebar.yml 文件名不一致
• 改了配置不生效：rm -f db.json && hexo generate（见「开发注意事项」）

附：多语言与 Wiki 速查表