Configuring Multilingual Support

Overview

Multilingual documentation dramatically expands your audience reach. Starlight provides built-in i18n support with locale-based routing. This section covers how to set up and manage multilingual content.

Q&A

Q: How do I enable multilingual support?

A: Add locale configuration to astro.config.mjs:

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      defaultLocale: 'root',
      locales: {
        root: { label: 'English', lang: 'en' },
        zh: { label: '中文', lang: 'zh-CN' },
        ja: { label: '日本語', lang: 'ja' },
      },
      sidebar: [
        {
          label: 'Getting Started',
          translations: { 'zh-CN': '快速开始', 'ja': 'はじめに' },
          items: [{ autogenerate: { directory: 'getting-started' } }],
        },
      ],
    }),
  ],
});

Key points:

root is the default locale (served at /), other locales get prefixed paths (/zh/, /ja/)
label is shown in the language switcher dropdown
lang sets the HTML lang attribute for accessibility and SEO
translations on sidebar items provide localized labels

Q: Where do I put translated content?

A: Translated content goes in locale-prefixed directories:

src/content/docs/
├── index.md                        # English homepage (/)
├── getting-started/
│   └── installation.md            # English: /getting-started/installation/
└── zh/
    ├── index.md                    # Chinese homepage (/zh/)
    └── getting-started/
        └── installation.md        # Chinese: /zh/getting-started/installation/

Starlight automatically links the English and Chinese versions together in the language switcher.

Q: How does Starlight handle UI translations?

A: Starlight’s built-in UI strings (like “Search”, “Skip to content”, “Previous”, “Next”) are automatically translated for supported languages. You can also override specific strings:

starlight({
  locales: {
    root: { label: 'English', lang: 'en' },
    zh: { label: '中文', lang: 'zh-CN' },
  },
  // Override specific UI strings if needed
  customCss: ['./src/styles/custom.css'],
})

For sidebar labels, use the translations property as shown above.

Q: What if a page doesn’t have a translation yet?

A: Starlight handles missing translations gracefully:

If a translated page doesn’t exist, the language switcher still shows the locale but navigates to the fallback (default locale) page
You can set up a fallback strategy in your content workflow

Recommended approach: use a content migration script (like the one in this project) that detects missing translations and generates placeholder pages:

## English version in progress

This page is not available in English yet.

- View Chinese: [/zh/getting-started/installation/](/zh/getting-started/installation/)

Q: How do I manage content synchronization across languages?

A: There are three common strategies:

Strategy	Description	Best For
Single source	Write in one language, translate via script or service	Small teams, clear truth source
Parallel editing	Each language maintained independently	Large teams with language specialists
Hybrid	Single source + manual override for important pages	Growing teams, quality-critical content

Our approach: We use a “single source” model where Chinese is the truth source. A migration script (scripts/migrate-content.mjs) processes source directories, generates frontmatter, and syncs content to the Starlight content directory. English versions are either manually translated or show placeholder pages.

A: Use the translations property on sidebar groups:

sidebar: [
  {
    label: 'Introduction',
    translations: {
      'zh-CN': '引言与预备知识',
      'ja': 'はじめに',
    },
    items: [{ autogenerate: { directory: 'introduction' } }],
  },
]

The page titles (from frontmatter) are automatically used for sidebar items generated by autogenerate.

Building a commercial IoT product?

We provide ESP32 ODM design-to-manufacturing services. From prototype to production — the team behind this tutorial can build it with you.

Talk to us →

Configuring Multilingual Support