refactor(language-select): adopt shared i18n route utilities and JSON-encoded targets

Replace the inline localizedPathname function in StarlightLanguageSelect
with buildDocsRoutePath and stripDocsLocalePrefix from the shared i18n
library. Encode the select option value as a JSON object containing both
the target path and locale code so the client-side handler can persist
the locale without re-parsing the URL. Update the persistence test
suite to use the new encoded value format and add coverage for Japanese
locale persistence.

Co-Authored-By: Hagicode <noreply@hagicode.com>
Signed-off-by: newbe36524 <newbe36524@qq.com>

Author: newbe36524

src/components/StarlightLanguageSelect.astro

@@ -1,62 +1,14 @@
 ---
-import context from 'virtual:starlight/project-context';
 import config from 'virtual:starlight/user-config';
 import Select from '@astrojs/starlight/components/Select.astro';
 import { DOCS_LOCALE_SELECTOR_OPTIONS } from '../i18n/generated/docs-locale-resources.mjs';
+import { buildDocsRoutePath, stripDocsLocalePrefix, type DocsLocale } from '@/lib/i18n';
 
-function stripTrailingSlash(path: string): string {
-  if (path === '/') {
-    return '';
-  }
-
-  return path.endsWith('/') && path !== '/' ? path.slice(0, -1) : path;
-}
-
-function localizedPathname(locale: string | undefined): string {
-  const url = new URL(Astro.url);
-
-  if (!config.locales) {
-    return url.pathname;
-  }
-
-  const nextLocale = locale === 'root' ? '' : locale;
-  const base = stripTrailingSlash(import.meta.env.BASE_URL);
-  const hasBase = url.pathname.startsWith(base);
-
-  if (hasBase) {
-    url.pathname = url.pathname.replace(base, '');
-  }
-
-  const [_leadingSlash, baseSegment] = url.pathname.split('/');
-  const htmlExt = '.html';
-  const isRootHtml = baseSegment?.endsWith(htmlExt);
-  const baseSlug = isRootHtml ? baseSegment?.slice(0, -1 * htmlExt.length) : baseSegment;
-
-  if (baseSlug && baseSlug in config.locales) {
-    if (nextLocale) {
-      url.pathname = url.pathname.replace(baseSlug, nextLocale);
-    } else if (isRootHtml) {
-      url.pathname = '/index.html';
-    } else {
-      url.pathname = url.pathname.replace('/' + baseSlug, '');
-    }
-  } else if (nextLocale) {
-    if (baseSegment === 'index.html') {
-      url.pathname = '/' + nextLocale + '.html';
-    } else {
-      url.pathname = '/' + nextLocale + url.pathname;
-    }
-  }
-
-  if (hasBase) {
-    url.pathname = base + url.pathname;
-  }
-
-  if (context.trailingSlash === 'never') {
-    url.pathname = stripTrailingSlash(url.pathname);
-  }
-
-  return url.pathname;
+function buildLanguageSelectValue(locale: DocsLocale): string {
+  return JSON.stringify({
+    path: buildDocsRoutePath(locale, stripDocsLocalePrefix(Astro.url.pathname)),
+    locale,
+  });
 }
 
 const localeOptions = DOCS_LOCALE_SELECTOR_OPTIONS.filter(({ code }) => {
@@ -75,7 +27,7 @@ const localeOptions = DOCS_LOCALE_SELECTOR_OPTIONS.filter(({ code }) => {
         icon="translate"
         label={Astro.locals.t('languageSelect.accessibleLabel')}
         options={localeOptions.map((locale) => ({
-          value: localizedPathname(locale.code),
+          value: buildLanguageSelectValue(locale.code),
           selected: locale.code === Astro.locals.starlightRoute.locale,
           label: locale.label,
         }))}
@@ -88,23 +40,21 @@ const localeOptions = DOCS_LOCALE_SELECTOR_OPTIONS.filter(({ code }) => {
 <script>
   const DOCS_LANGUAGE_STORAGE_KEY = 'starlight-route';
 
-  function isEnglishDocsPath(pathname) {
-    return pathname === '/en' || pathname === '/en/' || pathname.startsWith('/en/');
-  }
+  function parseSelectedLocaleTarget(value) {
+    try {
+      const parsed = JSON.parse(value);
+      if (!parsed || typeof parsed !== 'object') {
+        return null;
+      }
 
-  function detectDocsLocaleFromPath(pathname) {
-    const segments = pathname.split('/').filter(Boolean);
-    const firstSegment = segments[0];
-    if (firstSegment === 'en') {
-      return 'en';
-    }
+      if (typeof parsed.path !== 'string' || typeof parsed.locale !== 'string') {
+        return null;
+      }
 
-    const blogRouteLocales = ['zh-Hant', 'ja-JP', 'ko-KR', 'de-DE', 'fr-FR', 'es-ES', 'pt-BR', 'ru-RU'];
-    if (blogRouteLocales.includes(firstSegment)) {
-      return firstSegment;
+      return parsed;
+    } catch (_error) {
+      return null;
     }
-
-    return isEnglishDocsPath(pathname) ? 'en' : 'root';
   }
 
   function serializeStoredDocsLocale(storageValue, locale) {
@@ -122,9 +72,7 @@ const localeOptions = DOCS_LOCALE_SELECTOR_OPTIONS.filter(({ code }) => {
     return JSON.stringify(routeObj);
   }
 
-  function persistSelectedDocsLocale(targetPath) {
-    const locale = detectDocsLocaleFromPath(targetPath);
-
+  function persistSelectedDocsLocale(locale) {
     try {
       const previousValue = localStorage.getItem(DOCS_LANGUAGE_STORAGE_KEY);
       localStorage.setItem(
@@ -143,8 +91,13 @@ const localeOptions = DOCS_LOCALE_SELECTOR_OPTIONS.filter(({ code }) => {
       if (select) {
         select.addEventListener('change', (e) => {
           if (e.currentTarget instanceof HTMLSelectElement) {
-            persistSelectedDocsLocale(e.currentTarget.value);
-            window.location.pathname = e.currentTarget.value;
+            const target = parseSelectedLocaleTarget(e.currentTarget.value);
+            if (!target) {
+              return;
+            }
+
+            persistSelectedDocsLocale(target.locale);
+            window.location.pathname = target.path;
           }
         });
         window.addEventListener('pageshow', (event) => {

src/lib/i18n.test.ts

@@ -92,6 +92,7 @@ describe('docs locale helpers', () => {
     ['root', '/en/install/', '/install/'],
     ['root', '/install/', '/install/'],
     ['root', '/en/install', '/install'],
+    ['ja-JP', '/en/product-overview/', '/ja-JP/product-overview/'],
     ['ja-JP', '/blog/example/', '/ja-JP/blog/example/'],
     ['fr-FR', '/en/blog/example/', '/fr-FR/blog/example/'],
   ] as const)('builds %s route for %s', (locale, originalPath, expected) => {

tests/language-select-persistence.test.mjs

@@ -7,6 +7,7 @@ import { fileURLToPath } from 'node:url';
 import { DOCS_LOCALE_SELECTOR_OPTIONS } from '../src/i18n/generated/docs-locale-resources.mjs';
 
 const testDir = path.dirname(fileURLToPath(import.meta.url));
+const encodeSelectionValue = (path, locale) => JSON.stringify({ path, locale });
 
 async function readLanguageSelectScript() {
   const componentPath = path.join(testDir, '..', 'src', 'components', 'StarlightLanguageSelect.astro');
@@ -39,7 +40,7 @@ function evaluateLanguageSelectScript(scriptContent, options = {}) {
 
   const select = Object.setPrototypeOf(
     {
-      value: options.selectedValue ?? '/en/product-overview/',
+      value: options.selectedValue ?? encodeSelectionValue('/en/product-overview/', 'en'),
       selectedIndex,
       addEventListener(type, listener) {
         listeners.set(type, listener);
@@ -115,7 +116,7 @@ function evaluateLanguageSelectScript(scriptContent, options = {}) {
 test('language selector persists English locale before navigating', async () => {
   const scriptContent = await readLanguageSelectScript();
   const result = evaluateLanguageSelectScript(scriptContent, {
-    selectedValue: '/en/product-overview/',
+    selectedValue: encodeSelectionValue('/en/product-overview/', 'en'),
     storedRouteValue: JSON.stringify({ path: '/product-overview/', lang: 'root' }),
   });
 
@@ -131,6 +132,8 @@ test('language selector renders the full generated locale set in the header', as
   const source = await readFile(componentPath, 'utf8');
 
   assert.match(source, /DOCS_LOCALE_SELECTOR_OPTIONS/);
+  assert.match(source, /buildDocsRoutePath/);
+  assert.match(source, /stripDocsLocalePrefix/);
   assert.match(source, /label: locale\.label/);
   assert.match(source, /return true;/);
   assert.deepEqual(
@@ -153,10 +156,24 @@ test('language selector renders the full generated locale set in the header', as
 test('language selector navigates even when localStorage fails', async () => {
   const scriptContent = await readLanguageSelectScript();
   const result = evaluateLanguageSelectScript(scriptContent, {
-    selectedValue: '/product-overview/',
+    selectedValue: encodeSelectionValue('/product-overview/', 'root'),
     storageThrows: true,
   });
 
   assert.equal(result.pathname, '/product-overview/');
   assert.equal(result.storedRouteValue, undefined);
 });
+
+test('language selector persists Japanese locale from the encoded route target', async () => {
+  const scriptContent = await readLanguageSelectScript();
+  const result = evaluateLanguageSelectScript(scriptContent, {
+    selectedValue: encodeSelectionValue('/ja-JP/product-overview/', 'ja-JP'),
+    storedRouteValue: JSON.stringify({ path: '/en/product-overview/', lang: 'en' }),
+  });
+
+  assert.equal(result.pathname, '/ja-JP/product-overview/');
+  assert.deepEqual(JSON.parse(result.storedRouteValue), {
+    path: '/en/product-overview/',
+    lang: 'ja-JP',
+  });
+});