feat(i18n): manual routing

[ematipico]

Changes

Closes PLT-1865

This PR adds i18n manual routing. This enabled using the the following configuration:

export default defineConfig({
	i18n: {
		defaultLocale: "fr",
		locales: ["fr", "en"],
+		routing: "manual"
	}
})

With this kind of configuration, the astro:i18n virtual modules exports new functions that users can use in their pages, and specifically in their middleware:

• redirectToDefaultLocale, to redirect to the default locale that was configured
• notFound, to return a 404
• redirectToFallback, to manually trigger the Astro i18n fallback

Another function that is exported is middleware. This function is actually useful in case the user wants to use the Astro i18n middleware, but still being able to hack it and provide some escape hatches/exceptions to some routes. Also, this middleware function accepts the majority of the option of the Astro i18n middleware. Eventually, users can do something like this, in their middleware.js file:

import { middleware } from "astro:i18n";
import { defineMiddleware, sequence } from "astro:middleware"

const myMiddleware = defineMiddleware(async (context, next) => {
	// custom logic here
	const response = await next();
	
	// fallback logic that is run **after** the astro i18n middleware
	return response;
})

export const onRequest = sequence(myMiddleware, middleware({
	redirectToDefaultLocale: false,
	prefixDefaultLocale: true
}))

Technical changes:

• the new functions export a noop function that emits an error if they didn't opt-in the manual routing
• the middleware plugin emits an error if the user opt-in the feature, but they don't have a middleware file. However, I can easily change the idea in case you think this is too much. Integrations can inject their middleware functions after all
• when the user opt-in the function, we don't inject our internal middleware
• I refactored our internal middleware. I took shared functions and lifted them, so they can be used inside our internal middleware and the user middleware

Testing

I added new tests

Docs

withastro/docs#7749

[changeset-bot]

🦋 Changeset detected

Latest commit: e781cb2

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[bluwy]

The general logic LGTM 👍

[sarah11918]

What a cool feature and exciting release! Most of these are small suggestions @ematipico but I've noted that I think we're missing some JSDoc for the configuration reference page for "manual"?

Looking so good though!

[sarah11918]

Just checking, are we waiting for a docs entry for "manual" here? This should have its own entry that shows up in the docs config reference file.

For reference, this is the text from the docs guide page, to help craft something:

When this option is enabled, Astro will disable its i18n middleware so that you can implement your own custom logic. No other routing options (e.g. prefixDefaultLocale) may be configured with routing: "manual".

You will be responsible for writing your own routing logic, or executing Astro's i18n middleware manually alongside your own.

[ematipico]

That's done dbcee6e (#10193)

[github-actions]

This PR is blocked because it contains a minor changeset. A reviewer will merge this at the next release if approved.

[sarah11918]

Admittedly, I have the hardest time figuring out what the JSDoc is going to look like ahead of time (I'm hoping the syntax is correct to get the new manual option nested under i18n.routing along with the other object! 😅 )

But all the text is approved by docs! Great work, @ematipico ! 🥳

merge day