Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(docs): follow browser language and remember manual preferences (#5351)
t0saki41180e1ba56b
diff --git a/docs/.vitepress/LANGUAGE.md b/docs/.vitepress/LANGUAGE.mdnew file mode 100644index 000000000..ceb21389a--- /dev/null+++ b/docs/.vitepress/LANGUAGE.md@@ -0,0 +1,31 @@+# Site language behavior / 站点语言规则++The interface follows the browser's **first** preferred language. Chinese tags use Chinese; the website additionally supports Traditional Chinese, Japanese, Korean and Spanish. Other sites use English for unsupported languages. IP location, top-level domain and secondary browser languages do not affect this decision.++Choose a language in the language menu to remember it, including when it is already displayed. Choose **Follow browser** to resume automatic selection and remove the language query override. Only menu choices persist. `?lang=en` and other supported language tags control the current page without changing the saved choice; Studio also accepts `?lng=`. On Docs, `/en/` and `/zh/` paths take precedence over queries and saved preferences. The root opens the localized documentation homepage automatically; the localized homepages remain stable URLs.++The shared cookie and each origin's fallback localStorage key are `openviking-language-preference`. Values are `auto`, `en`, `zh`, `zh-TW`, `ja`, `ko`, or `es`. No value means `auto`. The cookie wins over localStorage, including when its value is `auto`. Production cookies use the matching `.openviking.ai` or `.openviking.net` parent domain, `Path=/`, a one-year lifetime, `SameSite=Lax`, and `Secure` on HTTPS. The two parent domains remain independent. A bilingual site may display English for a saved `ja` choice without changing that original choice. Old language records (`openviking-preferences.lang`, `i18nextLng`, `blog.lang`, sessionStorage and window.name) are ignored; theme behavior is retained. Disabled storage still permits changes for the current page.++Each repository contains the same self-contained `language-preference.js` and `language-preference.contract.js`; keep their copies and test cases aligned when changing the contract. There is no remote configuration or runtime dependency between repositories. Focus, history restoration and browser-language changes refresh the preference. Explicit page languages continue to win.++Publish the compatible widget before releasing host integrations. Hosts mount it with their current locale, then call `VikingBotWidget.setLocale('en' | 'zh')` to update UI copy in place. Older widget bundles remain mounted when this method is absent. Language changes preserve drafts, panel state, history and connections; they do not change the model's reply policy. Widget assets at `/studio/embed-widget/vikingbot-widget.js` must be routed to the widget's static build even while the Studio page is closed. Verify a JavaScript MIME type and bundle response, not a homepage HTML fallback, before production widget acceptance. These changes do not reopen Studio.++## 中文说明++界面默认只读取浏览器的首选语言;中文标签使用中文。官网还支持繁体中文、日语、韩语和西班牙语,其他站点遇到未支持语言时显示英语。自动判断不使用 IP、所在地区、顶级域名或浏览器第二语言。++在语言菜单中点击具体语言会保存选择,即使当前已经显示该语言。选择“跟随浏览器”会恢复自动判断,并清除 URL 的语言覆盖。只有菜单操作保存偏好;`?lang=` 只决定当前页面,Studio 兼容 `?lng=`。Docs 的 `/en/`、`/zh/` 路径优先于查询参数和保存的偏好;根入口自动打开对应语言的文档首页,两个语言首页都是稳定地址。Docs 手动切换尽量保留当前文档,缺少译文时回退到目标语言简介页,不存在的锚点回到页首。++Cookie 和本站 localStorage 统一使用新键 `openviking-language-preference`,取值为 `auto` 或上述六种官网语言代码,无记录等同于自动。Cookie 优先于 localStorage,显式 `auto` 也优先。正式域名在各自父域共享 Cookie,一年有效,`Path=/`、`SameSite=Lax`,HTTPS 下启用 `Secure`;`.ai` 与 `.net` 相互独立。不支持的语言只在显示时回退,不覆盖原始选择。旧语言记录不迁移,主题偏好保留;存储不可用时仍可在本页切换。重新获得焦点、历史恢复和浏览器语言变化时重读偏好,显式页面语言继续优先。++四个仓库内的解析模块和契约测试应同步维护,不引入运行时跨仓依赖。发布时先发布兼容旧调用的新 widget,再发布各宿主接入。`setLocale()` 原地更新组件文案,保留面板、草稿、历史与连接;不改变模型回复语言策略。旧 widget 缺少此方法时保留现有实例。组件静态资源路由须与 Studio 页面关闭状态分开,上线验收要确认脚本地址返回 JavaScript;本改动不恢复 Studio 的开放状态。++## Verification / 验证++The shared contract runs 30 cases in each repository. The Docs route suite covers root-to-homepage routing and document language switching; widget locale tests preserve the mounted view, inputs, selection, message history and connection, and verify the translated suggestion payload. The built section-link check also verifies that homepage section anchors remain valid. No coverage threshold is configured for this change.++Chromium checks use local production bundles served under the real `.ai`/`.net` hostnames through request interception, with a local widget and mocked chat transport. They cover both parent-domain cookie scopes and isolation, focus refresh, explicit URLs, legacy language records with retained theme, Blog legacy URLs, desktop/mobile keyboard controls, old widget compatibility, drafts across language changes, and Docs `DOCS_BASE=/guide/`. These are local integration checks, not production chat/backend validation.++Known environment limits: the deployed widget URL currently returns `text/html` and needs its static route restored before release. Studio's whole-project `tsc --noEmit` reports existing errors identical to a clean target-branch checkout; widget typechecking passes. With all storage APIs forced to throw, VitePress 1.6.4's built-in `check-dark-mode` inline script reports a storage error, while documentation and language switching remain usable. Website lint has 11 existing warnings and no errors.++共享契约在各仓运行 30 项;Docs 路由新增 11 项,widget 原地切换新增 4 项。各站构建和 widget 类型检查通过。浏览器验收使用本地生产构建、真实域名 Cookie 规则和模拟聊天传输,不代表线上后端验收已完成。Studio 全量类型检查的已有错误与干净目标分支一致;VitePress 内置深色模式脚本在强制禁用所有存储 API 时会报错,但正文和语言切换可用。上线前仍需恢复 widget 的 JavaScript 静态资源响应。diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.tsindex 67f08a4ad..d9350f599 100644--- a/docs/.vitepress/config.ts+++ b/docs/.vitepress/config.ts@@ -7,7 +7,14 @@ import { titleFromMarkdown, sidebarSection, localizedSectionSidebarItems, localiconst docsRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')const repo = process.env.GITHUB_REPOSITORY || 'volcengine/OpenViking'const githubRepositoryUrl = `https://github.com/${repo}?utm_source=docs&utm_medium=referral&utm_campaign=docs`-const base = process.env.DOCS_BASE || '/'+const configuredBase = '/' + (process.env.DOCS_BASE || '/').split('/').filter(Boolean).join('/') + '/'+const base = configuredBase === '//' ? '/' : configuredBase+const languageSource = fs.readFileSync(path.join(docsRoot, '.vitepress/theme/language-preference.js'), 'utf8').replace('export function', 'function')+const entrySource = fs.readFileSync(path.join(docsRoot, '.vitepress/theme/language-entry.js'), 'utf8').replace('export function', 'function')+const languageBootstrapScript = `${languageSource}\n${entrySource}\n;(() => {+ const target = docsLanguageEntry(location.href, ${JSON.stringify(base)}, createLanguagePreference())+ if (target) location.replace(target)+})()`const preferenceBootstrapScript = `;(() => {const prefix = 'openviking-preferences:'const cookieKey = 'openviking-preferences'@@ -228,7 +235,8 @@ export default defineConfig({['link', { rel: 'icon', type: 'image/x-icon', href: `${base}favicon.ico` }],['link', { rel: 'icon', type: 'image/png', sizes: '32x32', href: `${base}favicon-32.png` }],['link', { rel: 'apple-touch-icon', href: `${base}apple-touch-icon.png` }],- ['script', {}, preferenceBootstrapScript]+ ['script', {}, preferenceBootstrapScript],+ ['script', {}, languageBootstrapScript]],transformPageData(pageData, { siteConfig }) {const srcPath = path.join(siteConfig.srcDir, pageData.relativePath)@@ -276,7 +284,7 @@ export default defineConfig({},themeConfig: {logo: '/ov-logo.png',- logoLink: '/',+ logoLink: base,nav: enNav,socialLinks: [{ icon: 'github', link: githubRepositoryUrl }@@ -292,7 +300,7 @@ export default defineConfig({lang: 'en-US',link: '/en/',themeConfig: {- logoLink: '/en/',+ logoLink: `${base}en/`,nav: enNav,outline: {level: [2, 3]@@ -319,7 +327,7 @@ export default defineConfig({title: 'OpenViking',description: '面向 AI Agent 的开源上下文数据库',themeConfig: {- logoLink: '/zh/',+ logoLink: `${base}zh/`,nav: zhNav,sidebar: {'/zh/getting-started/': localizedGroupedSidebarItems('zh', ['getting-started', 'configuration', 'agent-integrations']),diff --git a/docs/.vitepress/theme/components/LocaleSwitch.vue b/docs/.vitepress/theme/components/LocaleSwitch.vueindex 9edf2838b..79212aa41 100644--- a/docs/.vitepress/theme/components/LocaleSwitch.vue+++ b/docs/.vitepress/theme/components/LocaleSwitch.vue@@ -1,36 +1,69 @@<script setup lang="ts">-import { computed } from 'vue'+import { computed, onMounted, onUnmounted, ref, nextTick } from 'vue'import { useData, useRouter, withBase } from 'vitepress'+import type { LanguagePreference } from '../language-preference.js'+import { docsLanguagePreference } from '../language-state'+import { localizedDocument } from '../language-routing'+import { data as pages } from '../locale-pages.data'-const { lang, page, hash } = useData()+const { lang, page } = useData()const router = useRouter()+const policy = docsLanguagePreference+const preference = ref<LanguagePreference>('auto')+const menu = ref<HTMLDetailsElement>()const locale = computed(() => lang.value.startsWith('zh') ? 'zh' : 'en')+let unsubscribe: (() => void) | undefined+onMounted(() => {+ preference.value = policy.read()+ unsubscribe = policy.subscribe(() => { preference.value = policy.read() })+})+onUnmounted(() => unsubscribe?.())-function switchLocale(next: 'en' | 'zh') {- if (next === locale.value) return- const relative = page.value.relativePath- .replace(/^(en|zh)\//, '')- .replace(/(^|\/)index\.md$/, '$1')- .replace(/\.md$/, '')- // Unlocalized design notes have no counterpart; use the selected docs home.- const target = /^(en|zh)\//.test(page.value.relativePath) ? relative : ''- void router.go(withBase(`/${next}/${target}`) + hash.value)+async function switchLocale(choice: 'auto' | 'en' | 'zh') {+ if (menu.value) menu.value.open = false+ policy.clearQuery()+ policy.save(choice)+ preference.value = choice+ const targetLocale = policy.resolve(null, true)+ const url = new URL(location.href)+ url.pathname = withBase(localizedDocument(page.value.relativePath, targetLocale, pages))+ await router.go(url.pathname + url.search + url.hash)+ await nextTick()+ if (url.hash) {+ let anchor: HTMLElement | null = null+ try { anchor = document.getElementById(decodeURIComponent(url.hash.slice(1))) } catch { /* Invalid fragment. */ }+ if (anchor) anchor.scrollIntoView()+ else {+ history.replaceState(history.state, '', url.pathname + url.search)+ window.scrollTo(0, 0)+ }+ }}</script><template>- <div class="ov-locale-switch" role="group" :aria-label="locale === 'zh' ? '语言' : 'Language'">- <button type="button" lang="en" :aria-pressed="locale === 'en'" aria-label="English" @click="switchLocale('en')">EN</button>- <button type="button" lang="zh-CN" :aria-pressed="locale === 'zh'" aria-label="简体中文" @click="switchLocale('zh')">中</button>- </div>+ <details ref="menu" class="ov-locale-switch"+ @keydown.esc="() => { if (menu) { menu.open = false; menu.querySelector('summary')?.focus() } }"+ @focusout="event => { if (menu && !menu.contains(event.relatedTarget as Node)) menu.open = false }">+ <summary :aria-label="locale === 'zh' ? '语言' : 'Language'">+ <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><path d="M3 5h12M9 3v2m4 0c-1 7-5 10-10 12m2-9c1 4 4 7 8 9m0 4 5-13 5 13m-8-4h6"/></svg>+ {{ locale === 'zh' ? '中' : 'EN' }}{{ preference === 'auto' ? (locale === 'zh' ? ' · 自动' : ' · Auto') : '' }}+ </summary>+ <div class="ov-locale-options">+ <button type="button" :aria-pressed="preference === 'auto'" @click="switchLocale('auto')">{{ locale === 'zh' ? '跟随浏览器' : 'Follow browser' }}</button>+ <button type="button" lang="en" :aria-pressed="preference === 'en'" @click="switchLocale('en')">English</button>+ <button type="button" lang="zh-CN" :aria-pressed="preference === 'zh'" @click="switchLocale('zh')">简体中文</button>+ </div>+ </details></template><style scoped>-/* Same segmented structure and measurements as blog.openviking.ai's b-seg. */-.ov-locale-switch { display: flex; flex: 0 0 auto; padding: 2px; border: 1px solid var(--vp-c-divider); border-radius: 999px; background: var(--vp-c-bg-alt); }-button { padding: 6px 12px; border: 0; border-radius: 999px; background: transparent; color: var(--vp-c-text-2); font: 11px/1.6 var(--vp-font-family-mono); cursor: pointer; }-button[aria-pressed='true'] { background: var(--vp-c-text-1); color: var(--vp-c-bg); }-button:hover:not([aria-pressed='true']) { color: var(--vp-c-text-1); }-button:focus-visible { outline: 2px solid var(--vp-c-brand-1); outline-offset: 3px; }-@media (max-width: 374px) { button { padding-inline: 8px; } }+.ov-locale-switch { position: relative; border: 1px solid var(--vp-c-divider); border-radius: 999px; background: var(--vp-c-bg-alt); }+summary { display: flex; align-items: center; gap: 5px; padding: 5px 8px; font: 11px/1.6 var(--vp-font-family-mono); cursor: pointer; list-style: none; }+summary::-webkit-details-marker { display: none; }+.ov-locale-options { position: absolute; right: 0; top: calc(100% + 6px); z-index: 90; min-width: 170px; padding: 5px; border: 1px solid var(--vp-c-divider); border-radius: 10px; background: var(--vp-c-bg); box-shadow: 0 4px 16px #0002; }+button { display: block; width: 100%; padding: 8px 10px; text-align: left; font-size: 12px; border-radius: 5px; }+button[aria-pressed=true] { font-weight: 700; }+button:hover { background: var(--vp-c-bg-alt); }+button:focus-visible, summary:focus-visible { outline: 2px solid var(--vp-c-brand-1); outline-offset: 3px; }</style>diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.cssindex 41344e658..b791a11e8 100644--- a/docs/.vitepress/theme/custom.css+++ b/docs/.vitepress/theme/custom.css@@ -504,3 +504,6 @@ html.ov-assistant-pill .VPContent {padding-bottom: calc(86px + env(safe-area-inset-bottom, 0px));}}++/* The custom menu includes browser-following mode on desktop and mobile. */+.VPNavBarTranslations, .VPNavScreenTranslations { display: none !important; }diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.tsindex 518b4d910..32d079a52 100644--- a/docs/.vitepress/theme/index.ts+++ b/docs/.vitepress/theme/index.ts@@ -1,3 +1,5 @@+import { docsLanguageEntry } from './language-entry.js'+import { createLanguagePreference } from './language-preference.js'import { h, defineAsyncComponent } from 'vue'import DefaultTheme, { VPButton } from 'vitepress/theme'import DocBreadcrumb from './components/DocBreadcrumb.vue'@@ -14,7 +16,6 @@ import './custom.css'import './reading.css'type OpenVikingPreference = {- lang?: 'zh' | 'en'theme?: 'light' | 'dark'}@@ -32,24 +33,17 @@ const MAIN_SITE_HOSTS = new Set(['127.0.0.1:8080'])-function normalizeLang(value: string | null): OpenVikingPreference['lang'] {- if (value === 'zh' || value === 'en') return value- return undefined-}-function normalizeTheme(value: string | null): OpenVikingPreference['theme'] {if (value === 'light' || value === 'dark') return valuereturn undefined}function readStoredPreference(): OpenVikingPreference {- const rawPreference = sessionStorage.getItem(PREFERENCE_SESSION_KEY)- if (!rawPreference) return {}-try {+ const rawPreference = sessionStorage.getItem(PREFERENCE_SESSION_KEY)+ if (!rawPreference) return {}const preference = JSON.parse(rawPreference) as OpenVikingPreferencereturn {- lang: normalizeLang(preference.lang ?? null),theme: normalizeTheme(preference.theme ?? null)}} catch {@@ -70,7 +64,9 @@ function cookieDomain() {}function readCookiePreference(): OpenVikingPreference {- const cookie = document.cookie+ let cookies = ''+ try { cookies = document.cookie } catch { return {} }+ const cookie = cookies.split('; ').find((item) => item.startsWith(`${PREFERENCE_COOKIE_KEY}=`))@@ -80,7 +76,6 @@ function readCookiePreference(): OpenVikingPreference {const rawPreference = decodeURIComponent(cookie.slice(PREFERENCE_COOKIE_KEY.length + 1))const preference = JSON.parse(rawPreference) as OpenVikingPreferencereturn {- lang: normalizeLang(preference.lang ?? null),theme: normalizeTheme(preference.theme ?? null)}} catch {@@ -106,15 +101,14 @@ function mergePreferences(incoming: OpenVikingPreference): OpenVikingPreference {return {- lang: incoming.lang ?? base.lang,theme: incoming.theme ?? base.theme}}function writeStoredPreference(preference: OpenVikingPreference) {const nextPreference = mergePreferences(readStoredPreference(), preference)- sessionStorage.setItem(PREFERENCE_SESSION_KEY, JSON.stringify(nextPreference))- writeCookiePreference(nextPreference)+ try { sessionStorage.setItem(PREFERENCE_SESSION_KEY, JSON.stringify(nextPreference)) } catch { /* Optional theme persistence. */ }+ try { writeCookiePreference(nextPreference) } catch { /* Optional theme persistence. */ }}function readTransferredPreference(): OpenVikingPreference {@@ -126,7 +120,6 @@ function readTransferredPreference(): OpenVikingPreference {window.name.slice(PREFERENCE_TRANSFER_PREFIX.length)) as OpenVikingPreferencereturn {- lang: normalizeLang(preference.lang ?? null),theme: normalizeTheme(preference.theme ?? null)}} catch {@@ -135,7 +128,7 @@ function readTransferredPreference(): OpenVikingPreference {}function writeTransferredPreference(preference: OpenVikingPreference) {- if (!preference.lang && !preference.theme) return+ if (!preference.theme) returnwindow.name = `${PREFERENCE_TRANSFER_PREFIX}${JSON.stringify(preference)}`}@@ -149,30 +142,18 @@ function readPersistedPreference() {function applyPreference(preference: OpenVikingPreference) {const normalizedPreference: OpenVikingPreference = {- lang: normalizeLang(preference.lang ?? null),theme: normalizeTheme(preference.theme ?? null)}- if (normalizedPreference.lang || normalizedPreference.theme) {+ if (normalizedPreference.theme) {writeStoredPreference(normalizedPreference)writeTransferredPreference(mergePreferences(readStoredPreference(), normalizedPreference))}if (normalizedPreference.theme) {- localStorage.setItem(VITEPRESS_THEME_KEY, normalizedPreference.theme)+ try { localStorage.setItem(VITEPRESS_THEME_KEY, normalizedPreference.theme) } catch { /* Still apply the theme. */ }document.documentElement.classList.toggle('dark', normalizedPreference.theme === 'dark')}-- const lang = normalizedPreference.lang- if (!lang) return-- const targetPath = resolveLocalizedPath(window.location.pathname, lang)- const targetUrl = `${targetPath}${window.location.search}${window.location.hash}`- const currentUrl = `${window.location.pathname}${window.location.search}${window.location.hash}`-- if (targetUrl !== currentUrl) {- window.location.replace(targetUrl)- }}function syncPreferenceFromPeerSite() {@@ -181,56 +162,18 @@ function syncPreferenceFromPeerSite() {applyPreference(readPersistedPreference())}-function resolveLocalizedPath(pathname: string, lang?: OpenVikingPreference['lang']) {- if (lang === 'zh') {- if (pathname.startsWith('/en/')) return pathname.replace(/^\/en\//, '/zh/')- }-- if (lang === 'en') {- if (pathname.startsWith('/zh/')) return pathname.replace(/^\/zh\//, '/en/')- }-- return pathname-}--function currentDocsLang(): OpenVikingPreference['lang'] {- if (window.location.pathname.startsWith('/zh/')) return 'zh'- if (window.location.pathname.startsWith('/en/')) return 'en'- return undefined-}-function currentDocsTheme(): OpenVikingPreference['theme'] {return document.documentElement.classList.contains('dark') ? 'dark' : 'light'}function syncCurrentDocsPreference() {const preference = mergePreferences(readPersistedPreference(), {- lang: currentDocsLang(),theme: currentDocsTheme()})writeStoredPreference(preference)writeTransferredPreference(preference)}-function patchHistoryForPreferenceSync() {- const originalPushState = window.history.pushState- const originalReplaceState = window.history.replaceState-- window.history.pushState = function patchedPushState(...args) {- const result = originalPushState.apply(this, args)- window.setTimeout(syncCurrentDocsPreference)- return result- }-- window.history.replaceState = function patchedReplaceState(...args) {- const result = originalReplaceState.apply(this, args)- window.setTimeout(syncCurrentDocsPreference)- return result- }-- window.addEventListener('popstate', () => window.setTimeout(syncCurrentDocsPreference))-}-function watchThemePreference() {const observer = new MutationObserver(syncCurrentDocsPreference)observer.observe(document.documentElement, {@@ -273,7 +216,6 @@ function syncPreferenceToMainSiteLinks() {if (!url) returnconst preference = mergePreferences(readPersistedPreference(), {- lang: currentDocsLang(),theme: currentDocsTheme()})writeStoredPreference(preference)@@ -288,7 +230,6 @@ function syncPreferenceToMainSiteLinks() {function startPreferenceSync() {syncPreferenceFromPeerSite()syncCurrentDocsPreference()- patchHistoryForPreferenceSync()watchThemePreference()syncPreferenceToMainSiteLinks()window.addEventListener('pageshow', syncPreferenceFromPeerSite)@@ -317,7 +258,8 @@ export default {'sidebar-nav-before': () => h('a', { class: 'sidebar-home-link', href: withBase(zh ? '/zh/' : '/en/') }, zh ? '← 文档首页' : '← Documentation home'),'doc-after': () => h(ApiExampleTabsEnhancer),'nav-bar-content-before': () => h(OpenVikingSearch),- 'nav-bar-content-after': () => h(LocaleSwitch)+ 'nav-bar-content-after': () => h(LocaleSwitch),+ 'nav-screen-content-after': () => h(LocaleSwitch)})},enhanceApp({ app, router }: EnhanceAppContext) {@@ -325,6 +267,16 @@ export default {app.component('DocsHome', defineAsyncComponent(() => import('./components/DocsHome.vue')))if (import.meta.env.SSR || typeof window === 'undefined') return+ const policy = createLanguagePreference()+ const previousBeforeHook = router.onBeforeRouteChange+ router.onBeforeRouteChange = async (to: string) => {+ if (await previousBeforeHook?.(to) === false) return false+ const target = docsLanguageEntry(new URL(to, location.href).href, withBase('/'), policy)+ if (target) {+ void router.go(target)+ return false+ }+ }trackPageView(window.location.pathname)initVikingBotWidget()@@ -332,8 +284,7 @@ export default {router.onAfterRouteChanged = (to: string) => {previousHook?.(to)trackPageView(to.split('?')[0].split('#')[0])- // <html lang> is rewritten by the router before this fires, so a locale- // switch re-mounts the widget in the language the reader just chose.+ // Update the existing widget after VitePress applies the page language.syncVikingBotLocale()}}diff --git a/docs/.vitepress/theme/language-entry.d.ts b/docs/.vitepress/theme/language-entry.d.tsnew file mode 100644index 000000000..1050466c9--- /dev/null+++ b/docs/.vitepress/theme/language-entry.d.ts@@ -0,0 +1,2 @@+import type { LanguagePolicy } from './language-preference.js';+export function docsLanguageEntry(href: string, base: string, preference: LanguagePolicy): string | null;diff --git a/docs/.vitepress/theme/language-entry.js b/docs/.vitepress/theme/language-entry.jsnew file mode 100644index 000000000..692bd1110--- /dev/null+++ b/docs/.vitepress/theme/language-entry.js@@ -0,0 +1,11 @@+/** Used unchanged by the blocking head script and the entry contract tests. */+export function docsLanguageEntry(href, base, preference) {+ const url = new URL(href);+ const root = '/' + base.split('/').filter(Boolean).join('/');+ const prefix = root === '/' ? '/' : root + '/';+ const relative = url.pathname === root ? '' : url.pathname.startsWith(prefix) ? url.pathname.slice(prefix.length) : null;+ if (relative !== '' && relative !== 'index.html') return null;+ const locale = preference.resolve(preference.parse(url.searchParams.get('lang')) || null, true);+ url.pathname = prefix + locale + '/';+ return url.href;+}diff --git a/docs/.vitepress/theme/language-preference.contract.d.ts b/docs/.vitepress/theme/language-preference.contract.d.tsnew file mode 100644index 000000000..5e51a9a5a--- /dev/null+++ b/docs/.vitepress/theme/language-preference.contract.d.ts@@ -0,0 +1,2 @@+export function languageContract(test: (name: string, run: () => void) => unknown): void;+export function testBrowser(options?: { url?: string; languages?: string[]; language?: string; local?: Record<string, string>; cookie?: string; denied?: boolean; cookieBlocked?: boolean }): { browser: Window; local: Map<string, string>; writes: string[]; setCookie(value: string): void };diff --git a/docs/.vitepress/theme/language-preference.contract.js b/docs/.vitepress/theme/language-preference.contract.jsnew file mode 100644index 000000000..8c5f38c08--- /dev/null+++ b/docs/.vitepress/theme/language-preference.contract.js@@ -0,0 +1,155 @@+import assert from 'node:assert/strict';+import { createLanguagePreference } from './language-preference.js';++export function testBrowser(options = {}) {+ const local = new Map(Object.entries(options.local || {}));+ const events = new EventTarget();+ const writes = [];+ let cookie = options.cookie || '';+ let location = new URL(options.url || 'https://openviking.ai/');+ const browser = {+ navigator: { languages: options.languages ?? ['en-US'], language: options.language ?? 'en-US' },+ get location() { return location; },+ document: {+ get cookie() { if (options.denied) throw new Error('blocked'); return cookie; },+ set cookie(value) {+ if (options.denied) throw new Error('blocked');+ writes.push(value);+ if (!options.cookieBlocked) cookie = value.split(';')[0];+ },+ },+ localStorage: {+ getItem(key) { if (options.denied) throw new Error('blocked'); return local.get(key) ?? null; },+ setItem(key, value) { if (options.denied) throw new Error('blocked'); local.set(key, value); },+ },+ history: { state: { navigation: 7 }, replaceState(state, _, href) { assert.equal(state, this.state); location = new URL(href, location); } },+ addEventListener: events.addEventListener.bind(events),+ removeEventListener: events.removeEventListener.bind(events),+ dispatchEvent: events.dispatchEvent.bind(events),+ };+ return { browser, local, writes, setCookie(value) { cookie = value; } };+}++/** Same behavioral cases are run by each site's own test runner. */+export function languageContract(test) {+ const key = 'openviking-language-preference';+ for (const [tag, full, bilingual] of [+ ['zh-CN', 'zh', 'zh'], ['zh-SG', 'zh', 'zh'], ['zh-Hans', 'zh', 'zh'],+ ['zh-TW', 'zh-TW', 'zh'], ['zh-HK', 'zh-TW', 'zh'], ['zh-MO', 'zh-TW', 'zh'],+ ['zh-Hant', 'zh-TW', 'zh'], ['zh_Hant_TW', 'zh-TW', 'zh'], ['zh-Hans-TW', 'zh', 'zh'],+ ['ja-JP', 'ja', 'en'], ['ko-KR', 'ko', 'en'], ['es-419', 'es', 'en'],+ ['en-US', 'en', 'en'], ['fr-FR', 'en', 'en'],+ ]) {+ test(`first browser language ${tag}`, () => {+ const { browser, local, writes } = testBrowser({ languages: [tag, 'zh-CN'] });+ const policy = createLanguagePreference(browser);+ assert.equal(policy.resolve(), full);+ assert.equal(policy.resolve(undefined, true), bilingual);+ assert.equal(policy.read(), 'auto');+ assert.equal(local.size, 0);+ assert.deepEqual(writes, []);+ });+ }+ test('uses navigator.language only when the first language is missing', () => {+ const { browser } = testBrowser({ languages: [], language: 'zh-SG' });+ assert.equal(createLanguagePreference(browser).resolve(), 'zh');+ assert.equal(createLanguagePreference(undefined).resolve(), 'en');+ });+ test('URL overrides cookie and local preference without persisting', () => {+ const fixture = testBrowser({ url: 'https://blog.openviking.ai/post/a/?lang=en', cookie: `${key}=zh`, local: { [key]: 'ja' } });+ const policy = createLanguagePreference(fixture.browser);+ assert.equal(policy.resolve(), 'en');+ assert.equal(policy.read(), 'zh');+ assert.equal(fixture.local.get(key), 'ja');+ assert.deepEqual(fixture.writes, []);+ });+ test('ignores invalid query values and supports Studio lng alias', () => {+ const { browser } = testBrowser({ url: 'https://openviking.net/studio/?lang=invalid&lng=zh-SG', cookie: `${key}=ja` });+ const policy = createLanguagePreference(browser);+ assert.equal(policy.resolve(), 'ja');+ assert.equal(policy.resolve(policy.query(['lang', 'lng']), true), 'zh');+ assert.equal(policy.parse('auto'), undefined);+ assert.equal(policy.parse('zh<script>'), undefined);+ });+ test('auto cookie overrides stale local manual preference', () => {+ const fixture = testBrowser({ cookie: `${key}=auto`, local: { [key]: 'zh' } });+ assert.equal(createLanguagePreference(fixture.browser).resolve(), 'en');+ });+ test('ignores malformed cookies and old language records', () => {+ const fixture = testBrowser({ languages: ['zh-HK'], cookie: `${key}=%ZZ; openviking-preferences=%7B%22lang%22%3A%22en%22%7D`, local: { i18nextLng: 'en', 'blog.lang': 'en' } });+ assert.equal(createLanguagePreference(fixture.browser).resolve(), 'zh-TW');+ });+ test('explicitly saves a click on the current automatic language', () => {+ const fixture = testBrowser({ languages: ['zh-CN'] });+ const policy = createLanguagePreference(fixture.browser);+ assert.equal(policy.resolve(), 'zh');+ policy.save('zh');+ assert.equal(policy.read(), 'zh');+ assert.equal(createLanguagePreference(fixture.browser).read(), 'zh');+ assert.equal(fixture.local.get(key), 'zh');+ });+ test('keeps the original choice when a bilingual site falls back', () => {+ const fixture = testBrowser();+ const policy = createLanguagePreference(fixture.browser);+ policy.save('ja');+ assert.equal(policy.resolve(undefined, true), 'en');+ assert.equal(policy.read(), 'ja');+ assert.equal(fixture.local.get(key), 'ja');+ });+ test('restores auto and clears only language query parameters', () => {+ const fixture = testBrowser({ url: 'https://openviking.net/studio/?lang=en&lng=en&tab=1#hello', languages: ['zh-SG'] });+ const policy = createLanguagePreference(fixture.browser);+ policy.clearQuery(['lang', 'lng']);+ policy.save('auto');+ assert.equal(policy.read(), 'auto');+ assert.equal(policy.resolve(), 'zh');+ assert.equal(fixture.browser.location.href, 'https://openviking.net/studio/?tab=1#hello');+ assert.equal(fixture.local.get(key), 'auto');+ });+ for (const host of ['openviking.ai', 'blog.openviking.ai', 'docs.openviking.net', 'openviking.net']) {+ test(`writes scoped secure cookie for ${host}`, () => {+ const fixture = testBrowser({ url: `https://${host}/` });+ createLanguagePreference(fixture.browser).save('es');+ const cookie = fixture.writes[0];+ assert.ok(cookie.includes(`Domain=.openviking.${host.endsWith('.ai') ? 'ai' : 'net'}`));+ for (const attribute of ['Path=/', 'Max-Age=31536000', 'SameSite=Lax', 'Secure']) assert.ok(cookie.includes(attribute));+ });+ }+ test('localhost and lookalike hosts do not get a parent-domain cookie', () => {+ for (const host of ['localhost', '127.0.0.1', 'notopenviking.ai', 'openviking.net.example.com']) {+ const fixture = testBrowser({ url: `http://${host}/` });+ createLanguagePreference(fixture.browser).save('en');+ assert.ok(!fixture.writes[0].includes('Domain='));+ assert.ok(!fixture.writes[0].includes('Secure'));+ }+ });+ test('disabled storage still permits manual and automatic in-page switching', () => {+ const fixture = testBrowser({ denied: true, languages: ['zh-TW'] });+ const policy = createLanguagePreference(fixture.browser);+ policy.save('ja');+ assert.equal(policy.resolve(), 'ja');+ policy.save('auto');+ assert.equal(policy.resolve(), 'zh-TW');+ });+ test('blocked cookie writes retain local choices and observe later local changes', () => {+ const fixture = testBrowser({ cookieBlocked: true });+ const policy = createLanguagePreference(fixture.browser);+ policy.save('zh');+ assert.equal(policy.read(), 'zh');+ fixture.local.set(key, 'es');+ assert.equal(policy.read(), 'es');+ });+ test('focus and history restoration refresh preferences without overriding an explicit URL', () => {+ const fixture = testBrowser({ url: 'https://openviking.ai/?lang=en' });+ const policy = createLanguagePreference(fixture.browser);+ const observed = [];+ const unsubscribe = policy.subscribe(() => observed.push([policy.read(), policy.resolve()]));+ fixture.setCookie(`${key}=zh`);+ for (const event of ['focus', 'pageshow', 'popstate', 'storage', 'languagechange']) fixture.browser.dispatchEvent(new Event(event));+ assert.deepEqual(observed, Array(5).fill(['zh', 'en']));+ unsubscribe();+ fixture.browser.dispatchEvent(new Event('focus'));+ assert.equal(observed.length, 5);+ assert.deepEqual(fixture.writes, []);+ });+}diff --git a/docs/.vitepress/theme/language-preference.d.ts b/docs/.vitepress/theme/language-preference.d.tsnew file mode 100644index 000000000..e3b916a0d--- /dev/null+++ b/docs/.vitepress/theme/language-preference.d.ts@@ -0,0 +1,16 @@+export type SiteLanguage = 'en' | 'zh' | 'zh-TW' | 'ja' | 'ko' | 'es';+export type LanguagePreference = SiteLanguage | 'auto';+export interface LanguagePolicy {+ key: string;+ parse(value: unknown): SiteLanguage | undefined;+ read(): LanguagePreference;+ preferred(): SiteLanguage;+ query(names?: string[]): SiteLanguage | undefined;+ resolve(explicit?: string | null, bilingual?: false): SiteLanguage;+ resolve(explicit: string | null | undefined, bilingual: true): 'en' | 'zh';+ save(value: LanguagePreference): void;+ clearQuery(names?: string[]): void;+ subscribe(listener: () => void): () => void;+ refresh(): void;+}+export function createLanguagePreference(browser?: Window): LanguagePolicy;diff --git a/docs/.vitepress/theme/language-preference.js b/docs/.vitepress/theme/language-preference.jsnew file mode 100644index 000000000..119812a94--- /dev/null+++ b/docs/.vitepress/theme/language-preference.js@@ -0,0 +1,125 @@+/**+ * Shared language contract, copied into Website, Blog, Docs and Studio.+ * Keep this file and its contract tests identical across sites. No runtime dependency.+ * Self-contained so the same code can run in a pre-paint bootstrap script.+ */+export function createLanguagePreference(browser = typeof window === 'undefined' ? undefined : window) {+ const key = 'openviking-language-preference';+ const languages = ['en', 'zh', 'zh-TW', 'ja', 'ko', 'es'];+ const listeners = new Set();+ let pending = null;++ function parse(value) {+ if (typeof value !== 'string') return undefined;+ const tag = value.trim().replace(/_/g, '-').toLowerCase();+ if (!/^[a-z]{2,3}(?:-[a-z0-9]{2,8})*$/.test(tag)) return undefined;+ const parts = tag.split('-');+ if (parts[0] === 'zh') {+ if (parts.includes('hans')) return 'zh';+ return parts.some(part => ['hant', 'tw', 'hk', 'mo'].includes(part)) ? 'zh-TW' : 'zh';+ }+ return languages.includes(parts[0]) ? parts[0] : undefined;+ }++ function validPreference(value) {+ return value === 'auto' || languages.includes(value) ? value : undefined;+ }++ function cookiePreference() {+ try {+ for (const row of browser.document.cookie.split(';')) {+ const item = row.trim();+ if (!item.startsWith(key + '=')) continue;+ try {+ const value = validPreference(decodeURIComponent(item.slice(key.length + 1)));+ if (value) return value;+ } catch { /* Ignore a malformed cookie. */ }+ }+ } catch { /* Cookies may be disabled. */ }+ return undefined;+ }++ function localPreference() {+ try { return validPreference(browser.localStorage.getItem(key)); } catch { return undefined; }+ }++ function read() {+ const cookie = cookiePreference();+ // If a cookie write was rejected, keep the local choice until a peer changes it.+ const local = localPreference();+ if (pending && pending.cookie === cookie && pending.local === local) return pending.value;+ pending = null;+ if (cookie) return cookie;+ return local || 'auto';+ }++ function preferred() {+ const preference = read();+ if (preference !== 'auto') return preference;+ return parse(browser?.navigator.languages?.[0] || browser?.navigator.language) || 'en';+ }++ function query(names = ['lang']) {+ const params = new URLSearchParams(browser?.location.search || '');+ for (const name of names) {+ const value = parse(params.get(name));+ if (value) return value;+ }+ return undefined;+ }++ function resolve(explicit = query(), bilingual = false) {+ const language = parse(explicit) || preferred();+ return bilingual ? (language.startsWith('zh') ? 'zh' : 'en') : language;+ }++ function refresh() {+ for (const listener of listeners) listener();+ }++ function clearQuery(names = ['lang']) {+ if (!browser) return;+ const url = new URL(browser.location.href);+ for (const name of names) url.searchParams.delete(name);+ if (url.href !== browser.location.href) {+ browser.history.replaceState(browser.history.state, '', url.href);+ }+ }++ function save(value) {+ if (!validPreference(value)) return;+ const before = cookiePreference();+ try { browser.localStorage.setItem(key, value); } catch { /* In-page fallback below. */ }+ try {+ const hostname = browser.location.hostname.toLowerCase();+ const domain = ['openviking.ai', 'openviking.net'].find(+ candidate => hostname === candidate || hostname.endsWith('.' + candidate),+ );+ browser.document.cookie = [+ key + '=' + encodeURIComponent(value), 'Path=/', 'Max-Age=31536000', 'SameSite=Lax',+ domain ? 'Domain=.' + domain : '', browser.location.protocol === 'https:' ? 'Secure' : '',+ ].filter(Boolean).join('; ');+ } catch { /* Storage access must not prevent a language switch. */ }+ pending = cookiePreference() === value ? null : { value, cookie: before, local: localPreference() };+ refresh();+ }++ function subscribe(listener) {+ if (listeners.size === 0) {+ for (const event of ['focus', 'pageshow', 'popstate', 'storage', 'languagechange']) {+ browser?.addEventListener(event, refresh);+ }+ }+ listeners.add(listener);+ return () => {+ listeners.delete(listener);+ if (listeners.size === 0) {+ for (const event of ['focus', 'pageshow', 'popstate', 'storage', 'languagechange']) {+ browser?.removeEventListener(event, refresh);+ }+ }+ };+ }++ return { key, parse, read, preferred, query, resolve, save, clearQuery, subscribe, refresh };+}diff --git a/docs/.vitepress/theme/language-preference.test.ts b/docs/.vitepress/theme/language-preference.test.tsnew file mode 100644index 000000000..41e036bde--- /dev/null+++ b/docs/.vitepress/theme/language-preference.test.ts@@ -0,0 +1,3 @@+import test from 'node:test';+import { languageContract } from './language-preference.contract.js';+languageContract(test);diff --git a/docs/.vitepress/theme/language-routing.test.ts b/docs/.vitepress/theme/language-routing.test.tsnew file mode 100644index 000000000..475e89cec--- /dev/null+++ b/docs/.vitepress/theme/language-routing.test.ts@@ -0,0 +1,40 @@+import assert from 'node:assert/strict'+import test from 'node:test'+import { createLanguagePreference } from './language-preference.js'+import { testBrowser } from './language-preference.contract.js'+import { docsLanguageEntry } from './language-entry.js'+import { localizedDocument } from './language-routing.ts'++for (const [pathname, base] of [+ ['/', '/'], ['/index.html', '/'],+ ['/guide/', '/guide/'], ['/guide', '/guide/'], ['/guide/index.html', '/guide/'],+]) {+ test(`entry ${pathname} resolves the localized homepage under base ${base}`, () => {+ const fixture = testBrowser({ languages: ['zh-Hant'], url: `https://docs.openviking.ai${pathname}?lang=zh&source=share#title` })+ const policy = createLanguagePreference(fixture.browser)+ const next = docsLanguageEntry(fixture.browser.location.href, base, policy)+ assert.equal(next, `https://docs.openviking.ai${base}zh/?lang=zh&source=share#title`)+ assert.equal(docsLanguageEntry(next!, base, policy), null)+ assert.deepEqual(fixture.writes, [])+ })+}++test('root query precedes manual preference; localized homepages and documents never redirect', () => {+ const fixture = testBrowser({ cookie: 'openviking-language-preference=zh', url: 'https://docs.openviking.net/en/?lang=en' })+ const policy = createLanguagePreference(fixture.browser)+ assert.equal(docsLanguageEntry('https://docs.openviking.net/?lang=en', '/', policy), 'https://docs.openviking.net/en/?lang=en')+ for (const path of ['/en/', '/zh', '/en/index.html', '/en/guides/03-deployment', '/zh/guides/03-deployment', '/outside/', '/guidebook/']) {+ assert.equal(docsLanguageEntry(`https://docs.openviking.net${path}`, '/', policy), null)+ }+ assert.equal(docsLanguageEntry('https://docs.openviking.net/en/', '/guide/', policy), null)+ assert.equal(docsLanguageEntry('https://docs.openviking.net/', '/', policy), 'https://docs.openviking.net/zh/')+ assert.equal(policy.read(), 'zh')+})++test('switches the same document or falls back to the target introduction', () => {+ const pages = ['en/guides/03-deployment.md', 'zh/guides/03-deployment.md', 'zh/index.md']+ assert.equal(localizedDocument('en/guides/03-deployment.md', 'zh', pages), '/zh/guides/03-deployment')+ assert.equal(localizedDocument('zh/guides/03-deployment.md', 'en', pages), '/en/guides/03-deployment')+ assert.equal(localizedDocument('en/guides/missing.md', 'zh', pages), '/zh/getting-started/01-introduction')+ assert.equal(localizedDocument('design/untranslated.md', 'en', pages), '/en/getting-started/01-introduction')+})diff --git a/docs/.vitepress/theme/language-routing.ts b/docs/.vitepress/theme/language-routing.tsnew file mode 100644index 000000000..936c61c27--- /dev/null+++ b/docs/.vitepress/theme/language-routing.ts@@ -0,0 +1,7 @@+export function localizedDocument(relativePath: string, locale: 'en' | 'zh', pages: string[]): string {+ const relative = relativePath.replace(/^(en|zh)\//, '');+ const candidate = `${locale}/${relative}`;+ const selected = /^(en|zh)\//.test(relativePath) && pages.includes(candidate)+ ? candidate : `${locale}/getting-started/01-introduction.md`;+ return '/' + selected.replace(/index\.md$/, '').replace(/\.md$/, '');+}diff --git a/docs/.vitepress/theme/language-state.ts b/docs/.vitepress/theme/language-state.tsnew file mode 100644index 000000000..5905db855--- /dev/null+++ b/docs/.vitepress/theme/language-state.ts@@ -0,0 +1,4 @@+import { createLanguagePreference } from './language-preference.js'++// Desktop and mobile menus observe the same in-page choice when storage is blocked.+export const docsLanguagePreference = createLanguagePreference()diff --git a/docs/.vitepress/theme/locale-pages.data.ts b/docs/.vitepress/theme/locale-pages.data.tsnew file mode 100644index 000000000..fc8957145--- /dev/null+++ b/docs/.vitepress/theme/locale-pages.data.ts@@ -0,0 +1,14 @@+import fs from 'node:fs'+import path from 'node:path'+import { fileURLToPath } from 'node:url'++export default {+ watch: ['../../en/**/*.md', '../../zh/**/*.md'],+ load() {+ const root = fileURLToPath(new URL('../../', import.meta.url))+ return ['en', 'zh'].flatMap(locale =>+ fs.readdirSync(path.join(root, locale), { recursive: true })+ .filter(file => typeof file === 'string' && file.endsWith('.md'))+ .map(file => `${locale}/${file}`.replaceAll(path.sep, '/')))+ }+}diff --git a/docs/.vitepress/theme/vikingbot-widget.ts b/docs/.vitepress/theme/vikingbot-widget.tsindex 7ea4bedab..5403a4821 100644--- a/docs/.vitepress/theme/vikingbot-widget.ts+++ b/docs/.vitepress/theme/vikingbot-widget.ts@@ -34,6 +34,7 @@ type WidgetApi = {toggle: () => voidclose: () => voidunmount: () => void+ setLocale?: (locale: WidgetLocale) => void}declare global {@@ -128,17 +129,12 @@ export function initVikingBotWidget() {})}-/**- * Switching locale is a client-side route change, so a widget mounted in the- * other language would keep its old strings for the rest of the session.- * Remount it — the visitor just asked for a different language, and their- * conversation is keyed on the browser, not on this mount.- */+/** Update a compatible widget in place, leaving older instances intact. */export function syncVikingBotLocale() {const locale = currentLocale()if (!mountedLocale || mountedLocale === locale) returnconst widget = window.VikingBotWidgetif (!widget) return- widget.unmount()- mount(locale)+ widget.setLocale?.(locale)+ mountedLocale = locale}