☰

企业官网建设流程全解析

首页 / 建站日记 / 企业官网建设流程全解析
MkDocs Material 多语言配置实战：站点语言、语言选择器与自定义翻译
2026/9/12 13:52:17 网站建设 项目流程

MkDocs Material 多语言配置实战：站点语言、语言选择器与自定义翻译

【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material

Material for MkDocs 内置了完整的国际化（i18n）支持，为模板变量与界面标签提供了 60+ 种语言的翻译，同时允许站点搜索按语言加载对应的分词与停用词处理器。本文基于 docs/setup/changing-the-language.md 展开，结合仓库内模板与插件源码，带你完成从单语言站点到多语言站点的完整配置，并学会通过主题扩展自定义任意语言的翻译文案。

语言支持机制概述

Material for MkDocs 的语言能力分为两层：界面文案层（模板变量与按钮标签的翻译）与搜索行为层（分词、停用词与文本切分规则随语言变化）。两者都以theme.language为基准，由模板系统统一驱动。

从模板源码看，语言加载集中在 material/templates/partials/language.html：

{% import "partials/languages/" ~ config.theme.language ~ ".html" as lang %} {% import "partials/languages/en.html" as fallback %} {% macro t(key) %}{{ lang.t(key) or fallback.t(key) or key }}{% endmacro %}

这条宏定义揭示了三条关键的兜底规则：

  1. 优先查找所选语言的翻译键；
  2. 找不到时回退到默认语言en（英语是所有翻译的基准语言）；
  3. 英语也没有该键时，直接原样输出键名，保证任何情况下页面都不会因缺失翻译而崩溃。

每个语言文件都是一张由key → 翻译文案组成的映射表，例如 zh.html 中包含action.edit（"编辑此页"）、clipboard.copy（"复制"）、search.placeholder（"搜索"）等约 60 个键。同时，<html>标签的lang属性与文档方向也来自这张表（见 base.html）：

{% import "partials/language.html" as lang with context %} <html lang="{{ lang.t('language') }}" class="no-js">

设置站点语言

站点语言通过mkdocs.yml中的theme.language配置，默认值为en，自 1.12.0 版本起可用：

theme: language: zh

注意：HTML5 规范允许每个文档只能声明一种lang属性，因此 Material for MkDocs 只支持为整个项目设置一个规范语言，即每个mkdocs.yml对应一种语言。

那么如何实现多语言文档？官方推荐的做法是：每种语言建立一个独立的子目录项目，再通过下一节的「语言选择器」将这些独立项目互相链接起来。由于每个子项目拥有自己的mkdocs.yml，语言可以各不相同。

支持的语言一览

仓库中的 material/templates/partials/languages/ 目录存放了全部语言模板。以 material/overrides/hooks/translations.py 中的icons映射表为准，当前可用的语言代码包括：af、ar、az、be、bg、bn、ca、cs、cy、da、de、el、en、eo、es、et、eu、fa、fi、fr、gl、he、hi、hr、hu、hy、id、is、it、ja、ka、kn、ko、ku-IQ、lb、lt、lv、mk、mn、ms、my、nb、nl、nn、pl、pt-BR、pt、ro、ru、sa、sh、si、sk、sl、sq、sr、sv、ta、te、th、tl、tr、uk、ur、uz、vi、zh、zh-Hant、zh-TW等（完整列表可在构建站点后于语言配置页面查看）。

锚点与 slug 的注意事项

部分语言（如中文、日文等非拉丁字符语言）使用默认 slug 函数生成的锚点链接可能难以阅读。此时建议为toc扩展配置一个支持 Unicode 的 slugify 函数，详细说明见 docs/setup/extensions/python-markdown.md#+toc.slugify。

站点语言选择器

当文档以多个独立项目提供多语言版本时，可以在页头加入语言选择器，方便用户在语言之间切换。该功能自 7.0.0 版本起可用，通过extra.alternate配置：

extra: alternate: - name: English link: /en/ # (1)! lang: en - name: Deutsch link: /de/ lang: de
  1. 必须使用绝对链接。如果链接包含域名部分，则按原样使用；否则会将 mkdocs.yml 中配置的site_url的域名部分自动拼接到链接前面。

每个备选语言支持三个属性：

属性必填说明
name是显示在语言选择器中的语言名称，必须为非空字符串
link是绝对链接，可以指向其他域名或子域名，甚至不一定是 MkDocs 生成的站点
lang是ISO 639-1 语言代码，用于链接的hreflang属性，提升搜索引擎的可发现性

选择器的渲染原理

选择器的前端实现位于 material/templates/partials/alternate.html。它遍历config.extra.alternate，为每一项渲染一个带hreflang属性的链接：

{% for alt in config.extra.alternate %} <li class="md-select__item"> <a href="{{ alt.link | url }}" hreflang="{{ alt.lang }}" class="md-select__link"> {{ alt.name }} </a> </li> {% endfor %}

同时在 base.html 的<head>中，这些备选语言还会被输出为<link rel="alternate" hreflang="...">，供搜索引擎识别同一内容的不同语言版本，这对 SEO 与国际化站点的收录非常有价值。

停留当前页面（Stay on page）

自 9.7.0 版本起（标记为实验性），当两个语言版本存在路径相同的页面时，用户切换语言后会停留在当前页面，而不是跳回首页。例如：

docs.example.com/en/ -> docs.example.com/de/ docs.example.com/en/foo/ -> docs.example.com/de/foo/ docs.example.com/en/bar/ -> docs.example.com/de/bar/

该行为无需任何配置，自动生效。

文档方向（Directionality）

大多数语言按从左到右（ltr）阅读，Material for MkDocs 也完整支持从右到左（rtl）的排版。direction自 2.5.0 版本起可用，默认值会根据所选语言自动计算（例如希伯来语、阿拉伯语会得到rtl），也可以显式覆盖：

theme: direction: rtl

方向的最终取值在 base.html 中计算并写入<body>标签：

{% set direction = config.theme.direction or lang.t("direction") %} <body dir="{{ direction }}" ...>

也就是说：theme.direction未配置时，会读取语言模板中的direction翻译键（如 en.html 中定义为ltr）。你可以通过临时修改dir属性直观对比两种方向下的排版差异。

自定义翻译（Custom translations）

官方自带的翻译覆盖了绝大多数界面元素，但如果你希望把某些文案替换为更贴合自己站点的措辞，可以基于「主题扩展」机制覆写翻译。步骤如下：

  1. 在overrides目录中新建语言模板，导入目标语言与英语翻译作为兜底；
  2. 定义override宏列出要覆写的键；
  3. 重新导出t宏，按「自定义 > 目标语言 > 英语」的优先级查找。

overrides/partials/languages/custom.html：

<!-- Import translations for language and fallback --> {% import "partials/languages/de.html" as language %} {% import "partials/languages/en.html" as fallback %} <!-- (1)! --> <!-- Define custom translations --> {% macro override(key) %}{{ { "source.file.date.created": "Erstellt am", <!-- (2)! --> "source.file.date.updated": "Aktualisiert am" }[key] }}{% endmacro %} <!-- Re-export translations --> {% macro t(key) %}{{ override(key) or language.t(key) or fallback.t(key) }}{% endmacro %}
  1. en必须始终作为兜底语言，因为它是主题的默认语言。
  2. 需要覆写哪些键，请参考 material/templates/partials/languages/ 目录下对应语言的模板文件，从中选取要覆写的翻译键并在此添加。

mkdocs.yml中启用自定义语言：

theme: language: custom

设置overrides目录的方式参见 docs/customization.md#extending-the-theme。由于language.html的宏机制天然支持「目标语言缺失时回退到en」，你的自定义语言即使只覆写了几个键，其余文案也会自动回退到英语，不会出现空白。

翻译键参考

以中文翻译 zh.html 为例，界面文案键涵盖了：action.edit（编辑此页）、action.skip（跳转至）、action.view（查看本页的源代码）、announce.dismiss（不再显示此消息）、blog.*（博客系列）、clipboard.copy（复制）、clipboard.copied（已复制）、consent.*（Cookie 同意弹窗）、footer.*、header、meta.*、nav、readtime.*（阅读时间）、rss.*、search.*（搜索系列）、select.language（选择当前语言）、select.version（选择当前版本）、source*（源码相关）、tabs、toc（目录）、top（回到页面顶部）等约 60 个键。自定义翻译时，直接以这些键名作为覆写目标即可。

语言与站点搜索的联动

语言配置不仅影响界面文案，还直接决定搜索索引的默认行为。在 material/plugins/search/plugin.py 的on_config阶段，搜索插件会从语言模板中读取三个默认值：

# Retrieve default value for language if not self.config.lang: self.config.lang = [self._translate(config, "search.config.lang")] # Retrieve default value for separator if not self.config.separator: self.config.separator = self._translate(config, "search.config.separator") # Retrieve default value for pipeline if self.config.pipeline is None: self.config.pipeline = list(filter(len, re.split( r"\s*,\s*", self._translate(config, "search.config.pipeline") )))

对应的三个翻译键定义在语言模板中，例如 en.html：

  • search.config.lang:en（lunr 使用的语言代码）；
  • search.config.pipeline:stopWordFilter（英语使用停用词过滤）；
  • search.config.separator:[\s\-]+（分词分隔符）。

而 zh.html 中则为中文站点准备了专用配置：search.config.pipeline为stemmer、search.config.separator为[\s\u200b\u3000\-、。，．？！；]+（将中文标点纳入分词）。这意味着切换theme.language后，搜索默认行为会自动适配，无需手动干预。

这些默认值也可以在 material/plugins/search/config.py 定义的SearchConfig中显式覆盖（lang、separator、pipeline选项）。此外，对于中文站点，插件还支持通过jieba_dict与jieba_dict_user指定结巴分词词典，进一步提升中文检索的准确性（相关加载逻辑见 plugin.py）。

语言列表的自动生成

本文档所在页面的「支持的语言一览」并非手工维护，而是由构建钩子动态生成。仓库中的 material/overrides/hooks/translations.py 在页面构建时扫描languages/目录下的所有模板：

  1. 解析每个模板的<!-- Translations: ... -->注释提取语言名称；
  2. 以英语翻译为基准，对比其他语言，找出缺失的翻译键；
  3. 按语言名称排序渲染出语言列表。

同时该钩子还会生成「补齐缺失翻译」的模板代码，方便社区贡献者通过提交 PR 完善翻译（见 docs/contributing/adding-translations.md）。这也解释了为何语言文件顶部标注着「此文件为自动生成，请勿手动编辑」——任何新增或缺失的键都由这一钩子统一追踪。

总结

围绕theme.language，Material for MkDocs 提供了一套层层兜底、开箱即用的国际化体系：

  • 单语言站点：只需在mkdocs.yml中设置theme.language，界面文案与搜索行为即自动适配；
  • 多语言站点：为每种语言建立独立子项目，用extra.alternate配置页头语言选择器，并可叠加hreflang声明与「停留当前页面」体验；
  • 特殊排版：通过theme.direction显式控制rtl/ltr，适配阿拉伯语、希伯来语等从右到左的语言；
  • 深度定制：借助主题扩展机制创建自定义语言文件，用「自定义 > 目标语言 > 英语」的优先级覆写任意界面文案；
  • 搜索联动：分词器、停用词与分隔符默认值均随语言模板切换，中文站点还能通过 jieba 词典进一步优化分词。

【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

标签： 网站建设 企业官网 项目流程 UI设计 前端开发

热门文章

文章分类

标签云

网站建设 响应式设计 用户体验 SEO优化 前端开发 小程序 电商平台 性能优化

相关文章

您可能感兴趣的其他内容

Conductor 如何构建可治理的自适应图（Durable Adaptive Graph）？
2026/9/12 13:49:33 网站建设

Conductor 如何构建可治理的自适应图（Durable Adaptive Graph）？

Conductor 如何构建可治理的自适应图&#xff08;Durable Adaptive Graph&#xff09;&#xff1f; 【免费下载链接】conductor Conductor is an event driven agentic workflow engine providing durable and highly resilient execution engine for applications and AI Agen…...

阅读更多 →
Electron+Vue3桌面应用架构改造：从VSCode插件到原生能力落地
2026/9/12 13:43:04 网站建设

Electron+Vue3桌面应用架构改造：从VSCode插件到原生能力落地

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …...

阅读更多 →
Midscene.js 提速指南：4 个实用优化让 AI 浏览器自动化脚本跑得更快
2026/9/12 13:40:37 网站建设

Midscene.js 提速指南：4 个实用优化让 AI 浏览器自动化脚本跑得更快

Midscene.js 提速指南&#xff1a;4 个实用优化让 AI 浏览器自动化脚本跑得更快 【免费下载链接】midscene GUI Agent for E2E Testing 项目地址: https://gitcode.com/GitHub_Trending/mid/midscene Midscene.js 用自然语言驱动浏览器&#xff1a;AI 看截图、读屏幕、替…...

阅读更多 →

需要专业的网站建设服务？

联系我们获取免费的网站建设咨询和方案报价，让我们帮助您实现业务目标

立即咨询