@bndynet/vue-site 1.0.2 → 1.2.0

package/bin/vue-site.mjs

@@ -5,7 +5,7 @@ import vue from '@vitejs/plugin-vue'
 import { resolve, dirname, basename } from 'path'
 import { fileURLToPath, pathToFileURL } from 'url'
 import { createRequire } from 'module'
-import { transform } from 'esbuild'
+import { build as esbuild } from 'esbuild'
 import fs from 'fs'
 
 const __filename = fileURLToPath(import.meta.url)
@@ -166,6 +166,29 @@ function resolveBootstrapUrl(path) {
   return '/' + t.replace(/^\.\//, '')
 }
 
+// Friendly display names for auto-discovered locale files (`/locales/<code>.json`). Used only when
+// the config doesn't declare `i18n.locales`; unknown codes fall back to the code itself.
+const LOCALE_LABELS = {
+  en: 'English',
+  zh: '简体中文',
+  'zh-CN': '简体中文',
+  'zh-TW': '繁體中文',
+  ja: '日本語',
+  ko: '한국어',
+  fr: 'Français',
+  de: 'Deutsch',
+  es: 'Español',
+  pt: 'Português',
+  ru: 'Русский',
+  it: 'Italiano',
+  nl: 'Nederlands',
+  pl: 'Polski',
+  tr: 'Türkçe',
+  vi: 'Tiếng Việt',
+  th: 'ไทย',
+  ar: 'العربية',
+}
+
 /**
  * Bootstrap script shared by dev (virtual entry) and build (inlined in html).
  * `siteConfigSpecifier` differs because dev serves from Vite root (`/foo`)
@@ -173,6 +196,11 @@ function resolveBootstrapUrl(path) {
  *
  * Static import bundles `bootstrap` for production; dynamic import with
  * vite-ignore is not emitted.
+ *
+ * Convention: translations are auto-loaded from `/locales/<code>.json` (relative to the Vite root,
+ * i.e. the config's directory). The user writes zero glue code — no `index.ts`, no `messages` field.
+ * An explicit `i18n.messages` still works and overrides auto-loaded keys; an explicit `i18n.locales`
+ * still controls the label/icon/order, otherwise the locale list is derived from the file names.
  */
 function buildBootstrapScript({ siteConfig, siteConfigSpecifier }) {
   const bs = siteConfig?.bootstrap
@@ -189,6 +217,43 @@ function buildBootstrapScript({ siteConfig, siteConfigSpecifier }) {
     `import '${pkgDirUrl}/dist/style.css'`,
     `import siteConfig from '${siteConfigSpecifier}'`,
     `import { repositoryUrl } from '${VIRTUAL_PACKAGE}'`,
+    ``,
+    `// Auto-discover translations: /locales/<code>.json -> { [code]: { ...messages } }.`,
+    `const __localeFiles = import.meta.glob('/locales/*.json', { eager: true, import: 'default' })`,
+    `const __LOCALE_LABELS = ${JSON.stringify(LOCALE_LABELS)}`,
+    `const __autoMessages = {}`,
+    `for (const __p in __localeFiles) {`,
+    `  const __code = __p.slice(__p.lastIndexOf('/') + 1).replace(/\\.json$/, '')`,
+    `  __autoMessages[__code] = __localeFiles[__p]`,
+    `}`,
+    `const __autoCodes = Object.keys(__autoMessages).sort()`,
+    `function __deepMerge(base, override) {`,
+    `  const out = { ...base }`,
+    `  for (const k in (override || {})) {`,
+    `    const a = out[k], b = override[k]`,
+    `    out[k] = a && b && typeof a === 'object' && typeof b === 'object' && !Array.isArray(a) && !Array.isArray(b)`,
+    `      ? __deepMerge(a, b) : b`,
+    `  }`,
+    `  return out`,
+    `}`,
+    `function __mergeMessages(base, override) {`,
+    `  const out = {}`,
+    `  const keys = new Set([...Object.keys(base), ...Object.keys(override || {})])`,
+    `  for (const k of keys) out[k] = __deepMerge(base[k] || {}, (override || {})[k] || {})`,
+    `  return out`,
+    `}`,
+    `// Merge auto-loaded files into i18n. Explicit config wins: messages override per key, and an`,
+    `// explicit locales list controls label/icon/order (else it's derived from the file names).`,
+    `function __resolveI18n(cfg) {`,
+    `  const hasAuto = __autoCodes.length > 0`,
+    `  if (!cfg && !hasAuto) return cfg`,
+    `  const base = cfg || {}`,
+    `  let locales = base.locales`,
+    `  if ((!locales || !locales.length) && hasAuto) {`,
+    `    locales = __autoCodes.map((c) => ({ code: c, label: __LOCALE_LABELS[c] || c }))`,
+    `  }`,
+    `  return { ...base, locales, messages: __mergeMessages(__autoMessages, base.messages) }`,
+    `}`,
     `;(async () => {`,
     `  const searchParams = new URLSearchParams(window.location.search)`,
     `  const hasThemeQuery = searchParams.has('theme')`,
@@ -203,6 +268,7 @@ function buildBootstrapScript({ siteConfig, siteConfigSpecifier }) {
     `  }`,
     `  const app = await createSiteApp({`,
     `    ...siteConfig,`,
+    `    i18n: __resolveI18n(siteConfig.i18n),`,
     `    ...(hasThemeQuery ? { theme: { ...(siteConfig.theme || {}), default: resolvedTheme } } : {}),`,
     `    packageRepository: repositoryUrl,`,
     `    baseUrl: import.meta.env.BASE_URL,`,
@@ -238,39 +304,167 @@ const htmlTemplate = buildHtmlShell(
   `<script type="module" src="/@id/__x00__${VIRTUAL_ENTRY}"></script>`,
 )
 
+// esbuild plugin stubbing asset / SFC / `?raw` imports (static or dynamic) to an empty default
+// export, so bundling the config for pre-load doesn't choke on resources Node can't load. Page
+// loaders are never invoked during pre-load (only build-time settings are read).
+function preloadAssetStubPlugin() {
+  const NS = 'vue-site-asset'
+  const ASSET =
+    /\?raw(?:&\S*)?$|\.(?:vue|css|scss|sass|less|styl|md|markdown|png|jpe?g|gif|svg|webp|avif|ico)(?:\?\S*)?$/
+  return {
+    name: 'vue-site:preload-asset-stub',
+    setup(b) {
+      b.onResolve({ filter: ASSET }, (args) => ({ path: args.path, namespace: NS }))
+      b.onLoad({ filter: /.*/, namespace: NS }, () => ({
+        contents: 'export default ""',
+        loader: 'js',
+      }))
+    },
+  }
+}
+
 async function loadSiteConfig() {
   const configPath = resolve(cwd, foundConfig)
   const raw = fs.readFileSync(configPath, 'utf-8')
 
-  const isTs = /\.m?ts$/.test(foundConfig)
-  const { code } = await transform(raw, {
-    loader: isTs ? 'ts' : 'js',
-    format: 'esm',
-  })
-
-  const stubbed = code.replace(
-    /import\s*\{[^}]*defineConfig[^}]*\}\s*from\s*['"][^'"]*['"]\s*;?/g,
-    'const defineConfig = (c) => c;',
+  // Stub the framework's value imports so the config evaluates without the real (browser-only)
+  // package. `defineConfig` is identity (the config object passes through); every other named
+  // import (e.g. `tk`, `localizedPage`) becomes a callable no-op that returns a no-op, covering
+  // helpers used as values. Relative imports (e.g. `./locales`) are left intact and bundled below.
+  let stubbed = raw.replace(
+    /import\s*\{([^}]*)\}\s*from\s*['"][^'"]*vue-site['"]\s*;?/g,
+    (_match, names) => {
+      const ids = names
+        .split(',')
+        .map((part) => part.trim())
+        .filter(Boolean)
+        .map((part) => {
+          const segments = part.split(/\s+as\s+/)
+          return (segments[1] ?? segments[0]).trim()
+        })
+        .filter(Boolean)
+      return ids
+        .map((id) =>
+          id === 'defineConfig'
+            ? 'const defineConfig = (c) => c;'
+            : `const ${id} = (..._args) => (() => {});`,
+        )
+        .join('\n')
+    },
   )
 
-  const tmpFile = resolve(cwd, `.site-config.${Date.now()}.tmp.mjs`)
-  fs.writeFileSync(tmpFile, stubbed)
+  // `import.meta.glob(...)` is a Vite-only feature; in Node it would throw at config-eval time.
+  // Stub it to an empty map so configs using `localizedPageGlob(import.meta.glob(...))` pre-load
+  // (page loaders are never invoked here — only build-time settings are read). The real glob runs
+  // in the browser via Vite.
+  if (/import\.meta\.glob/.test(stubbed)) {
+    stubbed =
+      'const __vueSiteGlobStub = (..._args) => ({});\n' +
+      stubbed.replace(/import\.meta\.glob/g, '__vueSiteGlobStub')
+  }
+
+  const isTs = /\.m?ts$/.test(foundConfig)
+  // Write the stubbed entry next to the original so its relative imports (`./locales`) resolve.
+  const entryFile = resolve(
+    dirname(configPath),
+    `.${basename(configPath)}.${Date.now()}.preload.${isTs ? 'ts' : 'js'}`,
+  )
+  const tmpDir = resolve(cwd, `.vue-site-preload-${Date.now()}`)
+  fs.writeFileSync(entryFile, stubbed)
 
   try {
-    const mod = await import(pathToFileURL(tmpFile).href)
+    // Bundle so local modules the config imports (e.g. `./locales.ts`) are inlined and TS is
+    // handled; asset imports are stubbed; remaining bare deps stay external for Node to resolve.
+    await esbuild({
+      entryPoints: { 'site-config': entryFile },
+      outdir: tmpDir,
+      bundle: true,
+      format: 'esm',
+      platform: 'node',
+      splitting: true,
+      logLevel: 'silent',
+      packages: 'external',
+      outExtension: { '.js': '.mjs' },
+      plugins: [preloadAssetStubPlugin()],
+    })
+
+    const entry = resolve(tmpDir, 'site-config.mjs')
+    const mod = await import(pathToFileURL(entry).href)
     return mod.default || {}
   } catch (e) {
-    console.warn(
-      `[vue-site] Could not pre-load site config from ${foundConfig}: ${e.message}`,
+    throw new Error(
+      `[vue-site] Could not pre-load site config from ${foundConfig}: ${e.message}\n` +
+        `  This usually means your config imports modules Node can't resolve directly ` +
+        `(path aliases like @/..., or framework APIs other than defineConfig).`,
     )
-    return {}
   } finally {
     try {
-      fs.unlinkSync(tmpFile)
+      fs.unlinkSync(entryFile)
+    } catch {}
+    try {
+      fs.rmSync(tmpDir, { recursive: true, force: true })
     } catch {}
   }
 }
 
+/**
+ * Turn a base file path into a `import.meta.glob(...)` expression matching the base file plus its
+ * per-locale siblings (`name.<code>.ext`) — but NOT unrelated `nameOther.ext`:
+ *   `../README.md`     -> import.meta.glob(["../README.md","../README.*.md"], { query: '?raw' })
+ *   `./pages/Home.vue` -> import.meta.glob(["./pages/Home.vue","./pages/Home.*.vue"], {})
+ * Markdown is loaded `?raw` (string content); other files (e.g. `.vue`) export a component.
+ * Returns `null` when the path has no extension (can't build a sensible glob).
+ */
+function fileToLocaleGlobExpr(rawPath) {
+  const qIdx = rawPath.indexOf('?')
+  const query = qIdx >= 0 ? rawPath.slice(qIdx + 1) : ''
+  const pathOnly = qIdx >= 0 ? rawPath.slice(0, qIdx) : rawPath
+  const dot = pathOnly.lastIndexOf('.')
+  if (dot <= pathOnly.lastIndexOf('/')) return null
+  const ext = pathOnly.slice(dot)
+  const globs = [pathOnly, `${pathOnly.slice(0, dot)}.*${ext}`]
+  const isMarkdown = /\.(?:md|markdown)$/i.test(ext) || /(?:^|&)raw(?:$|&)/.test(query)
+  const opts = isMarkdown ? `{ query: '?raw' }` : `{}`
+  return `import.meta.glob(${JSON.stringify(globs)}, ${opts})`
+}
+
+// Sugar so configs can name page files as plain strings; the CLI turns them into Vite globs so the
+// per-locale files get bundled. Two shapes are rewritten in the user's JS/TS under `cwd`:
+//   localizedPage('./file.md')  -> localizedPage(import.meta.glob([...], { query: '?raw' }))
+//   page: './file.md'           -> page: import.meta.glob([...], { query: '?raw' })
+// Loader functions, locale maps (`localizedPage({ en, zh })`) and explicit `import.meta.glob` are
+// left untouched; the `page:` form only rewrites path-like values (starting with `.` or `/`).
+function localizedPageSugarPlugin() {
+  const CALL_STRING_ARG = /(\blocalizedPage\s*\(\s*)(['"`])((?:\\.|(?!\2).)*)\2/g
+  const PAGE_STRING_FIELD = /(\bpage\s*:\s*)(['"`])((?:\\.|(?!\2).)*)\2/g
+  return {
+    name: 'vue-site:localized-page-sugar',
+    enforce: 'pre',
+    transform(code, id) {
+      const file = id.split('?')[0]
+      if (!/\.(?:[cm]?[jt]sx?)$/.test(file)) return
+      if (!file.startsWith(cwd) || file.includes('/node_modules/')) return
+      if (!code.includes('localizedPage(') && !/\bpage\s*:\s*['"`]/.test(code)) return
+      let changed = false
+      let out = code.replace(CALL_STRING_ARG, (match, head, _q, rawPath) => {
+        const expr = fileToLocaleGlobExpr(rawPath)
+        if (!expr) return match
+        changed = true
+        return `${head}${expr}`
+      })
+      out = out.replace(PAGE_STRING_FIELD, (match, head, _q, rawPath) => {
+        // Only rewrite path-like values to avoid touching unrelated `page: '...'` properties.
+        if (!/^[./]/.test(rawPath)) return match
+        const expr = fileToLocaleGlobExpr(rawPath)
+        if (!expr) return match
+        changed = true
+        return `${head}${expr}`
+      })
+      return changed ? { code: out, map: null } : undefined
+    },
+  }
+}
+
 function vueSitePlugin(entryCode) {
   return [
     {
@@ -458,7 +652,7 @@ async function buildViteConfig(options = {}) {
 
   const baseConfig = {
     root: cwd,
-    plugins: [vue(vueOpts), ...watchedScssPlugin, ...vueSitePlugin(entryCode), ...(userPlugins || [])],
+    plugins: [localizedPageSugarPlugin(), vue(vueOpts), ...watchedScssPlugin, ...vueSitePlugin(entryCode), ...(userPlugins || [])],
     resolve: {
       alias: {
         vue: resolve(vuePath, 'dist/vue.runtime.esm-bundler.js'),

package/dist/components/LocaleSwitch.vue.d.ts

@@ -0,0 +1,10 @@
+type __VLS_Props = {
+    compact?: boolean;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    compact: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    detailsRef: HTMLDetailsElement;
+    summaryRef: HTMLElement;
+}, HTMLDetailsElement>;
+export default _default;

package/dist/composables/useLocale.d.ts

@@ -0,0 +1,19 @@
+import { InjectionKey, Ref } from 'vue';
+/** Use `Symbol.for` so the key matches even if multiple copies of this package are resolved. */
+export declare const localeRefKey: InjectionKey<Ref<string>>;
+/**
+ * Resolve and apply the initial locale (stored > detected > default), then keep `localeRef`
+ * authoritative. Call once from `createSiteApp` when `i18n` is configured.
+ *
+ * @param localeRef — ref created next to `createApp` so it uses the same Vue runtime as the app.
+ * @param defaultLocale — used when nothing valid is in localStorage and detection finds no match.
+ * @param locales — full list of allowed locale codes.
+ * @param detectBrowser — try `navigator.language(s)` before falling back to `defaultLocale`.
+ * @param key — localStorage key for persistence (default `vue-site-locale`).
+ */
+export declare function initLocale(localeRef: Ref<string>, defaultLocale: string, locales: readonly string[], detectBrowser?: boolean, key?: string): void;
+export declare function useLocale(): {
+    locale: Ref<string, string>;
+    setLocale: (code: string) => void;
+    locales: () => string[];
+};

package/dist/composables/useLocalize.d.ts

@@ -0,0 +1,18 @@
+import { LocalizedString } from '../types';
+/**
+ * Reactively resolve localized content against the active locale. Returns:
+ *
+ * - `localize(value)` — resolve a `LocalizedString` (locale map, plain string, or a `tk()` key
+ *   reference); plain strings pass through unchanged.
+ * - `t(id, params?)` — resolve a UI message id from `SiteConfig.i18n.messages` layered over the
+ *   framework's built-in strings, with locale fallback (exact → primary-subtag → default → `en`)
+ *   and `{name}` placeholder interpolation.
+ * - `locale` — the active locale ref.
+ *
+ * Reading these inside a template/computed makes the output update automatically on language change.
+ */
+export declare function useLocalize(): {
+    localize: (value: LocalizedString | undefined) => string;
+    t: (id: string, params?: Record<string, string | number>) => string;
+    locale: import('vue').Ref<string, string>;
+};

package/dist/i18n-messages.d.ts

@@ -0,0 +1,9 @@
+import { LocaleCode } from './types';
+/**
+ * Built-in UI strings for framework chrome (theme/locale switchers, page errors). Keyed by locale
+ * then message id. Consumers override or extend these per locale via `SiteConfig.i18n.messages`,
+ * which is merged on top of these defaults. Unknown locales fall back to `en`.
+ *
+ * Body strings may contain `{name}` placeholders, interpolated by `useLocalize().t(id, params)`.
+ */
+export declare const builtinMessages: Record<LocaleCode, Record<string, string>>;

package/dist/i18n-utils.d.ts

@@ -0,0 +1,81 @@
+import { Component } from 'vue';
+import { LocaleCode, LocalizedString, MessageRef, MessageTree, PageLoader } from './types';
+/** Merged, flattened message dictionaries keyed by locale then dotted message id. */
+export type MessageCatalog = Record<LocaleCode, Record<string, string>>;
+/**
+ * Flatten a (possibly nested) message tree to dotted ids: `{ site: { title: 'x' } }` → `site.title`.
+ * Flat dictionaries pass through unchanged, so both layouts can be mixed.
+ */
+export declare function flattenMessages(tree: MessageTree | undefined, prefix?: string): Record<string, string>;
+/** Type guard for a {@link MessageRef} (a `{ $t }` key reference). */
+export declare function isMessageRef(value: unknown): value is MessageRef;
+/** Build a `MessageRef` referencing a central message id; use in `LocalizedString` config fields. */
+export declare function tk(id: string, params?: Record<string, string | number>): MessageRef;
+/**
+ * Merge `override` message trees on top of `base`, per locale, flattening nested groups to dotted
+ * ids. Returns a flat {@link MessageCatalog} ready for {@link resolveMessage}.
+ */
+export declare function mergeCatalog(base: Record<LocaleCode, MessageTree>, override?: Record<LocaleCode, MessageTree>): MessageCatalog;
+/**
+ * Resolve a message id from a merged `catalog` for the active locale, with fallback
+ * (exact → primary-subtag → `defaultLocale` → `en` → the id itself) and `{name}` interpolation.
+ */
+export declare function resolveMessage(catalog: MessageCatalog, id: string, locale: string, defaultLocale?: LocaleCode, params?: Record<string, string | number>): string;
+/**
+ * Resolve a `LocalizedString` to a plain string for the active `locale`.
+ *
+ * A bare `string` is returned unchanged. For a locale map, resolution order is:
+ * exact locale → primary-subtag match (e.g. `en-US` → `en`) → `defaultLocale` → first entry → `''`.
+ * A {@link MessageRef} is returned as its raw id here (use {@link resolveField} with a catalog to
+ * resolve it). This keeps single-language configs (plain strings) working without locale context.
+ */
+export declare function resolveLocalized(value: LocalizedString | undefined, locale: string, defaultLocale?: LocaleCode): string;
+/**
+ * Resolve any `LocalizedString` — including a {@link MessageRef} — against the active locale.
+ * Plain strings and locale maps go through {@link resolveLocalized}; key references are resolved
+ * from the merged message `catalog` via {@link resolveMessage}.
+ */
+export declare function resolveField(value: LocalizedString | undefined, locale: string, defaultLocale?: LocaleCode, catalog?: MessageCatalog): string;
+/** Options for {@link localizedPage}. */
+export interface LocalizedPageOptions {
+    /** Locale to fall back to when the active locale has no entry (else the first entry is used). */
+    defaultLocale?: LocaleCode;
+}
+/**
+ * Build a per-locale page loader for `NavItem.page` / `StandalonePage.page`. The returned loader
+ * receives the active locale and resolves the matching content, with graceful fallback. Three forms:
+ *
+ * - **File name** (recommended, simplest) — `localizedPage('../README.md')`. The **vue-site CLI**
+ *   rewrites this to a glob, so every `README.<code>.md` sitting next to the base file is picked up
+ *   automatically (e.g. `README.zh.md` → `zh`); a locale with no file falls back to the base file
+ *   (`README.md`). Add a language by dropping in a file — no config edits. Works for Markdown
+ *   (`.md`, loaded as `?raw`) and Vue pages (`.vue`). _Only the CLI understands this form; in
+ *   library mode use the glob form below._
+ * - **Glob map** — `localizedPage(import.meta.glob('../README*.md', { query: '?raw' }))`. Same
+ *   behavior as the file-name form, written explicitly (use this in library mode). Pass a **lazy**
+ *   glob whose modules expose `{ default }`.
+ * - **Locale map** — `localizedPage({ en: () => import('...'), zh: () => import('...') })` for files
+ *   that don't share a base name.
+ *
+ * @example
+ * // Simplest (via the CLI): ../README.md (base) + ../README.zh.md + ../README.ja.md + ...
+ * page: localizedPage('../README.md')
+ *
+ * @example
+ * // Explicit locale map
+ * page: localizedPage({
+ *   en: () => import('./pages/guide.en.md?raw'),
+ *   zh: () => import('./pages/guide.zh.md?raw'),
+ * })
+ */
+export declare function localizedPage(file: string, options?: LocalizedPageOptions): PageLoader;
+export declare function localizedPage(loaders: Record<LocaleCode, () => Promise<{
+    default: string;
+}>>, options?: LocalizedPageOptions): (locale: LocaleCode) => Promise<{
+    default: string;
+}>;
+export declare function localizedPage(loaders: Record<LocaleCode, () => Promise<{
+    default: Component;
+}>>, options?: LocalizedPageOptions): (locale: LocaleCode) => Promise<{
+    default: Component;
+}>;

package/dist/index.d.ts

@@ -1,8 +1,13 @@
 import { SiteConfig } from './types';
 export { createSiteApp } from './create-app';
 export { useTheme, themeRefKey } from './composables/useTheme';
+export { useLocale, localeRefKey } from './composables/useLocale';
+export { useLocalize } from './composables/useLocalize';
+export { resolveLocalized, resolveField, resolveMessage, mergeCatalog, flattenMessages, tk, isMessageRef, localizedPage } from './i18n-utils';
+export type { LocalizedPageOptions, MessageCatalog } from './i18n-utils';
+export { builtinMessages } from './i18n-messages';
 export { useSiteConfig } from './composables/useSiteConfig';
 export { builtinThemePalettes } from './theme/presets';
 export { ElMessage, ElMessageBox, ElNotification, } from 'element-plus';
-export type { SiteConfig, SiteEnvConfig, SiteViteConfig, SiteExternalLink, NavItem, StandalonePage, AuthRule, AuthContext, AuthConfig, RouterConfig, ThemeConfig, ThemeOption, ThemePaletteVars, ResolvedNavItem, } from './types';
+export type { SiteConfig, SiteEnvConfig, SiteViteConfig, SiteExternalLink, NavItem, StandalonePage, AuthRule, AuthContext, AuthConfig, RouterConfig, ThemeConfig, ThemeOption, ThemePaletteVars, ResolvedNavItem, LocaleCode, LocalizedString, MessageRef, MessageTree, LocaleOption, I18nConfig, PageLoader, } from './types';
 export declare function defineConfig(config: SiteConfig): SiteConfig;