feat(client): add i18n that follows the Devframe hub language

knip.jsonc

@@ -9,6 +9,7 @@
         "local.ts",
         "scripts/*.{js,mjs,ts}",
         "taze.config.ts",
+        "x18n.config.ts",
         "tests/{e2e,docs-screenshots}/**/*.ts"
       ],
       "project": [

package.json

@@ -13,6 +13,7 @@
     "watch": "turbo watch build",
     "dev": "pnpm run build && pnpm -C packages/devtools dev",
     "lint": "eslint --cache .",
+    "i18n:check": "x18n check",
     "knip": "knip",
     "release": "pnpm test && bumpp -r --all",
     "test": "pnpm lint && pnpm test:unit",
@@ -43,6 +44,7 @@
     "@types/node": "catalog:types",
     "@unocss/eslint-config": "catalog:buildtools",
     "@vitejs/devtools-kit": "catalog:types",
+    "@x18n/cli": "catalog:cli",
     "bumpp": "catalog:cli",
     "eslint": "catalog:cli",
     "eslint-flat-config-utils": "catalog:cli",

packages/devtools/client/app.vue

@@ -7,6 +7,7 @@ import { useCopy } from '~/composables/editor'
 import { setupFrameNav } from '~/composables/frame-nav'
 import { WS_DEBOUNCE_TIME } from '~/composables/rpc'
 import { registerCommands } from '~/composables/state-commands'
+import { i18n } from '~/i18n'
 import { wsConnectedOnce } from './composables/rpc'
 import { useSchemaInput } from './composables/state-schema'
 import { useDevToolsOptions } from './composables/storage-options'
@@ -117,7 +118,7 @@ registerCommands(() => [
     ? [
         {
           id: 'action:eye-dropper',
-          title: 'Color Picker',
+          title: i18n.global.t('commands.colorPicker'),
           icon: 'i-carbon-eyedropper',
           action: async () => {
             const { sRGBHex } = await eyeDropper.open() || {}
@@ -130,13 +131,13 @@ registerCommands(() => [
   ...[
     {
       id: 'action:refresh-data',
-      title: 'Refresh Data',
+      title: i18n.global.t('commands.refreshData'),
       icon: 'i-carbon-data-backup',
       action: refreshData,
     },
     {
       id: 'action:reload-page',
-      title: 'Reload Page',
+      title: i18n.global.t('commands.reloadPage'),
       icon: 'i-carbon-reset',
       action: reloadPage,
     },
@@ -148,7 +149,7 @@ registerCommands(() => [
   <div fixed inset-0 h-screen w-screen font-sans>
     <NuxtLoadingIndicator />
     <NLoading v-if="waiting">
-      Connecting....
+      {{ $t('common.connecting') }}
     </NLoading>
     <div
       v-show="!waiting"

packages/devtools/client/components/DisconnectIndicator.vue

@@ -19,16 +19,16 @@ function reload() {
       </div>
       <div flex="~ gap-2" items-center op50>
         <NIcon icon="i-carbon-wifi-off" />
-        Disconnected from Server
+        {{ $t('connection.disconnected') }}
       </div>
       <div border="t base" my2 h-1px w-10 />
       <div flex="~ gap-2" animate-pulse items-center text-xl text-yellow>
         <NIcon icon="i-carbon-circle-dash" animate-spin />
-        Retrying...
+        {{ $t('connection.retrying') }}
       </div>
       <div flex-auto />
       <NButton n="sm yellow" px2 py0 op40 @click="reload()">
-        Reload DevTools Page
+        {{ $t('connection.reload') }}
       </NButton>
     </div>
   </Teleport>

packages/devtools/client/composables/frame-nav.ts

@@ -2,6 +2,7 @@ import type { ModuleBuiltinTab, ModuleCustomTab } from '~/../src/types'
 import { computed, watch } from 'vue'
 import { useRouter } from '#app/composables/router'
 import { useEnabledTabs } from '~/composables/state-tabs'
+import { i18n } from '~/i18n'
 
 // `devframe:frame-nav` — the embedded-app half of the shared-iframe soft-nav
 // protocol (devframe#128 / vitejs/devtools#464). The Vite DevTools dock owns
@@ -31,9 +32,8 @@ interface FrameNavTab {
 }
 
 /** The DevTools settings page, surfaced as its own dock member. */
-const SETTINGS_TAB: FrameNavTab = {
+const SETTINGS_TAB: Omit<FrameNavTab, 'title'> = {
   id: 'settings',
-  title: 'Settings',
   icon: 'carbon:settings',
   category: '~builtin',
   // sort last within its sub-category (higher `order` renders earlier)
@@ -88,7 +88,10 @@ export function setupFrameNav(): void {
         path: tabPath(tab),
       },
     })),
-    SETTINGS_TAB,
+    {
+      ...SETTINGS_TAB,
+      title: i18n.global.t('common.settings'),
+    },
   ])
 
   function currentTabId(): string | undefined {
@@ -138,8 +141,9 @@ export function setupFrameNav(): void {
   // Announce proactively in case the host attached before this shim loaded.
   announce('ready')
 
-  // Re-announce when the conditional tab set changes (show()/settings/etc).
-  watch(() => manifest.value.map(entry => entry.id).join(','), () => announce('manifest'))
+  // Re-announce when the conditional tab set changes (show()/settings/etc),
+  // or when the titles change (the DevTools language was switched).
+  watch(() => manifest.value.map(entry => `${entry.id}:${entry.title}`).join(','), () => announce('manifest'))
 
   // Report in-app navigation so the dock highlight follows.
   watch(() => router.currentRoute.value.path, () => {

packages/devtools/client/composables/locale.ts

@@ -0,0 +1,112 @@
+import type { DevToolsRpcClient } from '@vitejs/devtools-kit/client'
+import type { ComputedRef, Ref } from 'vue'
+import type { DevToolsLocale } from '../i18n/locales'
+import { matchLocale } from '@devframes/hub'
+import { useLocalStorage, useNavigatorLanguage } from '@vueuse/core'
+import { computed, ref, shallowRef, watch } from 'vue'
+import { DEFAULT_LOCALE, DEVFRAME_LOCALE_STORAGE_KEY, DEVTOOLS_LOCALES, LOCALE_AUTO } from '../i18n/locales'
+import { rpcClient } from './rpc'
+
+const available = Object.keys(DEVTOOLS_LOCALES) as DevToolsLocale[]
+
+/** Closest supported DevTools locale for a BCP 47 tag, using Devframe's matching rules. */
+export function matchDevToolsLocale(tag: string | undefined | null): DevToolsLocale | undefined {
+  return matchLocale(tag ?? undefined, available) as DevToolsLocale | undefined
+}
+
+/**
+ * The visitor's language pick, owned by the Devframe hub UI (Settings →
+ * Appearance): `'auto'` or a locale tag. DevTools only reads the hub's own
+ * `localStorage` key, so a change in the hub reaches DevTools live via the
+ * `storage` event.
+ */
+function useLocalePreference(): Ref<string> {
+  try {
+    return useLocalStorage<string>(DEVFRAME_LOCALE_STORAGE_KEY, LOCALE_AUTO, {
+      // Never write: an absent key already means `auto` to the hub.
+      writeDefaults: false,
+      listenToStorageChanges: true,
+    })
+  }
+  catch {
+    // Reading `window.localStorage` throws when the browser blocks storage.
+    // Fall back to `auto` rather than failing the whole client at startup.
+    return ref(LOCALE_AUTO)
+  }
+}
+
+/**
+ * The host's default language, as the server published it in
+ * `__connection.json` (`createUi({ locale })` → `configs.ui.locale`).
+ *
+ * The live `client.connectionMeta` can't be used for this: the running hub UI
+ * overwrites `configs.ui.locale` there with the language it resolved, and an
+ * embedded frame shares the hub's connection object (devframe reads it from
+ * the parent window). Fetching the descriptor again gives the untouched value.
+ */
+async function fetchHostDefault(client: DevToolsRpcClient): Promise<DevToolsLocale | undefined> {
+  try {
+    const response = await fetch(client.connection.metaBaseUrl)
+    if (!response.ok)
+      return undefined
+    const meta = await response.json() as { configs?: { ui?: { locale?: string } } }
+    return matchDevToolsLocale(meta.configs?.ui?.locale)
+  }
+  catch {
+    return undefined
+  }
+}
+
+let resolved: ComputedRef<DevToolsLocale> | undefined
+
+/**
+ * The language DevTools renders in, resolved the same way the Devframe hub UI
+ * resolves its own:
+ *
+ * 1. the visitor's pick in the hub settings (unless `auto`);
+ * 2. the host's default, `configs.ui.locale` in `__connection.json`;
+ * 3. the browser language;
+ * 4. English.
+ */
+export function useDevToolsLocale(): ComputedRef<DevToolsLocale> {
+  if (resolved)
+    return resolved
+
+  const pick = useLocalePreference()
+  const { language } = useNavigatorLanguage()
+
+  const hostDefault = shallowRef<DevToolsLocale>()
+  let hostDefaultRequested = false
+  watch(rpcClient, async (client) => {
+    if (!client || hostDefaultRequested)
+      return
+    hostDefaultRequested = true
+    hostDefault.value = await fetchHostDefault(client)
+  }, { immediate: true })
+
+  resolved = computed<DevToolsLocale>(() => {
+    if (pick.value && pick.value !== LOCALE_AUTO) {
+      const matched = matchDevToolsLocale(pick.value)
+      if (matched)
+        return matched
+    }
+
+    if (hostDefault.value)
+      return hostDefault.value
+
+    // Read `language` unconditionally so the `languagechange` event
+    // re-evaluates this, then prefer the full `navigator.languages` list.
+    const primary = language.value
+    const languages = typeof navigator !== 'undefined' && navigator.languages?.length
+      ? navigator.languages
+      : [primary]
+    for (const tag of languages) {
+      const matched = matchDevToolsLocale(tag)
+      if (matched)
+        return matched
+    }
+
+    return DEFAULT_LOCALE
+  })
+  return resolved
+}

packages/devtools/client/composables/state-commands.ts

@@ -2,6 +2,7 @@ import type { MaybeRefOrGetter } from 'vue'
 import { randomStr } from '@antfu/utils'
 import { computed, onUnmounted, reactive, toValue } from 'vue'
 import { useRouter } from '#app/composables/router'
+import { i18n } from '../i18n'
 import { useEnabledTabs } from './state-tabs'
 
 export interface CommandItem {
@@ -18,24 +19,24 @@ export function useCommands() {
   const tabs = useEnabledTabs()
   const router = useRouter()
 
-  const fixedCommands: CommandItem[] = [
+  const fixedCommands = computed((): CommandItem[] => [
     {
       id: 'fixed:settings',
-      title: 'Settings',
+      title: i18n.global.t('common.settings'),
       icon: 'carbon-settings-adjust',
       action: () => {
         router.push('/settings')
       },
     },
     {
       id: 'fixed:docs',
-      title: 'Nuxt Documentations',
+      title: i18n.global.t('commands.nuxtDocs'),
       icon: 'logos-nuxt-icon',
       action: () => {
         return getNuxtDocsCommands()
       },
     },
-  ]
+  ])
 
   const tabCommands = computed(() => tabs.value
     .map((i): CommandItem => {
@@ -58,7 +59,7 @@ export function useCommands() {
 
   return computed(() => {
     return [
-      ...fixedCommands,
+      ...fixedCommands.value,
       ...tabCommands.value,
       ...[
         ...registeredCommands.values(),

packages/devtools/client/composables/state-tabs.ts

@@ -2,6 +2,7 @@ import type { ModuleBuiltinTab, ModuleCustomTab, RouteInfo, TabCategory } from '
 import { objectPick } from '@antfu/utils'
 import { computed, toValue } from 'vue'
 import { useRouter } from '#app/composables/router'
+import { i18n } from '../i18n'
 import { useClientRouter } from './client'
 import { useCustomTabs, useServerPages } from './state'
 import { useDevToolsOptions } from './storage-options'
@@ -17,11 +18,16 @@ export function useAllTabs() {
       .filter(route => !route.meta.experimental || (route.meta.experimental && settings.showExperimentalFeatures.value))
       .sort((a, b) => (a.meta.order as number || 100) - (b.meta.order as number || 100))
       .map((i): ModuleBuiltinTab => {
+        const name = i.name as string
         return {
-          name: i.name as string,
+          name,
           path: i.path,
           defaultOrder: i.meta.order as number | undefined,
           ...i.meta,
+          // `meta.title` is the English fallback for routes without a message.
+          title: i18n.global.te(`tabs.${name}`)
+            ? i18n.global.t(`tabs.${name}`)
+            : i.meta.title as string,
         }
       }),
     // <ModuleBuiltinTab>{

packages/devtools/client/composables/utils.ts

@@ -158,12 +158,6 @@ export function getComponentRelationships(component: Component, relationships?:
   }
 }
 
-export function pluralizeByCount(count: number, singular: string, plural = `${singular}s`) {
-  return `${count} ${count <= 1
-    ? singular
-    : plural}`
-}
-
 export function refreshData() {
   const client = useClient()
   const nuxt = useNuxtApp()

packages/devtools/client/i18n/index.ts

@@ -0,0 +1,65 @@
+import type { DevToolsLocale } from './locales'
+import { createI18n } from 'vue-i18n'
+import de from '../locales/de.json'
+import en from '../locales/en.json'
+import es from '../locales/es.json'
+import fr from '../locales/fr.json'
+import ja from '../locales/ja.json'
+import ko from '../locales/ko.json'
+import ptBR from '../locales/pt-BR.json'
+import ru from '../locales/ru.json'
+import zhCN from '../locales/zh-CN.json'
+import zhTW from '../locales/zh-TW.json'
+import { DEFAULT_LOCALE } from './locales'
+
+export type MessageSchema = typeof en
+
+const messages: Record<DevToolsLocale, MessageSchema> = {
+  'en': en,
+  'zh-CN': zhCN,
+  'zh-TW': zhTW,
+  'ja': ja,
+  'ko': ko,
+  'es': es,
+  'fr': fr,
+  'de': de,
+  'pt-BR': ptBR,
+  'ru': ru,
+}
+
+/**
+ * Russian has three plural forms: `one | few | many`
+ * (1 страница, 2 страницы, 5 страниц).
+ */
+function russianPlural(choice: number, choicesLength: number): number {
+  if (choicesLength < 3) {
+    return choice === 1
+      ? 0
+      : 1
+  }
+  const mod10 = choice % 10
+  const mod100 = choice % 100
+  if (mod10 === 1 && mod100 !== 11)
+    return 0
+  if (mod10 >= 2 && mod10 <= 4 && (mod100 < 10 || mod100 >= 20))
+    return 1
+  return 2
+}
+
+/**
+ * The single i18n instance of the DevTools client. Exported so composables
+ * running outside a component (tab lists, commands) can translate with
+ * `i18n.global.t`, which stays reactive to locale changes.
+ */
+export const i18n = createI18n<[MessageSchema], DevToolsLocale, false>({
+  legacy: false,
+  globalInjection: true,
+  locale: DEFAULT_LOCALE,
+  fallbackLocale: DEFAULT_LOCALE,
+  messages,
+  pluralRules: {
+    ru: russianPlural,
+  },
+  missingWarn: false,
+  fallbackWarn: false,
+})