fix(i18n): improve error message (#11189)

* fix(i18n): improve error message

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

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

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

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

---------

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

.changeset/heavy-eagles-happen.md

@@ -0,0 +1,5 @@
+---
+'astro': patch
+---
+
+Improve error message when using `getLocaleByPath` on path that doesn't contain any locales.

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

@@ -1196,6 +1196,18 @@ export const i18nNotEnabled = {
 	hint: 'See https://docs.astro.build/en/guides/internationalization for a guide on setting up i18n.',
 } satisfies ErrorData;
 
+/**
+ * @docs
+ * @description
+ * An i18n utility tried to use the locale from a URL path that does not contain one. You can prevent this error by using pathHasLocale to check URLs for a `locale` first before using i18n utilities.
+ * 
+ */
+export const i18nNoLocaleFoundInPath = {
+	name: 'i18nNoLocaleFoundInPath',
+	title: 'The path doesn\'t contain any locale',
+	message: 'You tried to use an i18n utility on a path that doesn\'t contain any locale. You can use \`pathHasLocale\` first to determine if the path has a locale.',
+} satisfies  ErrorData;
+
 /**
  * @docs
  * @description

packages/astro/src/i18n/index.ts

@@ -8,7 +8,7 @@ import type {
 } from '../@types/astro.js';
 import { shouldAppendForwardSlash } from '../core/build/util.js';
 import { REROUTE_DIRECTIVE_HEADER } from '../core/constants.js';
-import { MissingLocale } from '../core/errors/errors-data.js';
+import {i18nNoLocaleFoundInPath, MissingLocale} from '../core/errors/errors-data.js';
 import { AstroError } from '../core/errors/index.js';
 import { createI18nMiddleware } from './middleware.js';
 import type { RoutingStrategies } from './utils.js';
@@ -190,11 +190,11 @@ export function getPathByLocale(locale: string, locales: Locales): string {
 			}
 		}
 	}
-	throw new Unreachable();
+	throw new AstroError(i18nNoLocaleFoundInPath);
 }
 
 /**
- * An utility function that retrieves the preferred locale that correspond to a path.
+ * A utility function that retrieves the preferred locale that correspond to a path.
  *
  * @param path
  * @param locales
@@ -205,14 +205,14 @@ export function getLocaleByPath(path: string, locales: Locales): string {
 			if (locale.path === path) {
 				// the first code is the one that user usually wants
 				const code = locale.codes.at(0);
-				if (code === undefined) throw new Unreachable();
+				if (code === undefined) throw new AstroError(i18nNoLocaleFoundInPath);
 				return code;
 			}
 		} else if (locale === path) {
 			return locale;
 		}
 	}
-	throw new Unreachable();
+	throw new AstroError(i18nNoLocaleFoundInPath);
 }
 
 /**
@@ -271,17 +271,6 @@ function peekCodePathToUse(locales: Locales, locale: string): undefined | string
 	return undefined;
 }
 
-class Unreachable extends Error {
-	constructor() {
-		super(
-			'Astro encountered an unexpected line of code.\n' +
-				'In most cases, this is not your fault, but a bug in astro code.\n' +
-				"If there isn't one already, please create an issue.\n" +
-				'https://astro.build/issues'
-		);
-	}
-}
-
 export type MiddlewarePayload = {
 	base: string;
 	locales: Locales;