语言修改¶

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

配置¶

站点语言¶

可以通过 mkdocs.yml 设置站点语言：

theme:
  language: en # (1)!

1、 HTML5 仅允许为每个文档设置一种语言，因此 MkDocs For Material 主题仅支持为整个项目设置一个规范语言，即每个 mkdocs.yml 文件只能设置一个语言。
构建多语言文档的最简单方法是为每种语言在子文件夹中创建一个项目，然后使用语言选择器将这些项目相互链接。

支持以下语言：

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

站点语言选择¶

如果您的文档提供多种语言版本，可以在页眉中添加一个指向这些语言的语言选择器。可以通过 mkdocs.yml 文件定义其他语言。

extra:
  alternate:
    - name: English
      link: /en/ # (1)!
      lang: en
    - name: Deutsch
      link: /de/
      lang: de

1、请注意，这必须是一个绝对链接。如果它包含域名部分，则会按定义使用。否则，会将 mkdocs.yml 中设置的site_url的域名部分添加到链接的前面。

每个备用语言具有以下属性可供选择：

此属性的值在语言选择器中用作语言的名称，并且必须设置为非空字符串。

此属性必须设置为绝对链接，该链接也可以指向另一个域或子域，这些域或子域不一定是由 MkDocs 生成的。

此属性必须包含ISO 639-1语言代码，并用于链接的 hreflang 属性，以提高搜索引擎的发现能力。

留在当前页面¶

Insiders 改善了在不同语言之间切换时的用户体验，例如，如果语言 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/

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

无需进行任何配置。我们正在努力改进 2024 年的多语言支持，包括让未来的语言切换更加无缝。

方向性¶

虽然许多语言都是从左到右（ltr）阅读的，但 Material-for-MkDocs 主题也支持从右到左（rtl）的方向性，这是根据所选语言推断出来的，但也可以通过以下方式设置

theme:
  direction: ltr

点击下面的标题切换阅读方向

自定义¶

自定义翻译¶

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

<!-- 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 %}

theme:
  language: custom