@bndynet/vue-site 1.0.4 → 1.2.0

package/README.md

@@ -10,6 +10,7 @@ Configurable Vue 3 site framework: one package, `site.config.ts`, and Markdown p
 - Hash or HTML5 (`web`) router history, configurable in `site.config.ts`
 - Markdown (`?raw`) or Vue pages
 - highlight.js, light/dark theme + localStorage
+- Built-in multi-language support (locale switcher, `LocalizedString` config, per-locale pages) — see [Internationalization](#internationalization-i18n)
 - Project `README.md` as Home
 - Full TypeScript types
 
@@ -69,14 +70,15 @@ Add `"dev": "vue-site dev"` (or `vs dev`) in `package.json` scripts if you like.
 
 | Property | Description |
 |----------|-------------|
-| `title` | Site title (sidebar + tab) |
+| `title` | Site title (sidebar + tab). `LocalizedString` |
 | `nav` | `NavItem[]` |
 | `defaultPath` | Path the site opens at; `/` and unknown paths redirect here. Must match a registered route (a `nav` item's resolved path or a `pages` entry's `path`). Defaults to the first top-level `nav` item |
 | `logo` | Logo URL or imported image |
 | `theme` | See `ThemeConfig` below; set to `false` to disable theming (hides the switcher, forces a fixed `light` palette, no localStorage persistence) |
-| `footer` | Footer text |
+| `i18n` | Multi-language config (`I18nConfig`) — see [Internationalization](#internationalization-i18n) |
+| `footer` | Footer text. `LocalizedString` |
 | `readme` | Raw Home content if no `README.md` |
-| `links` | Header links: Lucide `icon` + `link`, optional `title` |
+| `links` | Header links: Lucide `icon` + `link`, optional `title` (`LocalizedString`) |
 | `pages` | `StandalonePage[]` — full-screen routes outside the `nav` tree (no top bar/sidebar/footer) |
 | `auth` | Central authorization policy (`AuthConfig`) — see [Per-page authorization](#per-page-authorization-auth) |
 | `router` | History mode (`RouterConfig`) — `hash` (default) or HTML5 `web`; see [Router history](#router-history-router) |
@@ -89,10 +91,10 @@ Add `"dev": "vue-site dev"` (or `vs dev`) in `package.json` scripts if you like.
 
 | Property | Description |
 |----------|-------------|
-| `label` | Sidebar text |
+| `label` | Sidebar text. `LocalizedString` |
 | `icon` | [Lucide](https://lucide.dev/icons) name |
-| `page` | `() => import('./page.md?raw')` or `() => import('./Page.vue')` |
-| `path` | Route path (derived from `label` if omitted) |
+| `page` | Page content. Simplest is a **file-path string** like `'./pages/AdminView.vue'` or `'./README.md'` (auto-loads per-locale siblings, falls back to the base file). Also accepts a loader (`() => import('./Page.vue')` / `() => import('./page.md?raw')`) or a `localizedPage(...)` result. See [Per-locale page content](#per-locale-page-content) and [Advanced page loaders](#advanced-page-loaders) |
+| `path` | Route path (derived from `label`'s default-locale value if omitted; stays stable across languages) |
 | `children` | Nested group |
 | `link` | Render as a hyperlink (internal route path or external URL) instead of a page route |
 | `visible` | `() => boolean \| Promise<boolean>`, awaited once at startup. Return `false` to hide the item from the nav and skip its route (not reachable by direct URL). A hidden parent hides its subtree; a group with no remaining children is pruned. Not reactive to later changes. |
@@ -109,6 +111,220 @@ Built-in themes are `light`, `dark`, plus the always-on extras `sepia` and `ocea
 | `palettes` | — | Partial overrides for built-in light/dark only |
 | `extraThemes` | — | Extra themes: `id`, `label`, `icon`, optional `basedOn`, `palette`; reuse a built-in id (`sepia`/`ocean`) to override it. Import `builtinThemePalettes` for full defaults |
 
+## Internationalization (`i18n`)
+
+Set `i18n` to enable multi-language support. The framework adds a locale switcher to the header,
+resolves every `LocalizedString` field (`title`, `nav[].label`, `footer`, `links[].title`) against
+the active locale, and exposes the current locale via `useLocale()` / `useLocalize()`.
+
+```typescript
+import { defineConfig } from '@bndynet/vue-site'
+
+export default defineConfig({
+  i18n: {
+    locales: [
+      { code: 'en', label: 'English' },
+      { code: 'zh', label: '简体中文', icon: 'languages' },
+    ],
+    defaultLocale: 'en',
+  },
+  title: { en: 'My Site', zh: '我的站点' }, // a LocalizedString
+  footer: { en: '© 2026', zh: '© 2026 版权所有' },
+  nav: [
+    { label: { en: 'Home', zh: '首页' }, icon: 'home', page: '../README.md' },
+    {
+      label: { en: 'Guide', zh: '指南' },
+      icon: 'book',
+      // Per-locale content: ./pages/guide.md (base) + guide.zh.md, auto-discovered by the CLI.
+      page: './pages/guide.md',
+    },
+  ],
+})
+```
+
+### Per-locale page content
+
+Point `page` at a **file-path string** and the framework serves the right file for the active
+locale — no extra wiring:
+
+```typescript
+import { defineConfig, tk } from '@bndynet/vue-site'
+
+export default defineConfig({
+  i18n: { locales: [{ code: 'en' }, { code: 'zh' }], defaultLocale: 'en' },
+  nav: [
+    // Loads ../README.md, and auto-uses ../README.zh.md when the active locale is `zh`.
+    { label: tk('nav.home'), icon: 'home', page: '../README.md' },
+    // Vue pages work the same way: Dashboard.vue + Dashboard.zh.vue.
+    { label: tk('nav.dash'), icon: 'gauge', page: './pages/Dashboard.vue' },
+  ],
+})
+```
+
+- Name the variants `name.<code>.<ext>` next to the base file — `README.zh.md`, `Dashboard.zh.vue`, …
+- A locale with no matching file falls back to the **base file** (`README.md`). Resolution order:
+  exact → primary-subtag (`zh-TW` → `zh`) → base file.
+- **Add a language by dropping in a `name.<code>` file — no config changes.**
+- Works for Markdown (`.md`) and Vue (`.vue`). The base name must not contain dots (`README.md` ✓,
+  `my.page.md` ✗).
+
+> The string form is resolved by the `vue-site` CLI at build time. If you embed the library yourself
+> (no CLI — see [library mode](#library-mode)), use a loader from
+> [Advanced page loaders](#advanced-page-loaders) instead.
+
+### Advanced page loaders
+
+> **Rarely needed.** The file-path string above covers most sites. Reach for these only when you
+> want a plain single-file loader, files that **don't** share a base name, or you run **without** the
+> CLI (library mode).
+
+Besides a string, `page` accepts a **loader function** or a `localizedPage(...)` result:
+
+- **Single file, no localization** — a plain dynamic import:
+
+  ```typescript
+  page: () => import('./pages/Dashboard.vue')   // or () => import('./guide.md?raw') for Markdown
+  ```
+
+- **Explicit locale map** — for files that don't share a base name (so the string form can't infer
+  them):
+
+  ```typescript
+  import { localizedPage } from '@bndynet/vue-site'
+
+  page: localizedPage({
+    en: () => import('./pages/guide-en.md?raw'),
+    zh: () => import('./pages/guide-zh.md?raw'),
+  })
+  ```
+
+- **Glob (library mode)** — the same auto-discovery as the string form, written out so it works
+  without the CLI:
+
+  ```typescript
+  page: localizedPage(import.meta.glob(['../README.md', '../README.*.md'], { query: '?raw' }))
+  ```
+
+  `page: '../README.md'` is exactly this, generated for you by the CLI. (For Vue pages drop the
+  `{ query: '?raw' }`.)
+
+All `localizedPage` forms fall back when the active locale has no file (exact → primary-subtag →
+base file → first entry).
+
+### How it works
+
+- **Initial locale**: stored choice (localStorage) > browser language (`navigator.language`, when
+  `detectBrowser` is on) > `defaultLocale` > first entry.
+- **`LocalizedString`** is `string | Record<LocaleCode, string> | MessageRef`. A plain string is
+  returned as-is (single-language configs keep working), a locale map holds inline per-language
+  text, and a `MessageRef` (built with `tk('id')`) references a key from a central message file —
+  see [Centralized message files](#centralized-message-files-tk--t).
+- **Stable URLs**: route paths derive from the **default-locale** label (or an explicit `path`), so
+  switching language never changes URLs.
+- **Reactive**: switching language updates labels, the title, the footer, and page content live
+  (page content reloads via `localizedPage`). The switcher only appears when `locales.length > 1`.
+- **UI strings**: the framework ships built-in strings (currently `en`, `zh`) for the theme/locale
+  switchers and page errors; override or extend them per locale via `i18n.messages`.
+
+### `I18nConfig`
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `locales` | discovered `locales/*.json` | `{ code, label, icon? }[]` — supported languages, in display order. Optional: derived from the auto-loaded file names (with built-in labels) when omitted. First entry is the fallback |
+| `defaultLocale` | `locales[0].code` | Initial locale when nothing is stored and detection finds no match |
+| `detectBrowser` | `true` | Detect the initial locale from `navigator.language(s)` on first visit |
+| `storageKey` | `vue-site-locale` | localStorage key for the chosen locale |
+| `messages` | auto-loaded from `locales/<code>.json` | `Record<LocaleCode, Record<string, string>>` — extra/override translations, merged over the auto-loaded files and built-in UI strings |
+
+### Message files & keys (`tk` / `t`)
+
+Instead of inlining `{ en, zh }` everywhere, keep all translations in plain JSON — **one file per
+language** — and reference them by key. This is zero-config: the CLI auto-discovers
+`locales/<code>.json` next to your `site.config.ts`. You don't write any glue code (no `index.ts`,
+no `messages` field) and you don't even have to list the languages.
+
+```jsonc
+// locales/en.json — nested groups (recommended), flattened to dotted ids
+{
+  "site": { "title": "My Site" },
+  "nav": { "home": "Home", "guide": "Guide" }
+}
+```
+
+```jsonc
+// locales/zh.json
+{
+  "site": { "title": "我的站点" },
+  "nav": { "home": "首页", "guide": "指南" }
+}
+```
+
+> Files may be **nested** (above) or **flat** (`{ "site.title": "My Site" }`) — nested groups are
+> flattened to dotted ids, so `tk('site.title')` / `t('site.title')` work either way.
+
+```typescript
+// site.config.ts — reference keys with tk() in config and t() in pages
+import { defineConfig, tk } from '@bndynet/vue-site'
+
+export default defineConfig({
+  // `i18n` can be omitted entirely: the language list is derived from the file names
+  // (en, zh, ...) with friendly built-in labels. Declare it only to customize label/icon/order.
+  i18n: {
+    locales: [
+      { code: 'en', label: 'English' },
+      { code: 'zh', label: '简体中文', icon: 'languages' },
+    ],
+    defaultLocale: 'en',
+  },
+  title: tk('site.title'),
+  nav: [
+    { label: tk('nav.home'), icon: 'home', page: '../README.md' },
+    {
+      label: tk('nav.guide'),
+      icon: 'book',
+      page: './pages/guide.md',
+    },
+  ],
+})
+```
+
+Key resolution falls back through the active locale's primary subtag → `defaultLocale` → `en` → the
+id itself, and `{name}` placeholders are interpolated. `tk()` and inline `{ en, zh }` maps can be
+mixed freely — use `tk()` for shared/centrally managed text and an inline map for one-off strings.
+
+**Auto-discovery details & overrides**
+
+- The convention is `locales/<code>.json` (e.g. `locales/en.json`, `locales/zh.json`), resolved
+  relative to the config directory. `code` is the file name (a `LocaleCode` like `en` or `zh-TW`).
+- An explicit `i18n.messages` is still supported and **overrides** auto-loaded keys (per id); an
+  explicit `i18n.locales` controls the label/icon/order. Both are optional.
+- Auto-discovery is a **CLI** feature. If you embed the library yourself (calling `createSiteApp`
+  without the `vue-site` CLI), pass `i18n.messages` directly — e.g. build it from JSON with explicit
+  imports (avoid `import.meta.glob` inside `site.config.ts`, which the CLI pre-loads in Node).
+
+### Localizing in your own pages
+
+`useLocalize()` returns `t(id, params?)` (resolve a message id from the central catalog with
+`{name}` interpolation), `localize(value)` (resolve any `LocalizedString` — a `tk()` ref, an inline
+map, or a plain string), and the reactive `locale` ref. `useLocale()` returns
+`{ locale, setLocale, locales }` for building a custom switcher. All work inside any component
+rendered by `createSiteApp`.
+
+```vue
+<script setup lang="ts">
+import { useLocalize } from '@bndynet/vue-site'
+
+const { t, localize, locale } = useLocalize()
+</script>
+
+<template>
+  <!-- key from the central message file -->
+  <h1>{{ t('nav.home') }}</h1>
+  <!-- or inline, for one-off text -->
+  <p>{{ localize({ en: 'Hello', zh: '你好' }) }} — {{ locale }}</p>
+</template>
+```
+
 ## Per-page authorization (`auth`)
 
 Gate individual pages on the current user. Add an `auth` rule to any `NavItem` or `StandalonePage`, and a single `auth.authorize` policy in `SiteConfig` to decide access.
@@ -245,7 +461,7 @@ app.mount('#app')
 
 Use a top-level `await` in your entry (or an async IIFE): `createSiteApp` is async and **awaits** `configureApp` when it returns a `Promise`. If you set optional `bootstrap` in config, that module loads before the app is created; if you omit `bootstrap`, that step is skipped.
 
-Exports: `createSiteApp`, `defineConfig`, `useTheme`, `useSiteConfig`, `themeRefKey`. Types: `SiteConfig`, `SiteEnvConfig`, `SiteViteConfig`, `SiteExternalLink`, `NavItem`, `StandalonePage`, `AuthRule`, `AuthContext`, `AuthConfig`, `RouterConfig`, `ThemeConfig`, `ThemeOption`, `ThemePaletteVars`, `ResolvedNavItem`.
+Exports: `createSiteApp`, `defineConfig`, `useTheme`, `useSiteConfig`, `useLocale`, `useLocalize`, `tk`, `resolveLocalized`, `resolveField`, `resolveMessage`, `mergeCatalog`, `flattenMessages`, `isMessageRef`, `localizedPage`, `builtinMessages`, `themeRefKey`, `localeRefKey`. Types: `SiteConfig`, `SiteEnvConfig`, `SiteViteConfig`, `SiteExternalLink`, `NavItem`, `StandalonePage`, `AuthRule`, `AuthContext`, `AuthConfig`, `RouterConfig`, `ThemeConfig`, `ThemeOption`, `ThemePaletteVars`, `ResolvedNavItem`, `I18nConfig`, `LocaleOption`, `LocaleCode`, `LocalizedString`, `MessageRef`, `MessageTree`, `MessageCatalog`, `PageLoader`, `LocalizedPageOptions`.
 
 ### Theme in Vue pages (`useTheme`)