feat(i18n): manual routing

.changeset/little-hornets-give.md

@@ -0,0 +1,48 @@
+---
+"astro": minor
+---
+
+Adds a new i18n routing option `manual` to allow you to write your own i18n middleware:
+
+```js
+import { defineConfig } from "astro/config"
+// astro.config.mjs
+export default defineConfig({
+    i18n: {
+        locales: ["en", "fr"],
+        defaultLocale: "fr",
+        routing: "manual"
+    }
+})
+```
+
+Adding `routing: "manual"` to your i18n config disables Astro's own i18n middleware and provides you with helper functions to write your own: `redirectToDefaultLocale`, `notFound`, and `redirectToFallback`:
+
+```js
+// middleware.js
+import { redirectToDefaultLocale } from "astro:i18n";
+export const onRequest = defineMiddleware(async (context, next) => {
+    if (context.url.startsWith("/about")) {
+        return next()
+    } else {
+        return redirectToDefaultLocale(context, 302);  
+    }
+})
+```
+
+Also adds a `middleware` function that manually creates Astro's i18n middleware. This allows you to extend Astro's i18n routing instead of completely replacing it. Run `middleware` in combination with your own middleware, using the `sequence` utility to determine the order:
+
+```js title="src/middleware.js"
+import {defineMiddleware, sequence} from "astro:middleware";
+import { middleware } from "astro:i18n"; // Astro's own i18n routing config
+
+export const userMiddleware = defineMiddleware();
+
+export const onRequest = sequence(
+  userMiddleware,
+  middleware({
+    redirectToDefaultLocale: false,
+    prefixDefaultLocale: true
+  })
+)
+```

packages/astro/src/@types/astro.ts

@@ -1497,66 +1497,80 @@ export interface AstroUserConfig {
 		 *
 		 * Controls the routing strategy to determine your site URLs. Set this based on your folder/URL path configuration for your default language.
 		 */
-		routing?: {
+		// prettier-ignore
+		routing?: 
 			/**
-			 * @docs
-			 * @name i18n.routing.prefixDefaultLocale
-			 * @kind h4
-			 * @type {boolean}
-			 * @default `false`
-			 * @version 3.7.0
-			 * @description
-			 *
-			 * When `false`, only non-default languages will display a language prefix.
-			 * The `defaultLocale` will not show a language prefix and content files do not exist in a localized folder.
-			 *  URLs will be of the form `example.com/[locale]/content/` for all non-default languages, but `example.com/content/` for the default locale.
 			 *
-			 * When `true`, all URLs will display a language prefix.
-			 * URLs will be of the form `example.com/[locale]/content/` for every route, including the default language.
-			 * Localized folders are used for every language, including the default.
-			 */
-			prefixDefaultLocale?: boolean;
-
-			/**
 			 * @docs
-			 * @name i18n.routing.redirectToDefaultLocale
-			 * @kind h4
-			 * @type {boolean}
-			 * @default `true`
-			 * @version 4.2.0
+			 * @name i18n.routing
+			 * @type {string}
+			 * @version 4.6.0
 			 * @description
+			 * 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"`.
 			 *
-			 * Configures whether or not the home URL (`/`) generated by `src/pages/index.astro`
-			 * will redirect to `/[defaultLocale]` when `prefixDefaultLocale: true` is set.
-			 *
-			 * Set `redirectToDefaultLocale: false` to disable this automatic redirection at the root of your site:
-			 * ```js
-			 * // astro.config.mjs
-			 * export default defineConfig({
-			 *   i18n:{
-			 *     defaultLocale: "en",
-			 * 		locales: ["en", "fr"],
-			 *     routing: {
-			 *       prefixDefaultLocale: true,
-			 *       redirectToDefaultLocale: false
-			 *     }
-			 *   }
-			 * })
-			 *```
-			 * */
-			redirectToDefaultLocale?: boolean;
-
-			/**
-			 * @name i18n.routing.strategy
-			 * @type {"pathname"}
-			 * @default `"pathname"`
-			 * @version 3.7.0
-			 * @description
-			 *
-			 * - `"pathname": The strategy is applied to the pathname of the URLs
+			 * You will be responsible for writing your own routing logic, or executing Astro's i18n middleware manually alongside your own.
 			 */
-			strategy?: 'pathname';
-		};
+		 	'manual'
+			| {
+					/**
+					 * @docs
+					 * @name i18n.routing.prefixDefaultLocale
+					 * @kind h4
+					 * @type {boolean}
+					 * @default `false`
+					 * @version 3.7.0
+					 * @description
+					 *
+					 * When `false`, only non-default languages will display a language prefix.
+					 * The `defaultLocale` will not show a language prefix and content files do not exist in a localized folder.
+					 *  URLs will be of the form `example.com/[locale]/content/` for all non-default languages, but `example.com/content/` for the default locale.
+					 *
+					 * When `true`, all URLs will display a language prefix.
+					 * URLs will be of the form `example.com/[locale]/content/` for every route, including the default language.
+					 * Localized folders are used for every language, including the default.
+					 */
+					prefixDefaultLocale?: boolean;
+
+					/**
+					 * @docs
+					 * @name i18n.routing.redirectToDefaultLocale
+					 * @kind h4
+					 * @type {boolean}
+					 * @default `true`
+					 * @version 4.2.0
+					 * @description
+					 *
+					 * Configures whether or not the home URL (`/`) generated by `src/pages/index.astro`
+					 * will redirect to `/[defaultLocale]` when `prefixDefaultLocale: true` is set.
+					 *
+					 * Set `redirectToDefaultLocale: false` to disable this automatic redirection at the root of your site:
+					 * ```js
+					 * // astro.config.mjs
+					 * export default defineConfig({
+					 *   i18n:{
+					 *     defaultLocale: "en",
+					 * 		locales: ["en", "fr"],
+					 *     routing: {
+					 *       prefixDefaultLocale: true,
+					 *       redirectToDefaultLocale: false
+					 *     }
+					 *   }
+					 * })
+					 *```
+					 * */
+					redirectToDefaultLocale?: boolean;
+
+					/**
+					 * @name i18n.routing.strategy
+					 * @type {"pathname"}
+					 * @default `"pathname"`
+					 * @version 3.7.0
+					 * @description
+					 *
+					 * - `"pathname": The strategy is applied to the pathname of the URLs
+					 */
+					strategy?: 'pathname';
+			  };
 
 		/**
 		 * @name i18n.domains

packages/astro/src/core/app/types.ts

@@ -67,7 +67,7 @@ export type SSRManifest = {
 };
 
 export type SSRManifestI18n = {
-	fallback?: Record<string, string>;
+	fallback: Record<string, string> | undefined;
 	strategy: RoutingStrategies;
 	locales: Locales;
 	defaultLocale: string;

packages/astro/src/core/base-pipeline.ts

@@ -48,9 +48,13 @@ export abstract class Pipeline {
 		 */
 		readonly site = manifest.site ? new URL(manifest.site) : undefined
 	) {
-		this.internalMiddleware = [
-			createI18nMiddleware(i18n, manifest.base, manifest.trailingSlash, manifest.buildFormat),
-		];
+		this.internalMiddleware = [];
+		// We do use our middleware only if the user isn't using the manual setup
+		if (i18n?.strategy !== 'manual') {
+			this.internalMiddleware.push(
+				createI18nMiddleware(i18n, manifest.base, manifest.trailingSlash, manifest.buildFormat)
+			);
+		}
 	}
 
 	abstract headElements(routeData: RouteData): Promise<HeadElements> | HeadElements;

packages/astro/src/core/config/schema.ts

@@ -386,21 +386,24 @@ export const AstroConfigSchema = z.object({
 					.optional(),
 				fallback: z.record(z.string(), z.string()).optional(),
 				routing: z
-					.object({
-						prefixDefaultLocale: z.boolean().default(false),
-						redirectToDefaultLocale: z.boolean().default(true),
-						strategy: z.enum(['pathname']).default('pathname'),
-					})
-					.default({})
-					.refine(
-						({ prefixDefaultLocale, redirectToDefaultLocale }) => {
-							return !(prefixDefaultLocale === false && redirectToDefaultLocale === false);
-						},
-						{
-							message:
-								'The option `i18n.redirectToDefaultLocale` is only useful when the `i18n.prefixDefaultLocale` is set to `true`. Remove the option `i18n.redirectToDefaultLocale`, or change its value to `true`.',
-						}
-					),
+					.literal('manual')
+					.or(
+						z
+							.object({
+								prefixDefaultLocale: z.boolean().default(false),
+								redirectToDefaultLocale: z.boolean().default(true),
+							})
+							.refine(
+								({ prefixDefaultLocale, redirectToDefaultLocale }) => {
+									return !(prefixDefaultLocale === false && redirectToDefaultLocale === false);
+								},
+								{
+									message:
+										'The option `i18n.redirectToDefaultLocale` is only useful when the `i18n.prefixDefaultLocale` is set to `true`. Remove the option `i18n.redirectToDefaultLocale`, or change its value to `true`.',
+								}
+							)
+					)
+					.default({}),
 			})
 			.optional()
 			.superRefine((i18n, ctx) => {

packages/astro/src/core/errors/errors-data.ts

@@ -1067,6 +1067,21 @@ export const MissingIndexForInternationalization = {
 	hint: (src: string) => `Create an index page (\`index.astro, index.md, etc.\`) in \`${src}\`.`,
 } satisfies ErrorData;
 
+/**
+ * @docs
+ * @description
+ * Some internationalization functions are only available when Astro's own i18n routing is disabled by the configuration setting `i18n.routing: "manual"`.
+ *
+ * @see
+ * - [`i18n` routing](https://docs.astro.build/en/guides/internationalization/#routing)
+ */
+export const IncorrectStrategyForI18n = {
+	name: 'IncorrectStrategyForI18n',
+	title: "You can't use the current function with the current strategy",
+	message: (functionName: string) =>
+		`The function \`${functionName}\' can only be used when the \`i18n.routing.strategy\` is set to \`"manual"\`.`,
+} satisfies ErrorData;
+
 /**
  * @docs
  * @description
@@ -1076,7 +1091,19 @@ export const NoPrerenderedRoutesWithDomains = {
 	name: 'NoPrerenderedRoutesWithDomains',
 	title: "Prerendered routes aren't supported when internationalization domains are enabled.",
 	message: (component: string) =>
-		`Static pages aren't yet supported with multiple domains. If you wish to enable this feature, you have to disable prerendering for the page ${component}`,
+		`Static pages aren't yet supported with multiple domains. To enable this feature, you must disable prerendering for the page ${component}`,
+} satisfies ErrorData;
+
+/**
+ * @docs
+ * @description
+ * Astro throws an error if the user enables manual routing, but it doesn't have a middleware file.
+ */
+export const MissingMiddlewareForInternationalization = {
+	name: 'MissingMiddlewareForInternationalization',
+	title: 'Enabled manual internationalization routing without having a middleware.',
+	message:
+		"Your configuration setting `i18n.routing: 'manual'` requires you to provide your own i18n `middleware` file.",
 } satisfies ErrorData;
 
 /**

packages/astro/src/core/middleware/vite-plugin.ts

@@ -6,6 +6,8 @@ import { addRollupInput } from '../build/add-rollup-input.js';
 import type { BuildInternals } from '../build/internal.js';
 import type { StaticBuildOptions } from '../build/types.js';
 import { MIDDLEWARE_PATH_SEGMENT_NAME } from '../constants.js';
+import { MissingMiddlewareForInternationalization } from '../errors/errors-data.js';
+import { AstroError } from '../errors/index.js';
 
 export const MIDDLEWARE_MODULE_ID = '\0astro-internal:middleware';
 const NOOP_MIDDLEWARE = '\0noop-middleware';
@@ -44,8 +46,14 @@ export function vitePluginMiddleware({ settings }: { settings: AstroSettings }):
 		},
 		async load(id) {
 			if (id === NOOP_MIDDLEWARE) {
+				if (!userMiddlewareIsPresent && settings.config.i18n?.routing === 'manual') {
+					throw new AstroError(MissingMiddlewareForInternationalization);
+				}
 				return 'export const onRequest = (_, next) => next()';
 			} else if (id === MIDDLEWARE_MODULE_ID) {
+				if (!userMiddlewareIsPresent && settings.config.i18n?.routing === 'manual') {
+					throw new AstroError(MissingMiddlewareForInternationalization);
+				}
 				// In the build, tell Vite to emit this file
 				if (isCommandBuild) {
 					this.emitFile({