From 28187dc59828e2a468aa5f03fa1a89ba212162b4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A4=8F=E6=B2=AB=E8=8A=B1=E7=81=ABzzz=F0=9F=8C=99?=
 <xmcn@1l1.icu>
Date: Thu, 22 Jan 2026 12:43:39 +0800
Subject: [PATCH 1/6] Fix i18n code logic

---
 layer/content.config.ts | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/layer/content.config.ts b/layer/content.config.ts
index b0b9bb80b..5ae63c50f 100644
--- a/layer/content.config.ts
+++ b/layer/content.config.ts
@@ -21,9 +21,10 @@ let collections: Record<string, DefinedCollection>
 if (locales && Array.isArray(locales)) {
   collections = {}
   for (const locale of locales) {
-    const code = (typeof locale === 'string' ? locale : locale.code).replace('-', '_')
+    const code = (typeof locale === 'string' ? locale : locale.code)
+    const safeCode = code.replace('-', '_')
 
-    collections[`landing_${code}`] = defineCollection({
+    collections[`landing_${safeCode}`] = defineCollection({
       type: 'page',
       source: {
         cwd,
@@ -31,7 +32,7 @@ if (locales && Array.isArray(locales)) {
       },
     })
 
-    collections[`docs_${code}`] = defineCollection({
+    collections[`docs_${safeCode}`] = defineCollection({
       type: 'page',
       source: {
         cwd,

From b758a08a122ba7040e1f7636b841d59c5ee7e37a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A4=8F=E6=B2=AB=E8=8A=B1=E7=81=ABzzz=F0=9F=8C=99?=
 <xmcn@1l1.icu>
Date: Thu, 22 Jan 2026 13:03:58 +0800
Subject: [PATCH 2/6] Fix queryCollection

---
 layer/app/pages/[[lang]]/[...slug].vue | 4 +++-
 layer/app/templates/landing.vue        | 3 ++-
 layer/app/utils/locale.ts              | 3 +++
 layer/server/utils/content.ts          | 7 ++++---
 layer/server/utils/locale.ts           | 3 +++
 5 files changed, 15 insertions(+), 5 deletions(-)
 create mode 100644 layer/app/utils/locale.ts
 create mode 100644 layer/server/utils/locale.ts

diff --git a/layer/app/pages/[[lang]]/[...slug].vue b/layer/app/pages/[[lang]]/[...slug].vue
index e2f1768d8..fcf6c0937 100644
--- a/layer/app/pages/[[lang]]/[...slug].vue
+++ b/layer/app/pages/[[lang]]/[...slug].vue
@@ -3,6 +3,8 @@ import { kebabCase } from 'scule'
 import type { ContentNavigationItem, Collections, DocsCollectionItem } from '@nuxt/content'
 import { findPageHeadline } from '@nuxt/content/utils'
 
+import { safeLocaleCode } from '~/utils/locale'
+
 definePageMeta({
   layout: 'docs',
 })
@@ -12,7 +14,7 @@ const { locale, isEnabled, t } = useDocusI18n()
 const appConfig = useAppConfig()
 const navigation = inject<Ref<ContentNavigationItem[]>>('navigation')
 
-const collectionName = computed(() => isEnabled.value ? `docs_${locale.value}` : 'docs')
+const collectionName = computed(() => isEnabled.value ? `docs_${safeLocaleCode(locale.value)}` : 'docs')
 
 const [{ data: page }, { data: surround }] = await Promise.all([
   useAsyncData(kebabCase(route.path), () => queryCollection(collectionName.value as keyof Collections).path(route.path).first() as Promise<DocsCollectionItem>),
diff --git a/layer/app/templates/landing.vue b/layer/app/templates/landing.vue
index c77ef1160..295659dca 100644
--- a/layer/app/templates/landing.vue
+++ b/layer/app/templates/landing.vue
@@ -1,11 +1,12 @@
 <script setup lang="ts">
 import type { Collections } from '@nuxt/content'
+import { safeLocaleCode } from '~/utils/locale'
 
 const route = useRoute()
 const { locale, isEnabled } = useDocusI18n()
 
 // Dynamic collection name based on i18n status
-const collectionName = computed(() => isEnabled.value ? `landing_${locale.value}` : 'landing')
+const collectionName = computed(() => isEnabled.value ? `landing_${safeLocaleCode(locale.value)}` : 'landing')
 
 const { data: page } = await useAsyncData(collectionName.value, () => queryCollection(collectionName.value as keyof Collections).path(route.path).first())
 if (!page.value) {
diff --git a/layer/app/utils/locale.ts b/layer/app/utils/locale.ts
new file mode 100644
index 000000000..c8b251ffe
--- /dev/null
+++ b/layer/app/utils/locale.ts
@@ -0,0 +1,3 @@
+export function safeLocaleCode(locale: string): string {
+  return locale.replaceAll('-', '_')
+}
\ No newline at end of file
diff --git a/layer/server/utils/content.ts b/layer/server/utils/content.ts
index 2f1569bf7..a2116b94e 100644
--- a/layer/server/utils/content.ts
+++ b/layer/server/utils/content.ts
@@ -1,4 +1,5 @@
 import type { LocaleObject } from '@nuxtjs/i18n'
+import { safeLocaleCode } from './locale'
 
 type ConfigWithLocales = {
   i18n?: { locales?: Array<string | LocaleObject> }
@@ -17,11 +18,11 @@ export function getAvailableLocales(config: ConfigWithLocales): string[] {
 
 export function getCollectionsToQuery(locale: string | undefined, availableLocales: string[]): string[] {
   if (locale && availableLocales.includes(locale)) {
-    return [`docs_${locale}`]
+    return [`docs_${safeLocaleCode(locale)}`]
   }
 
   return availableLocales.length > 0
-    ? availableLocales.map(l => `docs_${l}`)
+    ? availableLocales.map(l => `docs_${safeLocaleCode(l)}`)
     : ['docs']
 }
 
@@ -30,7 +31,7 @@ export function getCollectionFromPath(path: string, availableLocales: string[]):
   const firstSegment = pathSegments[0]
 
   if (firstSegment && availableLocales.includes(firstSegment)) {
-    return `docs_${firstSegment}`
+    return `docs_${safeLocaleCode(firstSegment)}`
   }
 
   return 'docs'
diff --git a/layer/server/utils/locale.ts b/layer/server/utils/locale.ts
new file mode 100644
index 000000000..c8b251ffe
--- /dev/null
+++ b/layer/server/utils/locale.ts
@@ -0,0 +1,3 @@
+export function safeLocaleCode(locale: string): string {
+  return locale.replaceAll('-', '_')
+}
\ No newline at end of file

From 0bdd1f69fc59422e1bb509f357ba1ac8da5ad6dd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A4=8F=E6=B2=AB=E8=8A=B1=E7=81=ABzzz=F0=9F=8C=99?=
 <xmcn@1l1.icu>
Date: Thu, 22 Jan 2026 13:09:21 +0800
Subject: [PATCH 3/6] Fix lint error

---
 layer/app/pages/[[lang]]/[...slug].vue | 2 +-
 layer/app/templates/landing.vue        | 2 +-
 layer/content.config.ts                | 4 +++-
 layer/server/utils/content.ts          | 2 +-
 layer/server/utils/locale.ts           | 3 ---
 layer/{app => }/utils/locale.ts        | 2 +-
 6 files changed, 7 insertions(+), 8 deletions(-)
 delete mode 100644 layer/server/utils/locale.ts
 rename layer/{app => }/utils/locale.ts (97%)

diff --git a/layer/app/pages/[[lang]]/[...slug].vue b/layer/app/pages/[[lang]]/[...slug].vue
index fcf6c0937..92a2fc2ee 100644
--- a/layer/app/pages/[[lang]]/[...slug].vue
+++ b/layer/app/pages/[[lang]]/[...slug].vue
@@ -3,7 +3,7 @@ import { kebabCase } from 'scule'
 import type { ContentNavigationItem, Collections, DocsCollectionItem } from '@nuxt/content'
 import { findPageHeadline } from '@nuxt/content/utils'
 
-import { safeLocaleCode } from '~/utils/locale'
+import { safeLocaleCode } from '../../../utils/locale'
 
 definePageMeta({
   layout: 'docs',
diff --git a/layer/app/templates/landing.vue b/layer/app/templates/landing.vue
index 295659dca..b7f6e7b4e 100644
--- a/layer/app/templates/landing.vue
+++ b/layer/app/templates/landing.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import type { Collections } from '@nuxt/content'
-import { safeLocaleCode } from '~/utils/locale'
+import { safeLocaleCode } from '../../utils/locale'
 
 const route = useRoute()
 const { locale, isEnabled } = useDocusI18n()
diff --git a/layer/content.config.ts b/layer/content.config.ts
index 5ae63c50f..2985d78d4 100644
--- a/layer/content.config.ts
+++ b/layer/content.config.ts
@@ -3,6 +3,8 @@ import { defineContentConfig, defineCollection, z } from '@nuxt/content'
 import { useNuxt } from '@nuxt/kit'
 import { joinURL } from 'ufo'
 
+import { safeLocaleCode } from './utils/locale'
+
 const { options } = useNuxt()
 const cwd = joinURL(options.rootDir, 'content')
 const locales = options.i18n?.locales
@@ -22,7 +24,7 @@ if (locales && Array.isArray(locales)) {
   collections = {}
   for (const locale of locales) {
     const code = (typeof locale === 'string' ? locale : locale.code)
-    const safeCode = code.replace('-', '_')
+    const safeCode = safeLocaleCode(code)
 
     collections[`landing_${safeCode}`] = defineCollection({
       type: 'page',
diff --git a/layer/server/utils/content.ts b/layer/server/utils/content.ts
index a2116b94e..95ffe313c 100644
--- a/layer/server/utils/content.ts
+++ b/layer/server/utils/content.ts
@@ -1,5 +1,5 @@
 import type { LocaleObject } from '@nuxtjs/i18n'
-import { safeLocaleCode } from './locale'
+import { safeLocaleCode } from '../../utils/locale'
 
 type ConfigWithLocales = {
   i18n?: { locales?: Array<string | LocaleObject> }
diff --git a/layer/server/utils/locale.ts b/layer/server/utils/locale.ts
deleted file mode 100644
index c8b251ffe..000000000
--- a/layer/server/utils/locale.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-export function safeLocaleCode(locale: string): string {
-  return locale.replaceAll('-', '_')
-}
\ No newline at end of file
diff --git a/layer/app/utils/locale.ts b/layer/utils/locale.ts
similarity index 97%
rename from layer/app/utils/locale.ts
rename to layer/utils/locale.ts
index c8b251ffe..938b44cff 100644
--- a/layer/app/utils/locale.ts
+++ b/layer/utils/locale.ts
@@ -1,3 +1,3 @@
 export function safeLocaleCode(locale: string): string {
   return locale.replaceAll('-', '_')
-}
\ No newline at end of file
+}

From 42e0638c9bff1f9433d66526a4bc02c56cd5c963 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A4=8F=E6=B2=AB=E8=8A=B1=E7=81=ABzzz=F0=9F=8C=99?=
 <xmcn@1l1.icu>
Date: Thu, 22 Jan 2026 17:58:32 +0800
Subject: [PATCH 4/6] Fix pages query collection

---
 layer/app/app.vue   | 3 ++-
 layer/app/error.vue | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/layer/app/app.vue b/layer/app/app.vue
index 99c5d68bb..aff70faa5 100644
--- a/layer/app/app.vue
+++ b/layer/app/app.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import type { ContentNavigationItem, PageCollections } from '@nuxt/content'
 import * as nuxtUiLocales from '@nuxt/ui/locale'
+import { safeLocaleCode } from '../utils/locale'
 
 const { seo } = useAppConfig()
 const site = useSiteConfig()
@@ -9,7 +10,7 @@ const { locale, locales, isEnabled, switchLocalePath } = useDocusI18n()
 const nuxtUiLocale = computed(() => nuxtUiLocales[locale.value as keyof typeof nuxtUiLocales] || nuxtUiLocales.en)
 const lang = computed(() => nuxtUiLocale.value.code)
 const dir = computed(() => nuxtUiLocale.value.dir)
-const collectionName = computed(() => isEnabled.value ? `docs_${locale.value}` : 'docs')
+const collectionName = computed(() => isEnabled.value ? `docs_${safeLocaleCode(locale.value)}` : 'docs')
 
 useHead({
   meta: [
diff --git a/layer/app/error.vue b/layer/app/error.vue
index 0b6dd828b..4d0e57758 100644
--- a/layer/app/error.vue
+++ b/layer/app/error.vue
@@ -2,6 +2,7 @@
 import type { NuxtError } from '#app'
 import type { ContentNavigationItem, PageCollections } from '@nuxt/content'
 import * as nuxtUiLocales from '@nuxt/ui/locale'
+import { safeLocaleCode } from '../utils/locale'
 
 const props = defineProps<{
   error: NuxtError
@@ -44,7 +45,7 @@ if (isEnabled.value) {
   })
 }
 
-const collectionName = computed(() => isEnabled.value ? `docs_${locale.value}` : 'docs')
+const collectionName = computed(() => isEnabled.value ? `docs_${safeLocaleCode(locale.value)}` : 'docs')
 
 const { data: navigation } = await useAsyncData(`navigation_${collectionName.value}`, () => queryCollectionNavigation(collectionName.value as keyof PageCollections), {
   transform: (data: ContentNavigationItem[]) => {

From c3efc3612e06f338db189db91a717eab1684d808 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A4=8F=E6=B2=AB=E8=8A=B1=E7=81=ABzzz=F0=9F=8C=99?=
 <xmcn@1l1.icu>
Date: Thu, 22 Jan 2026 18:29:15 +0800
Subject: [PATCH 5/6] Fix i18n path resolution

---
 layer/app/app.vue                      |  2 +-
 layer/app/error.vue                    |  2 +-
 layer/app/pages/[[lang]]/[...slug].vue |  4 ++--
 layer/app/templates/landing.vue        |  2 +-
 layer/server/mcp/tools/get-page.ts     |  4 ++--
 layer/server/mcp/tools/list-pages.ts   |  6 +++---
 layer/server/utils/content.ts          | 14 +++++++-------
 7 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/layer/app/app.vue b/layer/app/app.vue
index aff70faa5..081f53016 100644
--- a/layer/app/app.vue
+++ b/layer/app/app.vue
@@ -48,7 +48,7 @@ const { data: navigation } = await useAsyncData(() => `navigation_${collectionNa
   transform: (data: ContentNavigationItem[]) => {
     const rootResult = data.find(item => item.path === '/docs')?.children || data || []
 
-    return rootResult.find(item => item.path === `/${locale.value}`)?.children || rootResult
+    return rootResult.find(item => item.path === `/${locale.value.toLowerCase()}`)?.children || rootResult
   },
   watch: [locale],
 })
diff --git a/layer/app/error.vue b/layer/app/error.vue
index 4d0e57758..95505e697 100644
--- a/layer/app/error.vue
+++ b/layer/app/error.vue
@@ -51,7 +51,7 @@ const { data: navigation } = await useAsyncData(`navigation_${collectionName.val
   transform: (data: ContentNavigationItem[]) => {
     const rootResult = data.find(item => item.path === '/docs')?.children || data || []
 
-    return rootResult.find(item => item.path === `/${locale.value}`)?.children || rootResult
+    return rootResult.find(item => item.path === `/${locale.value.toLowerCase()}`)?.children || rootResult
   },
   watch: [locale],
 })
diff --git a/layer/app/pages/[[lang]]/[...slug].vue b/layer/app/pages/[[lang]]/[...slug].vue
index 92a2fc2ee..d55f07b2d 100644
--- a/layer/app/pages/[[lang]]/[...slug].vue
+++ b/layer/app/pages/[[lang]]/[...slug].vue
@@ -17,9 +17,9 @@ const navigation = inject<Ref<ContentNavigationItem[]>>('navigation')
 const collectionName = computed(() => isEnabled.value ? `docs_${safeLocaleCode(locale.value)}` : 'docs')
 
 const [{ data: page }, { data: surround }] = await Promise.all([
-  useAsyncData(kebabCase(route.path), () => queryCollection(collectionName.value as keyof Collections).path(route.path).first() as Promise<DocsCollectionItem>),
+  useAsyncData(kebabCase(route.path), () => queryCollection(collectionName.value as keyof Collections).path(route.path.toLowerCase()).first() as Promise<DocsCollectionItem>),
   useAsyncData(`${kebabCase(route.path)}-surround`, () => {
-    return queryCollectionItemSurroundings(collectionName.value as keyof Collections, route.path, {
+    return queryCollectionItemSurroundings(collectionName.value as keyof Collections, route.path.toLowerCase(), {
       fields: ['description'],
     })
   }),
diff --git a/layer/app/templates/landing.vue b/layer/app/templates/landing.vue
index b7f6e7b4e..2c2808ee6 100644
--- a/layer/app/templates/landing.vue
+++ b/layer/app/templates/landing.vue
@@ -8,7 +8,7 @@ const { locale, isEnabled } = useDocusI18n()
 // Dynamic collection name based on i18n status
 const collectionName = computed(() => isEnabled.value ? `landing_${safeLocaleCode(locale.value)}` : 'landing')
 
-const { data: page } = await useAsyncData(collectionName.value, () => queryCollection(collectionName.value as keyof Collections).path(route.path).first())
+const { data: page } = await useAsyncData(collectionName.value, () => queryCollection(collectionName.value as keyof Collections).path(route.path.toLowerCase()).first())
 if (!page.value) {
   throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
 }
diff --git a/layer/server/mcp/tools/get-page.ts b/layer/server/mcp/tools/get-page.ts
index dadf3cb15..6807598f4 100644
--- a/layer/server/mcp/tools/get-page.ts
+++ b/layer/server/mcp/tools/get-page.ts
@@ -27,9 +27,9 @@ WORKFLOW: This tool returns the complete page content including title, descripti
     const siteUrl = import.meta.dev ? 'http://localhost:3000' : inferSiteURL()
 
     const availableLocales = getAvailableLocales(config)
-    const collectionName = config.i18n?.locales
+    const { collection: collectionName } = config.i18n?.locales
       ? getCollectionFromPath(path, availableLocales)
-      : 'docs'
+      : { collection: 'docs' }
 
     try {
       const page = await queryCollection(event, collectionName as keyof Collections)
diff --git a/layer/server/mcp/tools/list-pages.ts b/layer/server/mcp/tools/list-pages.ts
index 5d34accc5..962c919b3 100644
--- a/layer/server/mcp/tools/list-pages.ts
+++ b/layer/server/mcp/tools/list-pages.ts
@@ -36,8 +36,8 @@ OUTPUT: Returns a structured list with:
 
     try {
       const allPages = await Promise.all(
-        collections.map(async (collectionName) => {
-          const pages = await queryCollection(event, collectionName as keyof Collections)
+        collections.map(async ({ collection, locale: localeCode }) => {
+          const pages = await queryCollection(event, collection as keyof Collections)
             .select('title', 'path', 'description')
             .all()
 
@@ -45,7 +45,7 @@ OUTPUT: Returns a structured list with:
             title: page.title,
             path: page.path,
             description: page.description,
-            locale: collectionName.replace('docs_', ''),
+            locale: localeCode,
             url: `${siteUrl}${page.path}`,
           }))
         }),
diff --git a/layer/server/utils/content.ts b/layer/server/utils/content.ts
index 95ffe313c..cdd2ba70e 100644
--- a/layer/server/utils/content.ts
+++ b/layer/server/utils/content.ts
@@ -16,23 +16,23 @@ export function getAvailableLocales(config: ConfigWithLocales): string[] {
     : []
 }
 
-export function getCollectionsToQuery(locale: string | undefined, availableLocales: string[]): string[] {
+export function getCollectionsToQuery(locale: string | undefined, availableLocales: string[]): Array<{ collection: string, locale?: string }> {
   if (locale && availableLocales.includes(locale)) {
-    return [`docs_${safeLocaleCode(locale)}`]
+    return [{ collection: `docs_${safeLocaleCode(locale)}`, locale }]
   }
 
   return availableLocales.length > 0
-    ? availableLocales.map(l => `docs_${safeLocaleCode(l)}`)
-    : ['docs']
+    ? availableLocales.map(l => ({ collection: `docs_${safeLocaleCode(l)}`, locale: l }))
+    : [{ collection: 'docs' }]
 }
 
-export function getCollectionFromPath(path: string, availableLocales: string[]): string {
+export function getCollectionFromPath(path: string, availableLocales: string[]): { collection: string, locale?: string } {
   const pathSegments = path.split('/').filter(Boolean)
   const firstSegment = pathSegments[0]
 
   if (firstSegment && availableLocales.includes(firstSegment)) {
-    return `docs_${safeLocaleCode(firstSegment)}`
+    return { collection: `docs_${safeLocaleCode(firstSegment)}`, locale: firstSegment }
   }
 
-  return 'docs'
+  return { collection: 'docs' }
 }

From 7e23df288a44c5361421436acc37c78e962df1bf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A4=8F=E6=B2=AB=E8=8A=B1=E7=81=ABzzz=F0=9F=8C=99?=
 <xmcn@1l1.icu>
Date: Thu, 22 Jan 2026 20:02:06 +0800
Subject: [PATCH 6/6] temp solution to fix a bug that incorrectly solve i18n
 routes

---
 layer/modules/routing.ts | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/layer/modules/routing.ts b/layer/modules/routing.ts
index 9c07d6589..d13d434bb 100644
--- a/layer/modules/routing.ts
+++ b/layer/modules/routing.ts
@@ -23,9 +23,17 @@ export default defineNuxtModule({
       const landingTemplate = resolve('../app/templates/landing.vue')
 
       if (isI18nEnabled) {
-        pages.push({
+        // Get locale codes for regex pattern
+        const locales = nuxt.options.i18n?.locales || []
+        const localeCodes = locales.map((locale: string | { code: string }) =>
+          typeof locale === 'string' ? locale : locale.code,
+        ).join('|')
+
+        // Use regex to only match valid locale codes or root
+        // This prevents /:lang? from matching /en/mcp
+        pages.unshift({
           name: 'lang-index',
-          path: '/:lang?',
+          path: `/:lang(${localeCodes})?`,
           file: landingTemplate,
         })
       }