Internationalization (i18n) guide and recipe should be merged

📚 Subject area/topic

Internationalization (i18n)

📋 Page(s) affected (or suggested, for new content)

https://docs.astro.build/en/guides/internationalization/
https://docs.astro.build/en/recipes/i18n/

📋 Description of content that is out-of-date or incorrect

The guide Internationalization (i18n) Routing lacks several tips that would make the Astro feature more attractive. Personally, I had given up on using Astro's i18n until I realised the following points, which made my experience so much better:

1. Every example block shows a directory structure with a folder per locale, in which you have to duplicate every .astro file:

   

   It seems inconvenient and off-putting, I can't imagine a case where I'd like to do this. The docs suggests in the text that you could create a /[locale]/ folder, but I must admit that when skimming through the page, I missed it and only saw the several examples like in the screenshot. I think a more proeminent example block with /[locale] and/or /[...locale] (see 2.) would better showcase the flexibility of the feature.

2. An info is missing from the guide and the alternative recipe (Add i18n features): What do you do when you have a defaultLocale without a prefix like /en/? (It's the default behaviour in the new feature) The answer is simple: you use /[...locale] and handle the undefined value in getStaticPaths. Pretty simple, but if an Astro beginner isn't aware of this possibility, the guide and the recipe appear to be missing critical info. Here's an example of what should be done:

   // Store this in a utils file
   export const langParams = [undefined, "fr"]
   // In every [...lang]/*.astro file
   export function getStaticPaths() {
   	return langParams.map((lang) => ({
   		params: { lang: lang },
   	}))
   }
   

3. By itself, the guide about the Astro feature does not give enough examples to get you started. You have to use /[...locale] and adapt the following tips from the recipe Add i18n features to have a working website:

   • The clever functions in Translate UI strings (you can use them with the new Astro feature like so: useTranslations(Astro.currentLocale)),
   • The LanguagePicker example is nice to have, because in Static mode, I don't think there is any other way to switch languages or to detect the client's preferred locale.

   The Astro feature is very flexible, so I don't see why people would want to not use it. That's why I feel like the recipe page is "legacy" and could be merged into the new guide for easier access to these clever tips.

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

No response

Compare the Internationalization (i18n) Routing guide and the Add i18n features recipe at the linked documentation pages. Start by mapping their existing examples and advice, then define a merged structure that retains the useful routing, translation, and language-picker guidance. Done means the relevant i18n information is consolidated without leaving the guide and recipe inconsistent.