Merge 6194ff3019 into 648db6b3d2

src/client/app/router.ts

@@ -154,6 +154,10 @@ export function createRouter(
         } catch (e) {}
       }
 
+      if (siteDataRef.value.localesFallback) {
+        await loadFallback()
+      }
+
       if (latestPendingPath === pendingPath) {
         latestPendingPath = null
         route.path = inBrowser ? pendingPath : withBase(pendingPath)
@@ -168,6 +172,77 @@ export function createRouter(
         syncRouteQueryAndHash(targetLoc)
       }
     }
+
+    async function loadFallback() {
+      const locales = siteDataRef.value.locales
+
+      for (const [key, value] of Object.entries(locales)) {
+        if (!value.fallback) continue
+        if (value.fallback === 'root') {
+          throw new Error(
+            `Invalid VitePress Config: A locale (${key}), cannot fall back to (root).`
+          )
+        }
+        if (key === value.fallback) {
+          throw new Error(
+            `Invalid VitePress Config: A locale (${key}), cannot have a fallback to itself.`
+          )
+        }
+        if (!Object.keys(locales).includes(value.fallback)) {
+          throw new Error(
+            `Invalid VitePress Config: A locale (${key}), cannot have a fallback to a non existing locale.`
+          )
+        }
+      }
+
+      // If the length is less than 2, it means there are no alternative locales to fallback to.
+      if (!locales || Object.keys(locales).length < 2) {
+        return
+      }
+
+      const nonRootLocales = Object.fromEntries(
+        Object.entries(locales).filter(([name]) => name !== 'root')
+      )
+
+      const failedLocaleKey =
+        Object.keys(nonRootLocales).find(
+          (lang) =>
+            pendingPath === `/${lang}` || pendingPath.startsWith(`/${lang}/`)
+        ) || 'root'
+
+      if (failedLocaleKey !== 'root') {
+        const fallbackLang =
+          locales[failedLocaleKey].fallback ?? getCustomFallbackLang()
+
+        await loadPage(
+          pendingPath.replace(
+            `/${failedLocaleKey}`,
+            fallbackLang ? `/${fallbackLang}` : ''
+          ),
+          scrollPosition,
+          true
+        )
+      } else {
+        const fallbackPath = getRootLocaleFallbackPath()
+        if (!fallbackPath) return
+        await loadPage(fallbackPath, scrollPosition, true)
+      }
+
+      function getCustomFallbackLang() {
+        const customFallbackLang = siteDataRef.value.localesDefaultFallback
+        if (customFallbackLang && customFallbackLang !== failedLocaleKey) {
+          return customFallbackLang
+        }
+      }
+
+      function getRootLocaleFallbackPath() {
+        const fallbackLang = locales['root'].fallback
+        if (!fallbackLang) return
+        if (pendingPath === '/') return `/${fallbackLang}`
+        const pathDivider = pendingPath.startsWith('/') ? '' : '/'
+        return `/${fallbackLang}${pathDivider}${pendingPath}`
+      }
+    }
   }
 
   function syncRouteQueryAndHash(

src/node/config.ts

@@ -335,6 +335,8 @@ export async function resolveSiteData(
     appearance: userConfig.appearance ?? true,
     themeConfig: userConfig.themeConfig || {},
     locales: userConfig.locales || {},
+    localesFallback: userConfig.localesFallback ?? true,
+    localesDefaultFallback: userConfig.localesDefaultFallback,
     scrollOffset: userConfig.scrollOffset ?? 134,
     cleanUrls: !!userConfig.cleanUrls,
     contentProps: userConfig.contentProps,

src/node/siteConfig.ts

@@ -54,6 +54,16 @@ export interface UserConfig<ThemeConfig = any>
 
   locales?: LocaleConfig<ThemeConfig>
 
+  /**
+   * If a page isn't found in the current language, allow switching to another language as a backup.
+   */
+  localesFallback?: boolean
+
+  /**
+   * Use a custom locale key to be used as a default fallback for all locales. Default is root.
+   */
+  localesDefaultFallback?: string
+
   router?: {
     prefetchLinks?: boolean
   }

types/shared.d.ts

@@ -142,6 +142,14 @@ export interface SiteData<ThemeConfig = any> {
     | string[]
     | { selector: string | string[]; padding: number }
   locales: LocaleConfig<ThemeConfig>
+  /**
+   * If a page isn't found in the current language, allow switching to another language as a backup.
+   */
+  localesFallback?: boolean
+  /**
+   * Use a custom locale key to be used as a default fallback for all locales. Default is root.
+   */
+  localesDefaultFallback?: string
   localeIndex?: string
   contentProps?: Record<string, any>
   router: {
@@ -179,7 +187,14 @@ export interface LocaleSpecificConfig<ThemeConfig = any> {
 
 export type LocaleConfig<ThemeConfig = any> = Record<
   string,
-  LocaleSpecificConfig<ThemeConfig> & { label: string; link?: string }
+  LocaleSpecificConfig<ThemeConfig> & {
+    label: string
+    link?: string
+    /**
+     * If the requested page isn't found in this language, switch to the same page in the specified language as a backup.
+     */
+    fallback?: string
+  }
 >
 
 export type AdditionalConfig<ThemeConfig = any> =