On this page

Languages#

Sumi's interface — buttons, labels, the search palette, dates and default callout titles — is available in English, Simplified Chinese and Traditional Chinese.

mkdocs.yml

theme:
  name: sumi
  locale: zh        # en, zh (zh_CN), zh_TW

CJK typography#

When the page language is Chinese, Japanese or Korean, Sumi uses a system font stack suited to the script, a slightly larger line height and no letter-spacing on headings. Search matches CJK text by substring (see Search).

Callout titles#

Default callout titles follow the language: > [!TIP] is titled Tip in English and 提示 in Chinese. A custom title is always used as written.

Multilingual sites#

With MkDocs NG 1.11 or later, one mkdocs.yml holds every language. The first language is built at the root of the site and the others into /zh/ and so on; each one can change any setting, such as site_name or nav. Sumi takes its interface language from each language's code.

mkdocs.yml

site_url: https://example.com/

languages:
  en: English
  zh:
    name: 简体中文
    site_name: 我的项目
    nav:
      - 首页: index.md
      - 指南: guide.md

Put each translation next to the original page, as guide.zh.md next to guide.md, or give the language a folder of its own with docs_dir: docs-zh. mkdocs build builds every language and mkdocs serve previews them all; add --language zh to work on one.

What Sumi does on such a site:

The language menu in the header, and the Switch to … commands in the command palette, link to the same page in the other language.
A page that isn't translated yet is shown in the default language, with a note at the top that says so. Its text is marked with its own lang, so screen readers and browsers read it in the right language.
Each page lists its translations with <link rel="alternate" hreflang="…">, so search engines show readers the version in their language.
Search, llms.txt and the print edition are built for each language.

See Multi-language Sites in the MkDocs NG docs for all the settings. This site and sumi-starter are built this way.

With an older MkDocs, build one site per language and link them with extra.alternate; see Navigation.

Adding a language#

Interface strings live in one Python file, mkdocs_sumi/i18n.py. A missing string falls back to English. Pull requests for new languages are welcome.