i18n routing

[SudoCat]

Body

Summary

Localised/i18n routes, a la https://nextjs.org/docs/pages/building-your-application/routing/internationalization

Background & Motivation

Localisation is a key requirement of numerous websites. It's the big thing that comes up as a vital missing feature when discussing Astro. There are workarounds, but they lack some of niceities folks have come to expect from i18n solutions.

There is also a growing community effort across various projects, however many have to resort to odd hacks and limitations due to working purely with the integrations APIs. They also often go beyond simple localised routing, and provide opinionated solutions for how to handle localising strings.

Localisation should be a first class citizen.

The current built-in solutions have four main flaws:

• defining pages and logic in multiple pages, prone to failure
• alternatively using dynamic locales, with no validation
• no simple way of omitting prefix for a default locale
• difficult to localise injected routes

The Astro APIs have evolved to a point where many of these problems could be solved in quite a simple way.

Goals

Core

• localised routes with locale prefixes
• default locale with no prefix
• redirect to default locale if prefix enabled
• localise injected routes

Stretch

• Route translations (e.g. about -> a-propos)
• Astro locale as global (rather than parameter - could just be middleware+Astro.locals?)
• Domain support (I'm not convinced this is an Astro responsibility - seems more of a CDN/Proxy responsibility)
• Opt-in/out API extending vite-scanner-plugin, similar to prerender.
• Simple locale detection via Accept-Language header in SSR

Example

Additional configuration:

export default defineConfig({
  i18n: {
    defaultLocale: 'us',
    locales: ['us', 'fr'],
    localizeEndpoints: false,
    enableDefaultPrefix: false,
    routeTranslations: {
      fr: {
        about: 'a-propos',
        example: 'exemple',
      },
    },
  }
})

Astro global update with a Locale object availabe at Astro.locale or Astro.i18n

interface Locale {
  currentLocale: string; // e.g. us, fr, ca-fr
  activeLocales: string[];
  defaultLocale: string;
}

Experimental Implementation:

SudoCat/astro#2

[alexanderniebuhr]

Is https://starlight.astro.build/guides/i18n/ the same workaround or could be a plug-and-play solution for Astro?

[SudoCat]

The configuration and output of Starlight looks very much like what we'd want to see. However, looking at the source code shows it uses a very custom solution, which only uses a single .Astro route with [...slug], and then manually handles all of the routing itself. This would not really be suitable for many websites, especially those using SSR which may need to return custom responses.

[ematipico]

This proposal has been accepted and advanced to Stage 2. #701