Update i18n recipe and guide for better integration

[casungo]

Description

This PR addresses issue #9256 by updating the internationalization (i18n) recipe and guide to improve clarity, integrate modern Astro API features, and ensure they complement each other effectively.

Related issues & labels

• Closes Internationalization (i18n) guide and recipe should be merged #9256
• Suggested label: improve or update documentation

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	66b2ec7
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/68334170aa4a220008922e0b
😎 Deploy Preview	https://deploy-preview-11768--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/guides/internationalization.mdx	Source changed, localizations will be marked as outdated.
en/recipes/i18n.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[casungo]

Draft for now because I need to finish the last 2 recipes. But everything else is finished, reviews are welcome!

[sarah11918]

Hi @casungo ! This is still marked as a draft, and I'm not sure whether you considered this finished, but it's been hanging around for a while and I do have some initial feedback here:

The i18n guide page

The original issue had to do with our recipe not using the i18n API at all, which people found (understandably!) confusing, and which meant that our recipe had to build some strategies for things that actually already exist if you just use the API.

I don't think the i18n guide page needed to change at all to address the issue, and I don't think we should consider making any changes to it at this time. There is already a lot going on here, and even though every page can always be improved, I think that's a separate issue and will only take more time and effort when we really need to focus on the recipe! 😄

The i18n Recipe

I think there are some very specific changes you've made here that incorporate the newer i18n routing features well! Specifically, I think the steps in "Translate UI strings" and "Let users switch between languages" are now better because we can determine the current locale.

I don't think very much before those steps in this guide should change though. What makes a recipe easy to follow is that it is very simple steps, with explicit instructions (few or no choices to make) and very little extra information like explanation. I think a lot of the earlier content you've added makes the steps less easy to follow and tries to "teach" about what the API is, and had some "if you're doing this" which a recipe should not have. A recipe should be opinionated and make a choice so that the readers have something to follow (and so WE know what the reader has already done so we can confidently tell them what to do next, and not worry that they chose a different option).

So, here's what I think helpful changes from the original guide would be:

• I think we put the entire basic i18n routing config that we are starting with in the prerequisites section, shown as a code block! I don't think this should be in a tip, I think it should be a proper prerequisite section that says "This recipe uses an Astro project configured with the following i18n routing." The example config should list all the languages in use and whatever other config options we want to assume so that we can build the rest of the example out knowing that someone can follow it exactly and have something that works at the end. For example, if we know what value we expect for prefixDefaultLocale, what our default language is, and what all the supported languages are, then we know exactly what our folder structure should look like.
• Update the original recipe instructions/code examples for "set up pages for each language" and "using collections for translated content" only as necessary for the example i18n config you have chosen to use. Do not add any extra information/steps because the level of detail in the original is mostly what we are going for. We are not trying to explain anything here, only give instructions to be followed. (But of course, modify as necessary so that we are telling them to do the proper thing based on the code they need to write/add!)
• By the time you get to "Translate UI strings" and "Let users switch between languages", the instructions you already have here are probably very close to, if not exactly what's needed! Just make sure they match with the config you started with, but you've already done a great job here!
• I think we can delete entirely "hide default language in the URL" because instead of this being a thing we have to show people how to do here, we now have a config option to swap this! And, I don't think we need to show "changing" it, because we have the i18n guide and API reference for explaining the effects of setting prefixDefaultLocale to either true or false.
• "Translating URLs" is marked as todo. Is this "Translate Routes" from the original? This seems to use a function useTranslatedPath that was used in the section that I think we can delete. So, i'm guessing that this "Translate Routes" can't just be copied/used as is. Do we still even need it?
• "Dynamic language routing with [locale]" is also shown as to-do, but from the original issue, you'll notice that Armand warned that showing this option could be problematic as it will really depend on someone's project, and whether it's static or on-demand rendered. It also doesn't really showcase incorporating the i18n API as much as it focuses on dynamic routing, so I think we can just not include this new section (and maybe consider adding it later) as out of scope for simply "updating this content" with our newer APIs. I think the main goal to accomplish first is to not confuse people when they see our i18n recipe doesn't use anything from our i18n guide page 😅

So if you are still available at some point (no rush of course! everything is when ever you can!), I think those are the changes that will really help the i18n recipe!