help with i18n | Astro Lounge | Page 1

shy kiln Jun 18, 2025, 3:03 PM

#

How to add more languages in the starlight docs?

limpid crownBOT Jun 18, 2025, 3:03 PM

#

Hi @shy kiln. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

#

To add more languages to your Starlight docs site, follow these steps:

Update your Starlight configuration
In your astro.config.mjs, add the new languages to the locales object and, if needed, update the defaultLocale. Each language should have a unique key (e.g., fr for French) and a label. You can also specify lang and dir (for right-to-left languages):

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      defaultLocale: 'en',
      locales: {
        en: { label: 'English' },
        fr: { label: 'Français', lang: 'fr' },
        'zh-cn': { label: '简体中文', lang: 'zh-CN' },
        // Add more languages here
      },
    }),
  ],
});

See more in the Starlight i18n guide.

Create content folders for each language
In your project, under src/content/docs/, create a folder for each language key you added. For example:
```
src/
  content/
    docs/
      en/
      fr/
      zh-cn/
```
Add your translated Markdown files to the appropriate folders. Use the same filenames across languages to enable fallback and translation notices.
(Optional) Add or override UI translations
If you want to translate Starlight’s UI (like navigation labels), create JSON files in src/content/i18n/ for each language and provide the necessary translations. For example, add fr.json for French UI strings.
See how to translate Starlight’s UI.

#

(Optional) Translate the site title
You can provide a localized site title by passing an object to the title option:
```
title: {
  en: 'My Docs',
  fr: 'Mes Docs',
  'zh-CN': '我的文档',
}
```
See how to translate the site title.

That’s it! Starlight will now serve your documentation in the additional languages you’ve configured, with automatic fallback to the default language if a translation is missing. For more advanced scenarios, refer to the Starlight Internationalization Guide.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@shy kiln Kapa.ai is still learning and improving, please let me know how I did by reacting below.

shy kiln Jun 18, 2025, 3:06 PM

#

@limpid crown the language switcher still doesnt appeaar in my starlight docs

limpid crownBOT Jun 18, 2025, 3:06 PM

#

Let me check the knowledge base for you again. One moment! :books:

#

If the language switcher does not appear in your Starlight docs, please check the following based on the official documentation:

Multiple Locales Required
The language switcher will only appear if you have configured more than one locale in your Starlight integration. Make sure your astro.config.mjs includes at least two entries in the locales object:
```
starlight({
  locales: {
    en: { label: 'English' },
    fr: { label: 'Français' },
  },
  defaultLocale: 'en',
})
```
See: Configure i18n
Correct Folder Structure
Ensure you have created a directory for each language in src/content/docs/ (e.g., en/, fr/) and that each contains at least one content file. This is necessary for Starlight to recognize the locales and enable the switcher.
Root Locale Special Case
If you are using a root locale (i.e., serving one language at the root path without a language prefix), the language switcher will only appear if you have at least one additional locale configured. For a monolingual site (only root), the switcher will not be shown, which is expected behavior see: Use a root locale.
Check for Typos and Consistency
The keys in your locales config must match the folder names in src/content/docs/ exactly (case-sensitive).

#

If you have followed all these steps and the language switcher still does not appear, the knowledge sources do not provide further troubleshooting steps. In that case, you may want to consult the Starlight troubleshooting guide or check for known issues on GitHub or the Astro Discord community.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@shy kiln Kapa.ai is still learning and improving, please let me know how I did by reacting below.

shy kiln Jun 18, 2025, 3:24 PM

#

@limpid crown the warning banner when the docs arent translated yet was removed?

limpid crownBOT Jun 18, 2025, 3:24 PM

#

Let me check the knowledge base for you again. One moment! :books:

#

No, the warning banner for untranslated docs has not been removed. According to the Starlight documentation, when a translation is not available for a language, Starlight will show the content from the default language along with a notice that the page has not yet been translated. This helps users know they are viewing fallback content see: Fallback content.

Additionally, the default component responsible for this notice is called FallbackContentNotice, which is still listed in the overrides reference. This component is displayed to users on pages where a translation for the current language is not available, and it is only used on multilingual sites see: FallbackContentNotice.

So, the warning banner is still part of Starlight’s multilingual support.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@shy kiln Kapa.ai is still learning and improving, please let me know how I did by reacting below.

shy kiln Jun 18, 2025, 3:32 PM

#

@limpid crown it doesnt show any banner

limpid crownBOT Jun 18, 2025, 3:32 PM

#

Let me check the knowledge base for you again. One moment! :books:

#

If the warning banner for untranslated docs (the fallback content notice) is not showing in your Starlight site, but you expect it to, here are the relevant facts from the documentation:

Starlight is designed to show a notice when a translation is missing and fallback content is displayed. This is handled by the FallbackContentNotice component, which is only used on multilingual sites see: FallbackContentNotice.
The documentation states:

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 see: Fallback content.

However, the knowledge sources do not provide troubleshooting steps if the banner does not appear as expected. They do not mention any configuration option to disable this banner, nor do they indicate that it has been removed.

If you have confirmed that:

You have more than one locale configured,
You are visiting a page in a non-default locale that does not have a translation,
And you are not seeing the fallback notice,

#

then the knowledge sources do not contain enough information to explain why the banner is missing. You may want to check for custom overrides of the `FallbackContentNotice` component or consult the Starlight troubleshooting guide for further help.

#help with i18n

That’s it! Starlight will now serve your documentation in the additional languages you’ve configured, with automatic fallback to the default language if a translation is missing. For more advanced scenarios, refer to the Starlight Internationalization Guide.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

If you have followed all these steps and the language switcher still does not appear, the knowledge sources do not provide further troubleshooting steps. In that case, you may want to consult the Starlight troubleshooting guide or check for known issues on GitHub or the Astro Discord community.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

So, the warning banner is still part of Starlight’s multilingual support.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

then the knowledge sources do not contain enough information to explain why the banner is missing. You may want to check for custom overrides of the FallbackContentNotice component or consult the Starlight troubleshooting guide for further help.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

then the knowledge sources do not contain enough information to explain why the banner is missing. You may want to check for custom overrides of the `FallbackContentNotice` component or consult the Starlight troubleshooting guide for further help.