Internationalization (i18n) guide and recipe should be merged #9256
Labels
help wanted
Issues looking for someone to run with them!
improve documentation
Enhance existing documentation (e.g. add an example, improve description)
📚 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:
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.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 theundefined
value ingetStaticPaths
. 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: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:useTranslations(Astro.currentLocale)
),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
The text was updated successfully, but these errors were encountered: