Internationalization (i18n)

Starlight provides built-in support for multilingual sites, including routing, fallback content, and full right-to-left (RTL) language support.

Configure i18n

Tell Starlight about the languages you support by passing locales and defaultLocale to the Starlight integration:

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      // Set English as the default language for this site.
      defaultLocale: 'en',
      locales: {
        // English docs in `src/content/docs/en/`
        en: {
          label: 'English',
        },
        // Simplified Chinese docs in `src/content/docs/zh-cn/`
        'zh-cn': {
          label: '简体中文',
          lang: 'zh-CN',
        },
        // Arabic docs in `src/content/docs/ar/`
        ar: {
          label: 'العربية',
          dir: 'rtl',
        },
      },
    }),
  ],
});

Your defaultLocale will be used for fallback content and UI labels, so choose the language you are most likely to start writing content in, or already have content for.

Create a directory for each language in src/content/docs/. For example, for the configuration shown above, create the following folders:
- Directorysrc/
  - Directorycontent/
    Directorydocs/
    Directoryar/
    …
    Directoryen/
    …
    Directoryzh-cn/
    …
You can now add content files in your language directories. Use the same file name to associate pages across languages and take advantage of Starlight’s full set of i18n features, including fallback content, translation notices, and more.

For example, create ar/index.md and en/index.md to represent the homepage for Arabic and English respectively.

Use a root locale

You can use a “root” locale to serve a language without any i18n prefix in its path. For example, if English is your root locale, an English page path would look like /about instead of /en/about.

To set a root locale, use the root key in your locales config. If the root locale is also the default locale for your content, remove defaultLocale or set it to 'root'.

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      defaultLocale: 'root', // optional
      locales: {
        root: {
          label: 'English',
          lang: 'en', // lang is required for root locales
        },
        'zh-cn': {
          label: '简体中文',
          lang: 'zh-CN',
        },
      },
    }),
  ],
});

When using a root locale, keep pages for that language directly in src/content/docs/ instead of in a dedicated language folder. For example, here are the home page files for English and Chinese when using the config above:

Directorysrc/
- Directorycontent/
  - Directorydocs/
    index.md
    Directoryzh-cn/
    index.md

Monolingual sites

By default, Starlight is a monolingual (English) site. To create a single language site in another language, set it as the root in your locales config:

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      locales: {
        root: {
          label: '简体中文',
          lang: 'zh-CN',
        },
      },
    }),
  ],
});

This allows you to override Starlight’s default language without enabling other internationalization features for multi-language sites, such as the language picker.

Fallback content

Starlight expects you to create equivalent pages in all your languages. For example, if you have an en/about.md file, create an about.md for each other language you support. This allows Starlight to provide automatic fallback content for pages that have not yet been translated.

If a translation is not yet available for a language, Starlight will show readers the content for that page in the default language (set via defaultLocale). For example, if you have not yet created a French version of your About page and your default language is English, visitors to /fr/about will see the English content from /en/about with a notice that this page has not yet been translated. This helps you add content in your default language and then progressively translate it when your translators have time.

Translate the site title

By default, Starlight will use the same site title for all languages. If you need to customize the title for each locale, you can pass an object to title in Starlight’s options:

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      title: {
        en: 'My Docs',
        'zh-CN': '我的文档',
      },
      defaultLocale: 'en',
      locales: {
        en: { label: 'English' },
        'zh-cn': { label: '简体中文', lang: 'zh-CN' },
      },
    }),
  ],
});

Translate Starlight’s UI

In addition to hosting translated content files, Starlight allows you to translate the default UI strings (e.g. the “On this page” heading in the table of contents) so that your readers can experience your site entirely in the selected language.

Arabic, Chinese, Chinese (Taiwan), Czech, Danish, Dutch, English, French, Galician, German, Hebrew, Hindi, Indonesian, Italian, Japanese, Korean, Norwegian Bokmål, Persian, Polish, Portuguese, Romanian, Russian, Spanish, Swedish, Turkish, Ukrainian, and Vietnamese translated UI strings are provided out of the box, and we welcome contributions to add more default languages.

You can provide translations for additional languages you support — or override our default labels — via the i18n data collection.

Configure the i18n data collection in src/content/config.ts if it isn’t configured already:

import { defineCollection } from 'astro:content';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ schema: docsSchema() }),
  i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
};

Create a JSON file in src/content/i18n/ for each additional locale you want to provide UI translation strings for. For example, this would add translation files for Arabic and Simplified Chinese:
- Directorysrc/
  - Directorycontent/
    Directoryi18n/
    ar.json
    zh-CN.json

Add translations for the keys you want to translate to the JSON files. Translate only the values, leaving the keys in English (e.g. "search.label": "Buscar").

These are the English defaults of the existing strings Starlight ships with:

{
  "skipLink.label": "Skip to content",
  "search.label": "Search",
  "search.shortcutLabel": "(Press / to Search)",
  "search.cancelLabel": "Cancel",
  "search.devWarning": "Search is only available in production builds. \nTry building and previewing the site to test it out locally.",
  "themeSelect.accessibleLabel": "Select theme",
  "themeSelect.dark": "Dark",
  "themeSelect.light": "Light",
  "themeSelect.auto": "Auto",
  "languageSelect.accessibleLabel": "Select language",
  "menuButton.accessibleLabel": "Menu",
  "sidebarNav.accessibleLabel": "Main",
  "tableOfContents.onThisPage": "On this page",
  "tableOfContents.overview": "Overview",
  "i18n.untranslatedContent": "This content is not available in your language yet.",
  "page.editLink": "Edit page",
  "page.lastUpdated": "Last updated:",
  "page.previousLink": "Previous",
  "page.nextLink": "Next",
  "page.draft": "This content is a draft and will not be included in production builds.",
  "404.text": "Page not found. Check the URL or try using the search bar.",
  "aside.note": "Note",
  "aside.tip": "Tip",
  "aside.caution": "Caution",
  "aside.danger": "Danger",
  "fileTree.directory": "Directory"
}

Starlight’s code blocks are powered by the Expressive Code library. You can set translations for its UI strings in the same JSON file using expressiveCode keys:

{
  "expressiveCode.copyButtonCopied": "Copied!",
  "expressiveCode.copyButtonTooltip": "Copy to clipboard",
  "expressiveCode.terminalWindowFallbackTitle": "Terminal window"
}

Starlight’s search modal is powered by the Pagefind library. You can set translations for Pagefind’s UI in the same JSON file using pagefind keys:

{
  "pagefind.clear_search": "Clear",
  "pagefind.load_more": "Load more results",
  "pagefind.search_label": "Search this site",
  "pagefind.filters_label": "Filters",
  "pagefind.zero_results": "No results for [SEARCH_TERM]",
  "pagefind.many_results": "[COUNT] results for [SEARCH_TERM]",
  "pagefind.one_result": "[COUNT] result for [SEARCH_TERM]",
  "pagefind.alt_search": "No results for [SEARCH_TERM]. Showing results for [DIFFERENT_TERM] instead",
  "pagefind.search_suggestion": "No results for [SEARCH_TERM]. Try one of the following searches:",
  "pagefind.searching": "Searching for [SEARCH_TERM]..."
}

Extend translation schema

Add custom keys to your site’s translation dictionaries by setting extend in the i18nSchema() options. In the following example, a new, optional custom.label key is added to the default keys:

import { defineCollection, z } from 'astro:content';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ schema: docsSchema() }),
  i18n: defineCollection({
    type: 'data',
    schema: i18nSchema({
      extend: z.object({
        'custom.label': z.string().optional(),
      }),
    }),
  }),
};

Learn more about content collection schemas in “Defining a collection schema” in the Astro docs.