Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(docs): follow browser language and remember manual preferences (#5351)

t0saki41180e1ba56b
diff --git a/docs/.vitepress/LANGUAGE.md b/docs/.vitepress/LANGUAGE.md
new file mode 100644
index 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.ts
index 67f08a4ad..d9350f599 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -7,7 +7,14 @@ import { titleFromMarkdown, sidebarSection, localizedSectionSidebarItems, locali
const 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.vue
index 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.css
index 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.ts
index 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 value
return 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 OpenVikingPreference
return {
- 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 OpenVikingPreference
return {
- 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 OpenVikingPreference
return {
- 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) return
window.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) return
const 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.ts
new file mode 100644
index 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.js
new file mode 100644
index 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.ts
new file mode 100644
index 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.js
new file mode 100644
index 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.ts
new file mode 100644
index 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.js
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 7ea4bedab..5403a4821 100644
--- a/docs/.vitepress/theme/vikingbot-widget.ts
+++ b/docs/.vitepress/theme/vikingbot-widget.ts
@@ -34,6 +34,7 @@ type WidgetApi = {
toggle: () => void
close: () => void
unmount: () => 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) return
const widget = window.VikingBotWidget
if (!widget) return
- widget.unmount()
- mount(locale)
+ widget.setLocale?.(locale)
+ mountedLocale = locale
}