How does Starlight implement root English pages with fallbacks but no redirect files?

[asieradzk]

I'm trying to replicate Starlight's i18n routing approach in my own Astro project, specifically:

1. English pages at root path (no /en/ prefix)
2. Other languages in their own directories (e.g., /fr/page/)
3. Fallback to English for missing translations
4. No redirect HTML files (which break Pagefind indexing)

I've seen that Starlight achieves this exact setup, but I can't figure out how to implement it in my own config. When I try:

routing: {
  prefixDefaultLocale: true,  
  redirectToDefaultLocale: false 
},
fallback: {
  'fr': 'en'
}

The fallbacks try to point to /en/page/ which doesn't exist since my English pages are at root.

What's the internal mechanism Starlight uses to accomplish this routing pattern while maintaining compatibility with Pagefind?

Just to be clear, this is the behaviour that I would like (which doesnt compile not a valid astro config):

routing: {
  prefixDefaultLocale: false,  
  redirectToDefaultLocale: false 
},
fallback: {
  'fr': 'en'
}

And I already have duplicate /page/index.astro /[lang]/page/index.astro just to be sure! If I dont set the redirectToDefaultLocale: false the generated /[lang]/page/index.html will appear with baked-in redirect which breaks pagefind indexing.

[HiDeoo]

👋

Starlight does not use the fallback mechanism available with Astro’s internationalization (i18n) features. This is visible when we generate the configuration for Astro i18n, you can see that the fallback option is not set.

What happens in the case of Starlight, which is built on top of content collections, would be similar to something like:

1. Query all entries in the docs content collection
2. Check if the website is a multilingual website
3. Grab a list of all pages in the default locale
4. Loop over all other locales configured
5. Get all pages for the current locale
6. Loop over all pages in the default locale
7. Check if the page in the default locale we are looping over exists in the current locale
   • If yes: Stop here and continue to the next page
   • If no: Manually add a route to render for the missing page in the current locale with the content from the default locale

This is obviously quite a bit of steps, and it's only something we can do because Starlight content pages are built on top of Astro's content collections and we have control over pages that are rendered.

Afaik, getting the exact same behavior with Astro's i18n features is not supported, as fallbacks only have 2 possible fallbackTypes:

• redirect which is what you want to avoid
• rewrite which would serve a page in a different language without redirecting the browser to a different page but would change the language of your UI.

[asieradzk]

Redirect is fine for fallback in my case, I only want to not generate redirects for pages that do exists.

With redirectToDefaultLocale: true, the redirects are also generated even when page is available in the [slug] language, it just makes files for hopping around: very annoying and breaks pagefind indexing.

[HiDeoo]

If I'm not missing anything, the following config seems to provide the desired behavior:

i18n: {
  locales: ["en", "fr"],
  defaultLocale: "en",
  fallback: {
    fr: "en",
  },
  routing: {
    fallbackType: "redirect",
  },
},

With the following file structure:

src/
  pages/
    index.astro
    about.astro
    fr/
      index.astro

Visiting /, /about/, or /fr/ shows the expected content without any redirects. However, visiting /fr/about/ redirects to /about/ with a 302.

Switching the fallbackType to rewrite and visiting /fr/about shows the content of /about/ without any redirects.

If it's not the case for you, maybe it's an issue with Astro itself or in a specific case and I would suggest opening an issue on the Astro repo with a small reproduction of the issue.

[asieradzk]

That is so bizare. Did you inspect the generated .index files? For me they contain redirects unless I specify redirectToDefaultLocale: false then they work fine but this disallows me from having en as root path.

[HiDeoo]

Yeah, for me the redirect is only present for fr/about/ that's a why a small reproduction on the Astro repo may be the best solution:

[asieradzk]

My structure was a bit different but I was able to reproduce this behaviour here:
https://github.com/asieradzk/i18ntest

Output of my build