fix(vitepress): address cubic review on #247

Map VP locale keys vs i18n codes, keep disk roots with
routeMessages, harden load/glob, re-chain enhanceApp, CI lint.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: s00d

docs/news/index.md

@@ -10,7 +10,7 @@ outline: 'deep'
 
 **Date**: 2026-08-05
 
-**Package**: `@i18n-micro/vitepress@1.0.1`
+**Package**: `@i18n-micro/vitepress@1.0.0`
 
 New workspace package for VitePress docs sites: JSON dictionaries, `$t` / `<I18nT>` in markdown, path sync with VitePress `locales`, and optional `<I18nSwitcher>`. Complements (does not replace) built-in multi-locale markdown and `vitepress-i18n` theme chrome helpers.
 

packages/vitepress/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i18n-micro/vitepress",
-  "version": "1.0.1",
+  "version": "1.0.0",
   "description": "VitePress bindings for i18n-micro — runtime dictionaries, MD components, and locale switcher.",
   "keywords": [
     "i18n",

packages/vitepress/playground/.vitepress/config.mts

@@ -49,13 +49,13 @@ export default defineConfig(
           link: '/fr/',
           themeConfig: {
             nav: [
-              { text: 'Accueil', link: '/fr/' },
-              { text: 'Démo', link: '/fr/guide/demo' },
+              { text: 'Accueil', link: '/' },
+              { text: 'Démo', link: '/guide/demo' },
             ],
             sidebar: [
               {
                 text: 'Guide',
-                items: [{ text: 'Démo in-page', link: '/fr/guide/demo' }],
+                items: [{ text: 'Démo in-page', link: '/guide/demo' }],
               },
             ],
           },

packages/vitepress/playground/fr/guide/demo.md

@@ -29,8 +29,8 @@ Locale actuelle : **{{ locale }}**
 
 ## Groupe
 
-<I18nGroup prefix="cta">
-  <I18nT keypath="readMore" />
+<I18nGroup prefix="cta" v-slot="{ t: tg }">
+  {{ tg('readMore') }}
 </I18nGroup>
 
 ## `<I18nSwitcher>` optionnel (thèmes custom)

packages/vitepress/playground/fr/index.md

@@ -13,7 +13,7 @@ Chaînes UI runtime (pas un remplacement du markdown dupliqué).
 </p>
 
 <p>
-  <a href="/fr/guide/demo">{{ $t('cta.readMore') }}</a>
+  <I18nLink to="/guide/demo">{{ $t('cta.readMore') }}</I18nLink>
 </p>
 
 Utilisez le menu de langue **intégré** (icône globe) pour changer de locale.

packages/vitepress/playground/guide/demo.md

@@ -29,8 +29,8 @@ Current locale: **{{ locale }}**
 
 ## Group
 
-<I18nGroup prefix="cta">
-  <I18nT keypath="readMore" />
+<I18nGroup prefix="cta" v-slot="{ t: tg }">
+  {{ tg('readMore') }}
 </I18nGroup>
 
 ## Optional `<I18nSwitcher>` (custom themes)

packages/vitepress/playground/index.md

@@ -13,7 +13,7 @@ Runtime UI strings (not a replacement for duplicated markdown prose).
 </p>
 
 <p>
-  <a href="/guide/demo">{{ $t('cta.readMore') }}</a>
+  <I18nLink to="/guide/demo">{{ $t('cta.readMore') }}</I18nLink>
 </p>
 
 Use the **built-in** language menu (globe icon) to switch locale.

packages/vitepress/src/create.ts

@@ -93,6 +93,9 @@ export function createVitePressI18n(options: VitePressI18nOptions): CreateVitePr
   applyRouteMessages(plugin, options.messages, options.routeMessages)
 
   let adapter: VitePressRouterAdapter | null = null
+  let installed = false
+  let boundSyncHandler: ((to: string) => unknown) | null = null
+  let chainedPrevious: ((to: string) => unknown) | undefined
 
   const enhanceApp = (ctx: {
     app: App
@@ -101,40 +104,56 @@ export function createVitePressI18n(options: VitePressI18nOptions): CreateVitePr
   }) => {
     const { app, router } = ctx
 
-    adapter = createVitePressRouterAdapter({
-      locales,
-      defaultLocale,
-      localeKeyToCode: options.localeKeyToCode,
-      getPath: () => router.route.path,
-      go: (href, navOptions) => router.go(href, navOptions),
-    })
-
-    plugin.setRoutingStrategy(adapter)
-    app.use(plugin)
+    if (!installed) {
+      adapter = createVitePressRouterAdapter({
+        locales,
+        defaultLocale,
+        localeKeyToCode: options.localeKeyToCode,
+        getPath: () => {
+          const route = router.route
+          return `${route.path}${route.query || ''}${route.hash || ''}`
+        },
+        go: (href, navOptions) => router.go(href, navOptions),
+      })
+
+      plugin.setRoutingStrategy(adapter)
+      app.use(plugin)
+      installed = true
+    }
 
-    if (!syncWithVitePress) return
+    if (!syncWithVitePress || !adapter) return
 
     const sync = (path = router.route.path) => {
       if (!adapter) return
       const nextLocale = adapter.getLocaleFromPath(path)
       if (plugin.global.getLocale() !== nextLocale) {
         plugin.global.locale = nextLocale
       }
-      plugin.global.setRoute(routeNameFromPath(path, adapter.localeCodes))
+      plugin.global.setRoute(
+        routeNameFromPath(path, adapter.localeCodes, defaultLocale, options.localeKeyToCode),
+      )
     }
 
     sync()
 
-    const previous = router.onAfterRouteChange
-    router.onAfterRouteChange = async (to: string) => {
-      if (typeof previous === 'function') {
-        await previous(to)
+    // Stay outermost: if base/user enhanceApp overwrote the hook, re-wrap on a later call.
+    const current = router.onAfterRouteChange
+    if (current !== boundSyncHandler) {
+      chainedPrevious = typeof current === 'function' ? current : undefined
+    }
+    boundSyncHandler = async (to: string) => {
+      if (typeof chainedPrevious === 'function') {
+        await chainedPrevious(to)
       }
       const path = to.startsWith('http')
-        ? new URL(to).pathname
-        : to.split(/[?#]/)[0] || '/'
+        ? (() => {
+          const url = new URL(to)
+          return url.pathname + url.search + url.hash
+        })()
+        : to
       sync(path)
     }
+    router.onAfterRouteChange = boundSyncHandler
   }
 
   return {

packages/vitepress/src/define-theme.ts

@@ -49,7 +49,8 @@ export function defineI18nTheme<T extends Theme>(base: T, options: DefineI18nThe
   return {
     ...base,
     async enhanceApp(ctx: EnhanceAppContext) {
-      if (!byApp.has(ctx.app)) {
+      let installed = byApp.get(ctx.app)
+      if (!installed) {
         const [{ config }, messagesMod] = await Promise.all([
           import('virtual:i18n-micro/config') as Promise<{ config: VirtualI18nConfig }>,
           import('virtual:i18n-micro/messages') as Promise<VirtualMessagesModule>,
@@ -58,13 +59,15 @@ export function defineI18nTheme<T extends Theme>(base: T, options: DefineI18nThe
         const localeCodes = config.localeCodes.length
           ? config.localeCodes
           : config.locales.map((l) => l.code)
+        const localeKeyToCode = options.localeKeyToCode ?? config.localeKeyToCode
         const initialLocale = getLocaleFromPath(
           ctx.router.route.path,
           localeCodes,
           config.defaultLocale,
+          localeKeyToCode,
         )
 
-        const installed = createVitePressI18n({
+        installed = createVitePressI18n({
           locale: initialLocale,
           defaultLocale: config.defaultLocale,
           fallbackLocale: config.fallbackLocale,
@@ -73,17 +76,19 @@ export function defineI18nTheme<T extends Theme>(base: T, options: DefineI18nThe
           routeMessages: messagesMod.routeMessages,
           missingWarn: config.missingWarn,
           syncWithVitePress: config.syncWithVitePress,
-          localeKeyToCode: options.localeKeyToCode ?? config.localeKeyToCode,
+          localeKeyToCode,
           plural: options.plural,
           missingHandler: options.missingHandler,
         })
-        // Vue peer version may differ between vitepress and @i18n-micro/vue — ctx shape is compatible at runtime.
-        installed.enhanceApp(ctx as unknown as Parameters<typeof installed.enhanceApp>[0])
         byApp.set(ctx.app, installed)
       }
 
+      // Install plugin first so base/user enhanceApp can use $t / components.
+      installed.enhanceApp(ctx as unknown as Parameters<typeof installed.enhanceApp>[0])
       if (baseEnhance) await baseEnhance(ctx)
       if (userEnhance) await userEnhance(ctx)
+      // Re-run so route sync wraps any onAfterRouteChange set by base/user.
+      installed.enhanceApp(ctx as unknown as Parameters<typeof installed.enhanceApp>[0])
     },
   }
 }

packages/vitepress/src/index.ts

@@ -25,8 +25,6 @@ export { createI18nRoutingFromAdapter } from './router/i18n-routing'
 /** Types only — runtime `withI18nMicro` lives in `@i18n-micro/vitepress/config` (Node). */
 export type { VirtualI18nConfig, VitePressUserConfigLike, WithI18nMicroOptions } from './with-i18n-micro'
 
-/// <reference path="./virtual.d.ts" />
-
 // Re-export Vue surface for a single import path in VitePress themes / MD pages
 export {
   createI18n,