Skip to content

Multi-language sites

DocsForge has built-in static internationalization (i18n). Add translated files next to your default-language files and DocsForge builds a default site at the root plus one sub-site per language under /<locale>/.

Enabling the plugin

Add the material/i18n plugin to docsforge.yml and declare your languages. Exactly one language must be marked as default.

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

File naming

Translated pages use the locale suffix by default:

docs/
├── index.md          # English (default) → /index.html
├── index.zh.md       # Chinese          → /zh/index.html
├── second.md         # English          → /second/index.html
└── second.zh.md      # Chinese          → /zh/second/index.html

Translated files can live anywhere in docs/, including subdirectories:

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

Fallback pages

By default, if a translation is missing for a locale, DocsForge uses the default-language page under that locale path. Disable this with fallback_to_default: false.

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

Translate section and page titles in the language switcher and sidebar with nav_translations:

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

Language switcher

A language switcher appears automatically in the header when the i18n plugin is configured. It links to the current page in every other language and emits <link rel="alternate" hreflang="..."> tags for SEO.

Site name and description per language

Override site_name and site_description for a locale:

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

Search and sitemaps

Each locale gets its own search index and sitemap:

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

Submit the root sitemap for the default language and /<locale>/sitemap.xml for each additional language to search engines.

Limitations

  • Only the suffix file layout is supported (index.zh.md).
  • The language switcher uses the current page's alternate URLs. If a page is excluded from the default nav, its alternates are still generated as long as the source file exists.

Next steps