feat: Primitives for i18n routing

.changeset/curvy-cats-talk.md

@@ -0,0 +1,5 @@
+---
+"@sveltejs/kit": minor
+---
+
+feat: add `resolveDestination` and `rewriteURL` hooks, enabling i18n routing

documentation/docs/30-advanced/20-hooks.md

@@ -4,12 +4,13 @@ title: Hooks
 
 'Hooks' are app-wide functions you declare that SvelteKit will call in response to specific events, giving you fine-grained control over the framework's behaviour.
 
-There are two hooks files, both optional:
+There are three hooks files, all optional:
 
 - `src/hooks.server.js` — your app's server hooks
 - `src/hooks.client.js` — your app's client hooks
+- `src/hooks.router.js` — your app's router hooks
 
-Code in these modules will run when the application starts up, making them useful for initializing database clients and so on.
+Code in the client & server modules will run when the application starts up, making them useful for initializing database clients and so on.
 
 > You can configure the location of these files with [`config.kit.files.hooks`](configuration#files).
 
@@ -232,6 +233,60 @@ During development, if an error occurs because of a syntax error in your Svelte
 
 > Make sure that `handleError` _never_ throws an error
 
+## Router hooks
+
+The following can be added to `src/hooks.router.js`. Router hooks run both on the server and the client.
+
+### rewriteURL
+
+This function allows you to rewrite URLs before they are processed by SvelteKit. It receives a `url` object and should return a `URL` object.
+
+```js
+/// file: src/hooks.router.js
+// @errors: 2345
+// @errors: 2304
+/** @type {import('@sveltejs/kit').RewriteURL} */
+export function rewriteURL({ url }) {
+	//Process requests to '/<lang>/about' as if they were to '/about'
+	const language = getLanguageFromPath(url.pathname);
+	if(language) url.pathname = url.pathname.slice(language.length + 1);
+
+	return url;
+}
+```
+
+Rewrites happen in place, and are completely invisible to the user. For example, if you rewrite `/about` to `/about-us`, the user will still see `/about` in their browser's address bar. Only the server will know that the URL has been rewritten.
+
+### resolveDestination
+
+This function allows you to change the destination of an outgoing navigation event, such as:
+- A link click
+- A `goto` call
+- A `redirect` call
+
+It receives the current url, and the destination url, and should return a `URL` object.
+
+```js
+/// file: src/hooks.router.js
+// @errors: 2345
+// @errors: 2304
+/** @type {import('@sveltejs/kit').ResolveDestination} */
+export function resolveDestination({ from, to }) {
+	if(from.origin !== to.origin) return to; //Ignore cross-origin navigations
+
+ 	//If the destination-path already includes a language, leave it
+	const destinationLanguage = getLanguageFromPath(to.pathname);
+	if(destinationLanguage) return to;
+
+	//Otherwise, add the language from the current page
+	const language = getLanguageFromPath(from.pathname) ?? defaultLanguage;
+	to.pathname = `/${language}${to.pathname}`;
+	return to;
+}
+```
+
+The `resolveDestination` hook is applied to all links and forms during prerendering and SSR, so it can safely be used even when JavaScript is disabled.
+
 ## Further reading
 
 - [Tutorial: Hooks](https://learn.svelte.dev/tutorial/handle)

packages/kit/src/core/config/index.js

@@ -93,6 +93,7 @@ function process_config(config, { cwd = process.cwd() } = {}) {
 		if (key === 'hooks') {
 			validated.kit.files.hooks.client = path.resolve(cwd, validated.kit.files.hooks.client);
 			validated.kit.files.hooks.server = path.resolve(cwd, validated.kit.files.hooks.server);
+			validated.kit.files.hooks.router = path.resolve(cwd, validated.kit.files.hooks.router);
 		} else {
 			// @ts-expect-error
 			validated.kit.files[key] = path.resolve(cwd, validated.kit.files[key]);

packages/kit/src/core/config/index.spec.js

@@ -79,7 +79,8 @@ const get_defaults = (prefix = '') => ({
 			assets: join(prefix, 'static'),
 			hooks: {
 				client: join(prefix, 'src/hooks.client'),
-				server: join(prefix, 'src/hooks.server')
+				server: join(prefix, 'src/hooks.server'),
+				router: join(prefix, 'src/hooks.router')
 			},
 			lib: join(prefix, 'src/lib'),
 			params: join(prefix, 'src/params'),

packages/kit/src/core/config/options.js

@@ -123,7 +123,8 @@ const options = object(
 				assets: string('static'),
 				hooks: object({
 					client: string(join('src', 'hooks.client')),
-					server: string(join('src', 'hooks.server'))
+					server: string(join('src', 'hooks.server')),
+					router: string(join('src', 'hooks.router'))
 				}),
 				lib: string(join('src', 'lib')),
 				params: string(join('src', 'params')),

packages/kit/src/core/sync/write_client_manifest.js

@@ -108,7 +108,8 @@ export function write_client_manifest(kit, manifest_data, output, metadata) {
 		}
 	`;
 
-	const hooks_file = resolve_entry(kit.files.hooks.client);
+	const client_hooks_file = resolve_entry(kit.files.hooks.client);
+	const router_hooks_file = resolve_entry(kit.files.hooks.router);
 
 	const typo = resolve_entry('src/+hooks.client');
 	if (typo) {
@@ -125,7 +126,16 @@ export function write_client_manifest(kit, manifest_data, output, metadata) {
 	write_if_changed(
 		`${output}/app.js`,
 		dedent`
-			${hooks_file ? `import * as client_hooks from '${relative_path(output, hooks_file)}';` : ''}
+			${
+				client_hooks_file
+					? `import * as client_hooks from '${relative_path(output, client_hooks_file)}';`
+					: ''
+			}
+			${
+				router_hooks_file
+					? `import * as router_hooks from '${relative_path(output, router_hooks_file)}';`
+					: ''
+			}
 
 			export { matchers } from './matchers.js';
 
@@ -139,8 +149,14 @@ export function write_client_manifest(kit, manifest_data, output, metadata) {
 
 			export const hooks = {
 				handleError: ${
-					hooks_file ? 'client_hooks.handleError || ' : ''
+					client_hooks_file ? 'client_hooks.handleError || ' : ''
 				}(({ error }) => { console.error(error) }),
+
+				resolveDestination: ${
+					router_hooks_file ? 'router_hooks.resolveDestination || ' : ''
+				}((event) => event.to),
+
+				rewriteURL: ${router_hooks_file ? 'router_hooks.rewriteURL || ' : ''}(({url}) => url)
 			};
 
 			export { default as root } from '../root.${isSvelte5Plus() ? 'js' : 'svelte'}';

packages/kit/src/core/sync/write_server.js

@@ -10,6 +10,7 @@ import colors from 'kleur';
 /**
  * @param {{
  *   hooks: string | null;
+ *   router_hooks: string | null;
  *   config: import('types').ValidatedConfig;
  *   has_service_worker: boolean;
  *   runtime_directory: string;
@@ -20,6 +21,7 @@ import colors from 'kleur';
 const server_template = ({
 	config,
 	hooks,
+	router_hooks,
 	has_service_worker,
 	runtime_directory,
 	template,
@@ -59,8 +61,11 @@ export const options = {
 	version_hash: ${s(hash(config.kit.version.name))}
 };
 
-export function get_hooks() {
-	return ${hooks ? `import(${s(hooks)})` : '{}'};
+export async function get_hooks() {
+	return {
+		${hooks ? `...(await import(${s(hooks)})),` : ''}
+		${router_hooks ? `...(await import(${s(router_hooks)})),` : ''}
+	};
 }
 
 export { set_assets, set_building, set_prerendering, set_private_env, set_public_env, set_safe_public_env };
@@ -77,6 +82,7 @@ export { set_assets, set_building, set_prerendering, set_private_env, set_public
  */
 export function write_server(config, output) {
 	const hooks_file = resolve_entry(config.kit.files.hooks.server);
+	const router_hooks_file = resolve_entry(config.kit.files.hooks.router);
 
 	const typo = resolve_entry('src/+hooks.server');
 	if (typo) {
@@ -100,6 +106,7 @@ export function write_server(config, output) {
 		server_template({
 			config,
 			hooks: hooks_file ? relative(hooks_file) : null,
+			router_hooks: router_hooks_file ? relative(router_hooks_file) : null,
 			has_service_worker:
 				config.kit.serviceWorker.register && !!resolve_entry(config.kit.files.serviceWorker),
 			runtime_directory: relative(runtime_directory),

packages/kit/src/exports/public.d.ts

@@ -400,6 +400,12 @@ export interface KitConfig {
 			 * @default "src/hooks.server"
 			 */
 			server?: string;
+
+			/**
+			 * The location of your router hooks.
+			 * @default "src/hooks.router"
+			 */
+			router?: string;
 		};
 		/**
 		 * your app's internal library, accessible throughout the codebase as `$lib`
@@ -674,6 +680,31 @@ export type HandleClientError = (input: {
 	message: string;
 }) => MaybePromise<void | App.Error>;
 
+/**
+ * Maps an href value to a destination
+ * @example
+ * ```js
+ * export const resolveDestination = ({ from, to })  => {
+ *   if(to.host !== from.host) return to; //Don't remap external links
+ *   const lang = getLanguageFromURL(from);
+ *   return applyLanguage(to, lang);
+ * }
+ * ```
+ */
+export type ResolveDestination = (event: { from: URL; to: URL }) => URL;
+
+/**
+ * Remap an incoming URL to a different URL.
+ *
+ * @example
+ * ```js
+ * export const rewriteURL = (url) => {
+ *   return urlWithoutLanguage(url);
+ * }
+ * ```
+ */
+export type RewriteURL = (event: { url: URL }) => URL;
+
 /**
  * The [`handleFetch`](https://kit.svelte.dev/docs/hooks#server-hooks-handlefetch) hook allows you to modify (or replace) a `fetch` request that happens inside a `load` function that runs on the server (or during pre-rendering)
  */

packages/kit/src/exports/vite/index.js

@@ -25,6 +25,8 @@ import analyse from '../../core/postbuild/analyse.js';
 import { s } from '../../utils/misc.js';
 import { hash } from '../../runtime/hash.js';
 import { dedent, isSvelte5Plus } from '../../core/sync/utils.js';
+import { resolve_destination_preprocessor } from './preprocessor/resolveDestination.js';
+
 import {
 	env_dynamic_private,
 	env_dynamic_public,
@@ -857,7 +859,19 @@ function kit({ svelte_config }) {
 		}
 	};
 
-	return [plugin_setup, plugin_virtual_modules, plugin_guard, plugin_compile];
+	const router_hook_entry = resolve_entry(kit.files.hooks.router);
+	/** @type {import('vite').Plugin} */
+	const resolve_destination = {
+		name: 'vite-plugin-sveltekit-resolve-destination',
+
+		api: {
+			sveltePreprocess: router_hook_entry
+				? resolve_destination_preprocessor({ router_hook_entry })
+				: undefined
+		}
+	};
+
+	return [plugin_setup, plugin_virtual_modules, plugin_guard, plugin_compile, resolve_destination];
 }
 
 /**