Update i18n recipe to use built-in routing

[hugosmoreira]

Description (required)

Updates the i18n recipe into a runnable English/French example using Astro's built-in routing. It adds the content collection loader, preserves translated paths (/en/about/ and /fr/a-propos/), and connects the navigation, language picker, layouts, and localized blog content. Both static and server-rendered blog examples are included.

The example uses a prefix for every locale. It does not attempt the broader guide/recipe consolidation or all routing configurations discussed in #9256.

• Live static demo
• Demo source

Verification

Rechecked on September 19. All 15 static recipe files match the runnable demo. The demo passes 28 static-output assertions and the server-rendered alternative passes 48 HTTP assertions, covering localized pages, reciprocal language links, redirects, and missing entries.

The docs PR integrated with current main (5531ce0a7d5f) passes type checking, ESLint, slug checks, and the full 6,373-page build/link check on Windows with Node 24.18.0 and pnpm 11.1.2. Type checking reports no errors or warnings and one hint in an unchanged component. The build uses the repository's SKIP_OG=true link-check command.

The old PR base references an unavailable Lunaria preview package; the tested integration uses main's released dependency instead, without dependency edits in this PR. An initial Windows file-opening error during the build did not recur on retry; unchanged main also passed the build and link check.

References

• Related to Internationalization (i18n) guide and recipe should be merged #9256

[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/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.

[astrobot-houston]

Hello! Thank you for opening your first PR to Astro’s Docs! 🎉

Here’s what will happen next:

1. Our GitHub bots will run to check your changes.
   If they spot any broken links you will see some error messages on this PR.
   Don’t hesitate to ask any questions if you’re not sure what these mean!

2. In a few minutes, you’ll be able to see a preview of your changes on Netlify 🥳.

3. One or more of our maintainers will take a look and may ask you to make changes.
   We try to be responsive, but don’t worry if this takes a few days.

[github-actions]

Preview deployment

✅ Deployment complete!

• Latest commit: 8e41e1c
• Preview: https://docs-update-i18n-recipe-api.previews.docs.astro.build
• Workflow run: View logs

[ArmandPhilippot]

Hi @hugosmoreira,

First thanks for willing to help but...

We have a PR template so that contributors use it, not so an AI can replace it with whatever it pleases. The fact that your AI runs git diff --check is not important information for maintainers. Explaining what you changed and why you made those changes is more useful.

Also, have you tested your changes, or everything is AI-generated?

Your AI claims it's complete, but it doesn't seem to me. For example:

• we still miss a loader
• you removed the "Translate routes" section, but now the recipe no longer explains to users how to translate them... The current recipe do not translate any slugs.

If some info was missing in the previous recipe, it should be fixed. If we remove a section because there is another way to handle it, we should make sure the recipe still show how to achieve that.

The live recipe has several gaps. Using Astro built-in APIs is nice but I'm not sure that's enough to close that issue.

The purpose of a recipe is to provide step-by-step instructions to achieve a goal that users can adapt to their project. Looking at the end result, this just show users they can switch between two languages:

A real demo of the result achieved with this recipe would be more useful, I think...

[hugosmoreira]

Thanks for the direct feedback. You're right: I replaced the PR template and described the recipe as complete without verifying the exact instructions end to end.

I used an AI assistant to help draft the change, but I'm responsible for reviewing and testing what I submit. I've returned the PR to draft. Before requesting another review, I'll restore the template, add the missing loader, preserve translated-slug support, and follow the complete recipe in a clean project with a runnable reproduction.

I'll report only the exact behavior I verified with the revision.

[hugosmoreira]

Thanks for the direct feedback. You were right: the previous revision and PR description overstated what had actually been verified.

Codex assisted with the implementation. For this revision, I reviewed the final one-file diff and kept only claims backed by actual checks. The recipe now includes the missing content loader, preserves translated slugs with an explicit route map (/en/about/ ↔ /fr/a-propos/), connects the navigation and language picker to the demonstrated pages, and includes localized content examples for static and SSR rendering.

I generated standalone fixtures from the final snippets and tested the static output, SSR development-server responses, root redirect, localized routes/content/dates, reciprocal language links, and the missing-loader and raw-path-picker failure modes. I also published and browser-checked a fresh-clone reproduction:

• Live demo: https://hugosmoreira.github.io/astro-i18n-recipe-demo/
• Source: https://github.com/hugosmoreira/astro-i18n-recipe-demo

I restored the repository's PR template and kept the PR as a draft for review.

[hugosmoreira]

@ArmandPhilippot This is ready for another look when you have time. The revised recipe includes the loader, translated paths, and connected example pages, with a runnable demo linked in the description. I have now rechecked the static and server-rendered examples and the full docs build/link checks against current main. The description records the exact scope and verification. This remains related to #9256 rather than claiming to resolve the whole issue.