Internationalization

Content directory convention

The default locale always occupies the contentDir root (no route prefix); other locales put their content in <contentDir>/<key>/, and their routes get the corresponding prefix. Config:

defineSiteConfig({
  locales: {
    en: { lang: 'en', label: 'English' },
  },
});

This site follows exactly that convention: docs/content/ is Simplified Chinese (the default), and docs/content/en/ is the English site — a full mirror of the Chinese structure (en/guide/, with the design subsection at en/guide/design/). You are reading the English mirror now:

• English home page, route /en/
• English getting started, route /en/guide/getting-started
• English pages can link back across locales: Chinese home page (this is a cross-locale demo link pointing to a Chinese page)

Rule details:

• A locale directory belongs to its own locale and never mixes into the default locale's pages
• Each locale has its own home page (the index.md in its own directory), article feed, and archives
• <html lang> takes each locale's lang value; the default locale defaults to zh-CN, overridable with the top-level lang / label

UI text

UI strings live in src/shared/i18n/; zh is the shape source of truth and en must be structurally identical, with key validation at build time. Each locale's UI text is matched by prefix against its lang (en-US → English); unregistered languages fall back to Chinese — so a default locale only needs lang: 'en' to get an English site chrome. The UI text of islands such as comments (Giscus) and the password gate uses the same table.

Switcher

The navbar provides a locale switcher showing each locale's label. Switching navigates to the current page's corresponding route in the target locale.

Recommendations

• Link between Chinese and English pages with relative paths (../en/xxx.md from a Chinese page); they are covered by dead-link checking all the same
• When the non-default locale has fewer pages, simply leave untranslated pages out of that locale's directory; the two sides are not required to match page for page