跳转至

多语言站点

DocsForge 内置静态国际化（i18n）。在默认语言文件旁边添加翻译文件，DocsForge 会在根目录构建默认站点，并为每种语言在 /<locale>/ 下构建子站点。

启用插件

在 docsforge.yml 中添加 material/i18n 插件并声明语言。必须且只能有一种语言被标记为 default。

plugins:
  - material/i18n:
      languages:
        - locale: en
          name: English
          default: true
        - locale: zh
          name: 中文

文件命名

翻译页面默认使用语言后缀：

docs/
├── index.md          # 英文（默认） → /index.html
├── index.zh.md       # 中文         → /zh/index.html
├── second.md         # 英文         → /second/index.html
└── second.zh.md      # 中文         → /zh/second/index.html

翻译文件可以放在 docs/ 的任何位置，包括子目录：

docs/
└── guide/
    ├── intro.md
    └── intro.zh.md

回退页面

默认情况下，如果某个语言缺少翻译，DocsForge 会在该语言路径下使用默认语言页面。可通过 fallback_to_default: false 禁用。

plugins:
  - material/i18n:
      fallback_to_default: false
      languages:
        - locale: en
          name: English
          default: true
        - locale: zh
          name: 中文

导航翻译

使用 nav_translations 翻译语言切换器和侧边栏中的章节与页面标题：

plugins:
  - material/i18n:
      languages:
        - locale: en
          name: English
          default: true
        - locale: zh
          name: 中文
          nav_translations:
            Home: 首页
            "Getting started": 入门
            Installation: 安装

语言切换器

配置 i18n 插件后，页眉会自动显示语言切换器。它会链接到当前页面的其他语言版本，并生成 <link rel="alternate" hreflang="..."> 标签以优化 SEO。

每种语言的站点名称和描述

为特定语言覆盖 site_name 和 site_description：

plugins:
  - material/i18n:
      languages:
        - locale: en
          name: English
          default: true
          site_name: My Project
        - locale: zh
          name: 中文
          site_name: 我的项目
          site_description: 中文文档

搜索和站点地图

每种语言都有自己的搜索索引和站点地图：

site/
├── search/search_index.json
├── sitemap.xml
├── sitemap.xml.gz
└── zh/
    ├── search/search_index.json
    ├── sitemap.xml
    └── sitemap.xml.gz

将默认语言的根站点地图提交给搜索引擎，并为每种附加语言提交 /<locale>/sitemap.xml。

限制

  • 仅支持 suffix 文件布局（index.zh.md）。
  • 语言切换器使用当前页面的替代 URL。如果页面被排除在默认导航之外，只要源文件存在，仍会生成其替代 URL。

下一步