Implementing Multilingual Support in Astro Starlight with i18n Functionality

Mar 16, 2025

I’ve implemented multilingual support using Astro’s documentation template Starlight, so I’m leaving this as a record for future reference.

Starlight’s i18n Features

Starlight has built-in internationalization (i18n) features, including:

Multilingual routing
Fallback content
Full support for right-to-left (RTL) languages

These features allow for efficient construction of multilingual sites.

How to Configure i18n

Specify the supported languages in the astro.config.mjs file.

Also set the default language (for languages not included in the locales).

In my case, I supported English (en) and Japanese (ja), with English set as the default language.

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
    integrations: [
        starlight({
            title: 'My Docs',
            defaultLocale: 'en',
            locales: {
                en: {
                    label: 'English',
                },
                ja: {
                    label: '日本語',
                },
                // Add other languages
            },
        }),
    ],
});

Create directories for each language in src/content/docs/:
- Directorysrc/
  - Directorycontent/
    …
  - Directorydocs/
    Directoryen/
    …
    Directoryja/
    …
    … Other language directories

Place corresponding content files (articles) in each language directory.

Using the same file name for the same page allows you to link pages across languages.

If you want to serve a specific language without prefixing the path, you can set a root locale.

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
    integrations: [
        starlight({
            defaultLocale: 'root',
            locales: {
                root: {
                    label: '日本語',
                    lang: 'ja',
                },
                en: {
                    label: 'English',
                },
            },
        });
    ],
});

In this case, place Japanese content directly under src/content/docs/.

Directorysrc/
- Directorycontent/
  - …
- Directorydocs/
  - index.md (Japanese index.md)
  - Directoryen/
    index.md

Fallback Content

For untranslated pages, Starlight automatically displays content in the default language and notifies that it’s untranslated.

This allows for gradual translation of content.

Translating the UI

You can also translate Starlight’s default UI strings. Create JSON files for each language in src/content/i18n/ and add translations.

{
  "search.label": "Search",
  "tableOfContents.onThisPage": "On this page",
  // Other translation keys
}

For more details, refer to the Starlight documentation.