# 语言与中文排版

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

```yaml title="mkdocs.yml"
theme:
  name: sumi
  locale: zh        # en、zh（zh_CN）、zh_TW
```

## 中文排版

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

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

## 中文搜索

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

## 提示框标题

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

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

## 双语站点

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

```yaml title="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](https://mkdocs-ng.org/user-guide/multi-language-sites/)。本站和 [sumi-starter](https://github.com/mkdocs-ng/sumi-starter) 模板都是这样构建的。

如果使用较旧的 MkDocs，可以每种语言各建一个站点，再用 `extra.alternate` 把它们连起来，见[导航](https://sumi.mkdocs-ng.org/docs/customize/navigation/#languages)。

## 添加新语言

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