更改语言¶

Material for MkDocs 支持国际化（i18n），并为 60 多种语言提供模板变量和标签的翻译。此外，网站搜索可以配置为使用特定语言的词干提取器（如果可用）。

配置¶

网站语言¶

1.12.0 en

您可以在 mkdocs.yml 中设置网站语言：

theme:
  language: en # (1)!

1. HTML5 只允许为每个文档设置 单一语言，这就是为什么 Material for MkDocs 只支持为整个项目设置一个规范语言，即每个 mkdocs.yml 一个。

构建多语言文档的最简单方法是在每种语言的子文件夹中创建一个项目，然后使用 语言选择器 来相互链接这些项目。

以下语言受支持：

请注意，由于默认 slug 函数的工作方式，某些语言会生成不可读的锚链接。考虑使用 支持 Unicode 的 slug 函数。

网站语言选择器¶

7.0.0

如果您的文档有多种语言可用，可以在页眉中添加指向这些语言的语言选择器。可以通过 mkdocs.yml 定义备用语言。

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 属性，从而提高搜索引擎的可发现性。

保持在页面上¶

9.7.0

在语言之间切换时，例如，如果语言 en 和 de 包含同一路径名称的页面，用户将停留在当前页面：

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/

无需配置。

方向性¶

2.5.0

虽然许多语言是从左到右（ltr）阅读的，但 Material for MkDocs 还支持从右到左（rtl）的方向性，这由所选语言推断，但也可以通过以下方式设置：

theme:
  direction: ltr

点击一个按钮以更改方向性：

自定义¶

自定义翻译¶

如果您想自定义某种语言的某些翻译，只需按照 主题扩展 的指南，在 overrides 文件夹中创建一个新的部分。然后，将该语言的 翻译 导入作为后备，并仅调整您想要覆盖的部分：

<!-- 导入语言的翻译和后备 -->
{% import "partials/languages/de.html" as language %}
{% import "partials/languages/en.html" as fallback %} <!-- (1)! -->

<!-- 定义自定义翻译 -->
{% macro override(key) %}{{ {
  "source.file.date.created": "Erstellt am", <!-- (2)! -->
  "source.file.date.updated": "Aktualisiert am"
}[key] }}{% endmacro %}

<!-- 重新导出翻译 -->
{% macro t(key) %}{{
  override(key) or language.t(key) or fallback.t(key)
}}{% endmacro %}

theme:
  language: custom