本页目录

语言与中文排版#

Sumi 的界面，包括按钮、标签、搜索面板、日期和提示框的默认标题，提供英文、简体中文和繁体中文三种语言。

mkdocs.yml

theme:
  name: sumi
  locale: zh        # en、zh（zh_CN）、zh_TW

中文排版#

当页面语言是中文、日文或韩文时，Sumi 会换用适合该文字的系统字体栈，稍微加大行高，并取消标题的字间距。所有字体都来自读者的操作系统，不会下载任何中文字体文件，页面依然轻量。

日期按语言格式化：英文显示为 November 1, 2026，中文显示为 2026年11月1日。

中文搜索#

搜索按子串匹配中日韩文字，所以搜“配置”能找到“站点配置”“配置项”等任何包含这两个字的标题和正文，不需要分词插件，也不需要服务器。按 ⌘ K 打开搜索；输入 > 切换到命令模式，命令也支持中文关键词，例如 >语言、>版本。

提示框标题#

提示框的默认标题跟随语言：> [!TIP] 在英文中显示为 Tip，在中文中显示为提示。自定义标题总是按原样显示：

> [!WARNING] 升级前请备份
> 0.x 版本之间的配置可能不兼容。

双语站点#

使用 MkDocs NG 1.11 或更高版本，一个 mkdocs.yml 就能管理所有语言。第一种语言构建在站点根目录，其他语言分别构建到 /zh/ 等子目录；每种语言都可以改写任意配置项，比如 site_name 和 nav。Sumi 的界面语言会自动跟随每种语言的代码。

mkdocs.yml

site_url: https://example.com/

languages:
  en: English
  zh:
    name: 简体中文
    site_name: 我的项目
    nav:
      - 首页: index.md
      - 指南: guide.md

译文可以和原文放在一起，比如 guide.md 旁边放 guide.zh.md；也可以给这门语言单独一个目录，写 docs_dir: docs-zh。mkdocs build 会构建所有语言，mkdocs serve 会同时预览所有语言；只想处理一种语言时加上 --language zh。

在这样的站点上，Sumi 会：

页眉的语言菜单和命令面板里的“切换到 …”命令，直接跳到另一种语言的同一页。
还没翻译的页面显示默认语言的原文，并在页面顶部提示“本页还没有翻译”。原文部分带有正确的 lang 属性，屏幕阅读器和浏览器会按原文语言朗读和处理。
每个页面都用 <link rel="alternate" hreflang="…"> 列出各语言版本，搜索引擎会给读者展示对应语言的页面。
搜索、llms.txt 和打印版都按语言分别生成。

所有配置项见 MkDocs NG 文档的 Multi-language Sites。本站和 sumi-starter 模板都是这样构建的。

如果使用较旧的 MkDocs，可以每种语言各建一个站点，再用 extra.alternate 把它们连起来，见导航。

添加新语言#

界面字符串都在一个 Python 文件 mkdocs_sumi/i18n.py 中，缺失的字符串会回退到英文。欢迎提交新语言的 Pull Request。