Fix `absolutePathToLang()` issue (#3298)

4 files changed, 17 insertions, 5 deletions

diff --git a/.changeset/dry-tomatoes-camp.md b/.changeset/dry-tomatoes-camp.md
new file mode 100644
index 00000000..96773e51
--- /dev/null
+++ b/.changeset/dry-tomatoes-camp.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': patch
+---
+
+Fixes a potential issue with [`absolutePathToLang()`](https://starlight.astro.build/reference/plugins/#absolutepathtolang) plugin API not handling paths with spaces correctly.
diff --git a/packages/starlight/__tests__/plugins/translations.test.ts b/packages/starlight/__tests__/plugins/translations.test.ts
index d626bdac..84b16627 100644
--- a/packages/starlight/__tests__/plugins/translations.test.ts
+++ b/packages/starlight/__tests__/plugins/translations.test.ts
@@ -68,4 +68,6 @@ test('can infer langs from an absolute path in the plugin context using absolute
 	expect(langs[1]).toBe('pt-BR');
 	// A page not matching any language defaults to the default language.
 	expect(langs[2]).toBe('en');
+	// A known language and an absolute path containing spaces.
+	expect(langs[3]).toBe('ar');
 });
diff --git a/packages/starlight/__tests__/plugins/vitest.config.ts b/packages/starlight/__tests__/plugins/vitest.config.ts
index 7a35ef91..d6d0aea1 100644
--- a/packages/starlight/__tests__/plugins/vitest.config.ts
+++ b/packages/starlight/__tests__/plugins/vitest.config.ts
@@ -1,3 +1,4 @@
+import { fileURLToPath } from 'node:url';
 import { defineVitestConfig } from '../test-config';
 
 export default defineVitestConfig({
@@ -77,9 +78,12 @@ export default defineVitestConfig({
 							useTranslations('en')('testPlugin3.doThing'),
 						],
 						langs: [
-							absolutePathToLang(new URL('./en/index.md', docsUrl).pathname),
-							absolutePathToLang(new URL('./pt-br/index.md', docsUrl).pathname),
-							absolutePathToLang(new URL('./index.md', docsUrl).pathname),
+							// We convert URLs to file paths to avoid potential issues with URL encoded paths,
+							// e.g. running tests with a path that contains spaces and would be `%20` encoded.
+							absolutePathToLang(fileURLToPath(new URL('./en/index.md', docsUrl))),
+							absolutePathToLang(fileURLToPath(new URL('./pt-br/index.md', docsUrl))),
+							absolutePathToLang(fileURLToPath(new URL('./index.md', docsUrl))),
+							absolutePathToLang(fileURLToPath(new URL('./ar/path with spaces/index.md', docsUrl))),
 						],
 					};
 
diff --git a/packages/starlight/integrations/shared/absolutePathToLang.ts b/packages/starlight/integrations/shared/absolutePathToLang.ts
index 24ab2245..eb40c775 100644
--- a/packages/starlight/integrations/shared/absolutePathToLang.ts
+++ b/packages/starlight/integrations/shared/absolutePathToLang.ts
@@ -1,3 +1,4 @@
+import { pathToFileURL } from 'node:url';
 import type { AstroConfig } from 'astro';
 import type { StarlightConfig } from '../../types';
 import { localeToLang } from './localeToLang';
@@ -16,8 +17,8 @@ export function absolutePathToLang(
 	}
 ): string {
 	const docsPath = getCollectionPath('docs', astroConfig.srcDir);
-	// Format path to unix style path.
-	path = path?.replace(/\\/g, '/');
+	// Format path to URL-encoded path.
+	path = pathToFileURL(path).pathname;
 	// Ensure that the page path starts with a slash if the docs directory also does,
 	// which makes stripping the docs path in the next step work on Windows, too.
 	if (path && !path.startsWith('/') && docsPath.startsWith('/')) path = '/' + path;