Build a Manual with Starlight #5: Multilingual and Versioning

Framework Starlight Documentation Static Site
1 min read

In #4 we put the docs on the internet. As your user base grows, two requests follow. One is that people want to read the docs in another language; the other is that they want the old docs kept around for those still using an older product version. This post covers both.

This series is Build a Manual with Starlight, in six parts.

  • #1 From Install to Your First Doc
  • #2 Sidebar and Search — Structuring Your Docs
  • #3 Writing Content — Code Blocks, Mermaid, asides
  • #4 Deploy to Cloudflare Pages and Connect a Domain
  • #5 Multilingual and Versioning ← this post
  • #6 Maintenance — Search, Accessibility, Docs Culture

In this post we cover adding languages and managing versions.

Adding Languages — Built-in i18n #

Multilingual support is a feature Starlight has built in. You declare the languages in the Starlight integration in astro.config.mjs.

astro.config.mjs — multilingual 
starlight({
  title: 'Product Manual',
  defaultLocale: 'ko',
  locales: {
    ko: { label: '한국어' },
    en: { label: 'English', lang: 'en' },
  },
})

You place the docs under per-language folders with the same name.

Placing translation files 
src/content/docs/
├─ ko/
│  └─ guides/install.md   # Korean
└─ en/
   └─ guides/install.md   # English

Placed this way, Starlight recognizes the two as translations of the same page and automatically shows a language switcher at the top. Untranslated pages fall back to the default language, so the site does not break even if you do not translate everything at once.

Versioning — With a Plugin #

Here, frankly, there is a point to make. Starlight core has no versioning feature. This is where it differs from Docusaurus, which has versioning built in. Instead, you add it with a community plugin like starlight-versions.

Install the versions plugin 
npm install starlight-versions

Register the plugin in the Starlight integration’s plugins, and you can freeze the current docs as a version and attach a version picker at the top. If your versioning needs are strong, it is worth comparing with Docusaurus, which has the same feature in core. The differences in how each tool handles versioning are laid out in the Documentation Site Generators Compared post.

Wrapping Up #

In this post we added languages with built-in i18n and added versioning with a plugin. We saw that multilingual support is handled easily, while versioning takes one extra step but can be filled in with a plugin.

The next post is the last one. We will close the series by going over the operations perspective: search, accessibility, and the habits that keep docs alive for the long run.

X