多语言与 Wiki 系统

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

配置以 userConfig/_config.tmp.yml 的 preference 段为权威源。

阅读方式：每节都按「如何启用 → 常用选项 → 全部可调项 → 边界与冲突」展开，先看效果，再看产生该效果的对应配置，复制即可用。

1. 功能总览

用途：一套目录约定 + 一份侧栏数据，就能跑起多 Wiki、多语言的文档系统。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

1.1 如何启用

效果：建好 source/tutorial/ 目录与 source/_data/tutorial-sidebar.yml 后，访问 /tutorial/ 出现带左侧章节树的 Wiki；再放一份 source/en/tutorial/ 翻译，访问 /en/tutorial/ 得到英文版——全程没有注册步骤，目录即注册。

对应配置（主题配置，preference 段）：

preference:
  default_lang: zh-cn   # 默认语言：无前缀路径用它
  wiki:
    enable: true        # 多语言 Wiki 系统总开关

1.2 常用选项

能力一览（现有实现边界）：

① 开第二个语言

效果：语言下拉里多出该语言，且开始生成 /{lang}/ 路径与回落页。

对应配置：

preference:
  lang_meta:
    en:
      name: English
      flag: 🇬🇧
      enabled: true      # 只认这一项：true 才生效

② 指定回落中间层

效果：请求某语言但该语言无内容时，优先拿这张语言的内容顶替，而不是直接掉到默认语言。

对应配置：

preference:
  fallback_lang: en      # 须在 lang_meta enabled 中

1.3 全部可调项

1.4 边界与冲突

• 语言能力表 = lang_meta 的 keys（9 语言全支持）；生效语言 = enabled: true 的 keys——未启用的语言不生成回落页、不出现在语言下拉、不作为回落目标。
• wiki 系统自动扫描 source/{wiki}/ 目录（front-matter layout: wiki）与 source/_data/{wiki}-sidebar.yml，无需配置注册。
• 旧 preference.wiki.default_lang/langs 位置已废弃（2026-09-08 迁移，兼容期 lang-config.js 仍兜底读取）。

1.5 小结

• 最小可用：default_lang + wiki.enable
• 要多语言：在 lang_meta 里把目标语言 enabled 改 true
• 想少写翻译：靠 fallback_lang 顶替，而不是复制页面
• 新增语言后不生效：确认 enabled: true 且补了 name/flag

2. 配置详解（preference 语言段）

用途：preference 语言段是全站语言行为的唯一入口（wiki / post / 搜索共用）。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

2.1 如何启用

效果：写好这段后，站点按 zh-cn 为默认、en 为回落，语言下拉只出现这两个。

对应配置（主题配置，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

语言元数据键逐项说明：

2.2 常用选项

① 换默认语言

效果：/docs/ 前缀变成该语言，其他语言反而要加前缀。

对应配置：

preference:
  default_lang: en

② 新增语言条目

效果：语言下拉出现新选项；未放翻译文件时按回落链显示别的内容。

对应配置：

preference:
  lang_meta:
    ja:
      name: 日本語
      flag: 🇯🇵
      enabled: true

2.3 全部可调项

2.4 边界与冲突

• default_lang 不写进 URL 前缀（/docs/ 即中文），其他语言写（/en/docs/）。
• fallback_lang 必须本身是 enabled 语言，否则该层被跳过。
• lang_meta 的 name/flag 只影响展示，不影响生成；漏写时下拉缺文案。

2.5 小结

• 最小可用：default_lang + 一个 enabled: true 的语言
• 新增语言三件套：代码 + name/flag + enabled: true
• 别动 default_lang 前缀路径：已有外链会失效
• 繁简方向：调 zhDefaultEncoding

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

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

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

3.1 如何启用

效果：页面右上角偏好面板出现语言下拉（带国旗）与繁简按钮，切换后跳到当前页面对应语言版本。

对应配置：

preference:
  translate:
    enable: true

3.2 常用选项

① 语言切换

效果：面板语言下拉框列出 lang_meta 中所有语言（带国旗），切换后跳转到当前页面的对应语言版本。

对应配置：preference.lang_meta（见 §2），无独立开关。

② 繁简转换

效果：面板出现繁简按钮；点击后正文在繁体/简体间转换。

对应配置：

preference:
  translate:
    enable: true

默认方向由 zhDefaultEncoding 决定（1 繁体 / 2 简体）。

③ 记忆偏好

效果：读者上次选的语言被记住，下次访问自动按该语言加载。

对应配置：无——用户选择存入 localStorage（key wiki_lang）。

3.3 全部可调项

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

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

3.4 边界与冲突

404 / 聚合页 / 加密页语言（2026-09-27）：

• 404 页：改为客户端语言检测（单文件），按访客浏览器语言 / 本地偏好动态选择文案语言，不再按路径静态生成多份（旧 /en/404.html 等不再需要）
• archives 聚合页：全语言统一分页——不再按语言各自分页导致页数不一致；各语言版本共享同一分页结构
• 加密页语言：加密提示语 / 按钮文案随页面语言切换（hbe-bundle 兜底文案走 MATERY_I18N，2026-09-27 E7）
• 内链与运行时文案：文章内链（url_for_lang）指向对应语言版；搜索 / 弹窗等运行时文案亦 i18n 化（P0/P1）

3.5 小结

• 最小可用：开一个非默认语言即可看到下拉
• 繁简按钮不出现：检查 translate.enable
• 切了语言又跳回：本地偏好被记住，属预期行为
• 404 多语言：已是客户端检测，无需按语言建页面

4. Wiki 页面创建流程

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

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

4.1 如何启用

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

对应配置：三步文件落位（目录 + front-matter + 侧栏）。

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

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

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

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

## 全局配置

正文内容……

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

getting_started:
  overview: index.html
  install: install.html
basic_config:
  global: global.html
  multilingual: multilingual.html

④ 完成：wiki 系统自动扫描 source/tutorial/ 目录（front-matter layout: wiki + wiki: tutorial），无需配置注册。

4.2 常用选项

① 往已有 Wiki 加页面

效果：新页面出现在侧栏指定章节里，链接可达。

对应配置：source/{wiki}/xxx.md + 在 sidebar.yml 对应章节加一行（两步缺一不可）。

② 加翻译版

效果：/en/{wiki}/xxx/ 出现英文页面，语言下拉可达。

对应配置：source/en/{wiki}/xxx.md（同上 front-matter，另加 lang: en）。

4.3 全部可调项

4.4 边界与冲突

• 路径前缀（/en/...）由 page.lang 决定；翻译页漏写 lang: en 会被当作默认语言，链接指向 /docs/ 而非 /en/docs/。
• wiki 名与 _data/{wiki}-sidebar.yml 文件名必须一致，否则侧栏不渲染。
• 页面 slug 与 sidebar.yml 的 key 必须一致，否则侧栏链接 404。

4.5 小结

• 最小可用：一个 md（两个 front-matter 键）+ 一份 sidebar.yml
• 加了页面侧栏没变：忘了在 sidebar.yml 加行
• 侧栏 404：key 与文件名对不上
• 翻译页进错语言：补 lang: en

5. 侧栏数据格式

用途：定义 Wiki 左侧章节树的顺序与层级。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

5.1 如何启用

效果：侧栏按 YAML 顺序渲染出「章节 → 页面」两级树，可折叠。

对应配置（source/_data/{wiki}-sidebar.yml）：

# tutorial-sidebar.yml 示例
guides:
  layout: layout.html
  tag-plugins: tag-plugins.html
basic_config:
  global: global.html
  nav-home: nav-home.html
  post: post.html
  widgets: widgets.html
advanced_config:
  code-highlight: code-highlight.html
  multilingual: multilingual.html

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

5.2 常用选项

① 调整顺序

效果：章节/页面在侧栏中的位置变化。

对应配置：改 YAML 里的键顺序（章节顺序 = 渲染顺序；章节内页面顺序 = 文件内顺序）。

② 指向子目录页面

效果：侧栏链接指向 source/tutorial/guide/xxx.md 生成的页面。

对应配置：

guides:
  tag-plugins: guide/tag-plugins.html

5.3 全部可调项

5.4 边界与冲突

• 侧栏值必须指向真实文件路径（如 guide/tag-plugins.html 对应 source/tutorial/guide/tag-plugins.md），否则侧栏链接 404。
• 新增页面 = ① 建 md 文件 ② 在 sidebar.yml 对应章节加一行，两步缺一不可。

5.5 小结

• 最小可用：一个章节 + 一个页面
• 侧栏顺序不对：改 YAML 行序
• 链接 404：路径与真实文件不一致
• 别重复 key：同名 key 会被覆盖

6. 多语言与翻译

用途：约定翻译文件放哪、front-matter 怎么标，让系统自动关联。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

6.1 如何启用

效果：同一路径在 source/{lang}/ 下出现同名文件后，该语言的 URL 就有真实内容，不再走回落页。

对应配置（目录约定）：

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

6.2 常用选项

① Wiki 页面翻译

效果：/en/docs/setup/ 显示英文内容，侧栏链接带 /en 前缀。

对应配置（英文页面 front-matter）：

layout: wiki
wiki: docs
lang: en

② 文章翻译

效果：/en/posts/{abbrlink}/ 出现英文文章，与中文版互相关联。

对应配置（source/en/_posts/{与中文同名}.md）：

abbrlink: "相同值"
lang: en

翻译要点：

• 英文页面 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）

6.3 全部可调项

6.4 边界与冲突

• abbrlink 必须与中文原版一致，否则中英链接无法关联。abbrlink 由 hexo-abbrlink 插件在首次构建时生成并写入 front-matter（writeback: false 后不再回写，字段固定），永远不要手改已有文章的 abbrlink。
• 翻译文件路径必须与源文件同名同路径，改名即断链。
• 只翻译部分页面是允许的，缺的走回落链。

6.5 小结

• 最小可用：目录同名 + lang 标记
• 文章关联不上：查 abbrlink 是否一致
• 侧栏链接指向中文：翻译页漏写 lang: en
• 侧栏不用翻译：只维护默认语言一份

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

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

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

7.1 如何启用

效果：访问 /de/docs/setup/ 时即使 de 没有翻译，也返回兜底内容，并在页首出现提示条「de 语言不存在，显示 xx 语言版本」。

对应配置：

preference:
  default_lang: zh-cn
  fallback_lang: en
  lang_meta:
    de:
      enabled: true     # de 生效才会为它生成回落页

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

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

7.2 常用选项

① 缩短回落路径

效果：把 fallback_lang 设为默认语言，则中间层与第三层重合，直接掉到默认语言。

对应配置：

preference:
  fallback_lang: zh-cn

② 关闭某语言（不再生成回落页）

效果：该语言路径直接 404，而不是显示别语言内容。

对应配置：

preference:
  lang_meta:
    de:
      enabled: false

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

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

7.3 全部可调项

回落页的实际表现：

• 内容语言按回落链选择（_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 语言生成多语言版（只生成无提示条）

7.4 边界与冲突

• fallback_lang 不在 enabled 列表时该层被跳过，直接进 default_lang。
• 提示条只在回落页出现；真实翻译页无提示条。
• 回落页 canonical 指向默认语言，不要手动改成当前 URL。

7.5 小结

• 最小可用：default_lang + fallback_lang
• 想两级就够：fallback_lang 设成 default_lang
• 不想生成某语言：enabled: false
• 提示条语言不对：检查回落链实际命中哪一层

8. SEO（canonical / hreflang）

用途：让搜索引擎正确区分同一内容的多语言版本，避免重复收录。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

8.1 如何启用

效果：页面 <html lang> 与语言一致；有翻译时输出互指的 hreflang；回落页 canonical 指向默认语言。

对应配置：无需额外配置，由 preference 语言段 + 页面 lang 自动推导。

8.2 常用选项

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

① 确认 canonical 开关

效果：关闭后不再输出 canonical 标签（不建议）。

对应配置：

canonical:
  enable: true

8.3 全部可调项

8.4 边界与冲突

• 路径前缀（非 query string）+ hreflang + canonical 是 Google 多语言 SEO 的标准实践；sitemap 由 hexo-generator-sitemap 统一输出，Wiki 页面自动包含。
• 回落页不输出 hreflang——它没有独立内容，避免被判重复。
• 根 _config.yml 必须配置 url，否则 canonical 为空。

8.5 小结

• 默认即正确：不用手写 hreflang
• canonical 为空：查根 _config.yml 的 url
• 翻译页 lang 不对：查 front-matter lang
• 回落页别加 hreflang：会重复收录

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

新增文章翻译版

1. 在 source/en/_posts/ 下创建与中文同名的文件（如 source/en/_posts/my-post.md）
2. front-matter 保留相同 abbrlink + 添加 lang: en
3. 正文翻译为英文
4. 构建后自动生成 /en/posts/{abbrlink}/ 路径

关键：abbrlink 必须与中文原版一致，否则中英链接无法关联。abbrlink 由 hexo-abbrlink 插件在首次构建时生成并写入 front-matter（writeback: false 后不再回写，字段固定），永远不要手改已有文章的 abbrlink。

常见排查

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

10. Wiki 整体加密配置

用途：加密整个 Wiki 的内容列与右侧目录；左侧导航保留可见（导航相当于标题，泄漏可接受）。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

10.1 如何启用

效果：进入该 Wiki 任意页面，正文与右侧 TOC 被遮罩并要求输入密码，左侧导航正常显示。

对应配置（source/_data/{wiki}-sidebar.yml 顶层键）：

encrypt_password: "{{PASSWORD}}"

声明位置：source/_data/{wiki}-sidebar.yml 顶层键——与 getting_started 等导航章节键并列，2026-09-07 统一 encrypt_ 前缀以示区分。

10.2 常用选项

① 改提示文案

效果：密码框上方提示语变化。

对应配置：

encrypt_message: "该栏目已加密，请输入密码"

② 改错误提示

效果：密码错误时显示自定义文案。

对应配置：

encrypt_wpm: "密码不对，请重试"

③ 改输入框与按钮文案

效果：输入框占位符与解密按钮文字变化。

对应配置：

encrypt_placeholder: "请输入密码"
encrypt_button_text: "解锁"

10.3 全部可调项

密码在 sidebar 数据中用 {{PASSWORD}} 占位，真实值不要提交进仓库。

10.4 边界与冲突

行为（依据 themes/matery/layout/wiki.ejs 与 themes/matery/source/js/wiki.js）：

• 加密范围：仅内容列（encryptHtml(page.content, …)）与右侧 TOC（#wiki-toc-aside 加 wiki-toc-encrypted 类）；左侧 wiki-sidebar 导航始终渲染、可见
• 加密参数：stableSalt: true + storageKey: 'wiki.' + page.wiki——同一 Wiki 的多页面共用同一个 localStorage 缓存键
• 解密后重建 TOC：前端解密成功触发 hexo-blog-decrypt 事件 → wiki.js 移除 wiki-toc-encrypted 类、内容列 l10→l8，先 tocbot.destroy() 再 tocbot.init()——加密态下正文标题不可读，TOC 必须等解密后重建

10.5 小结

• 最小可用：sidebar.yml 顶层一行 encrypt_password
• 只想改文案：加 encrypt_message / encrypt_wpm
• 导航也会泄漏：这是设计取舍，导航标题不做加密
• TOC 解密后乱：依赖 hexo-blog-decrypt 事件重建，勿自建 TOC

附：多语言与 Wiki 速查表