# Languages

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

```yaml title="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](search.md#chinese-japanese-and-korean)).

## 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.

```yaml title="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](https://mkdocs-ng.org/user-guide/multi-language-sites/) in the MkDocs NG docs for all the settings. This site and [sumi-starter](https://github.com/mkdocs-ng/sumi-starter) are built this way.

With an older MkDocs, build one site per language and link them with `extra.alternate`; see [Navigation](navigation.md#languages).

## 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.