Skip to content

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

fix(docs): localize OpenViking search UI (#2711)

Hao Zheb1712aab2812
diff --git a/.github/workflows/_docs.yml b/.github/workflows/_docs.yml
index 63a098352..5350d24c4 100644
--- a/.github/workflows/_docs.yml
+++ b/.github/workflows/_docs.yml
@@ -24,6 +24,10 @@ jobs:
run: npm ci
working-directory: docs
+ - name: Test docs search
+ run: npm run test:search
+ working-directory: docs
+
- name: Build docs
run: npm run docs:build
working-directory: docs
diff --git a/docs/.vitepress/theme/OpenVikingSearch.vue b/docs/.vitepress/theme/OpenVikingSearch.vue
index 131d033a5..5f2262c67 100644
--- a/docs/.vitepress/theme/OpenVikingSearch.vue
+++ b/docs/.vitepress/theme/OpenVikingSearch.vue
@@ -1,36 +1,22 @@
<script setup lang="ts">
import { computed, nextTick, onMounted, onUnmounted, ref, watch } from 'vue'
-import { withBase } from 'vitepress'
-
-type SearchMode = 'semantic' | 'keyword' | 'file'
-type SearchLocale = 'en' | 'zh'
-
-type DocsIndexRecord = {
- locale: SearchLocale
- path: string
- text: string
- title: string
- url: string
-}
-
-type DocsSearchResult = {
- line?: number | null
- mode?: SearchMode
- relativePath?: string
- score?: number | null
- snippet?: string
- title?: string
- uri?: string
- url?: string
-}
+import { useData, withBase } from 'vitepress'
+
+import { searchCopyForLocale } from './openviking-search-i18n'
+import { localizeSearchResultTitles } from './openviking-search-results'
+import type { RemoteSearchFailureReason } from './openviking-search-i18n'
+import type {
+ DocsIndexRecord,
+ DocsSearchResult,
+ SearchLocale,
+ SearchMode
+} from './openviking-search-results'
type ResolvedDocsSearchResult = DocsSearchResult & {
cleanedSnippet: string
resolvedUrl: string
}
-type RemoteSearchFailureReason = 'rate_limited' | 'timeout' | 'unavailable'
-
type RemoteSearchResponse =
| { ok: true; results: DocsSearchResult[] }
| { ok: false; reason: RemoteSearchFailureReason }
@@ -38,29 +24,16 @@ type RemoteSearchResponse =
const PRODUCTION_SEARCH_URL = 'https://openviking.ai/studio/gateway/docs/search'
const SEARCH_LIMIT = 8
const REMOTE_SEARCH_DEBOUNCE_MS = 1000
-const REMOTE_SEARCH_TIMEOUT_MS = 10000
-
-const modes: { command: string; label: string; placeholder: string; value: SearchMode }[] = [
- {
- command: '/find',
- label: 'Semantic',
- placeholder: 'Ask a question about the docs',
- value: 'semantic'
- },
- {
- command: '/grep',
- label: 'Keyword',
- placeholder: 'Search exact words in the docs',
- value: 'keyword'
- },
- {
- command: '/glob',
- label: 'File',
- placeholder: 'Find docs by path or filename',
- value: 'file'
- }
+const REMOTE_SEARCH_TIMEOUT_MS = 15000
+
+const modeDefinitions: { command: string; value: SearchMode }[] = [
+ { command: '/find', value: 'semantic' },
+ { command: '/grep', value: 'keyword' },
+ { command: '/glob', value: 'file' }
]
+const { lang } = useData()
+
const inputRef = ref<HTMLInputElement | null>(null)
const triggerRef = ref<HTMLButtonElement | null>(null)
const dialogRef = ref<HTMLElement | null>(null)
@@ -79,7 +52,14 @@ let localIndexPromise: Promise<DocsIndexRecord[]> | null = null
let activeSearchController: AbortController | null = null
const trimmedQuery = computed(() => query.value.trim())
-const activeMode = computed(() => modes.find((item) => item.value === mode.value) ?? modes[0])
+const searchCopy = computed(() => searchCopyForLocale(docsLocale()))
+const modes = computed(() =>
+ modeDefinitions.map((item) => ({
+ ...item,
+ ...searchCopy.value.modes[item.value]
+ }))
+)
+const activeMode = computed(() => modes.value.find((item) => item.value === mode.value) ?? modes.value[0])
const resolvedResults = computed<ResolvedDocsSearchResult[]>(() =>
results.value.flatMap((result) => {
const resolvedUrl = resultUrl(result)
@@ -88,6 +68,12 @@ const resolvedResults = computed<ResolvedDocsSearchResult[]>(() =>
)
function docsLocale(): SearchLocale {
+ const currentLang = String(lang.value ?? '').toLowerCase()
+ if (currentLang.startsWith('zh')) return 'zh'
+ if (currentLang.startsWith('en')) return 'en'
+
+ if (typeof window === 'undefined') return 'en'
+
const basePath = normalizeBasePath(import.meta.env.BASE_URL)
const pathname = window.location.pathname
const localizedPath = pathname.startsWith(basePath)
@@ -232,7 +218,7 @@ async function runSearch() {
if (currentSequence !== searchSequence) return
if (remoteResponse?.ok) {
- results.value = remoteResponse.results
+ results.value = await localizeRemoteResultTitles(remoteResponse.results, docsLocale())
return
}
@@ -253,6 +239,13 @@ async function runSearch() {
}
}
+async function localizeRemoteResultTitles(
+ searchResults: DocsSearchResult[],
+ locale: SearchLocale
+) {
+ return localizeSearchResultTitles(searchResults, locale, loadLocalIndex)
+}
+
async function fetchRemoteResults(
endpoint: string,
searchQuery: string,
@@ -321,16 +314,7 @@ function clearPendingSearch() {
}
function fallbackNotice(reason: RemoteSearchFailureReason, localResultCount: number) {
- const prefix =
- reason === 'rate_limited'
- ? 'OpenViking search is rate limited.'
- : reason === 'timeout'
- ? 'OpenViking search timed out.'
- : 'OpenViking search is unavailable.'
-
- return localResultCount > 0
- ? `${prefix} Showing local docs results.`
- : `${prefix} No local results found.`
+ return searchCopy.value.notice(reason, localResultCount)
}
async function loadLocalIndex() {
@@ -484,13 +468,13 @@ onUnmounted(() => {
<div class="ov-docs-search">
<button
ref="triggerRef"
- aria-label="Search docs"
+ :aria-label="searchCopy.trigger"
class="ov-docs-search-trigger"
type="button"
@click="openSearch"
>
- <span class="ov-docs-search-trigger-label">Search docs</span>
- <span aria-hidden="true" class="ov-docs-search-trigger-compact">Search</span>
+ <span class="ov-docs-search-trigger-label">{{ searchCopy.trigger }}</span>
+ <span aria-hidden="true" class="ov-docs-search-trigger-compact">{{ searchCopy.compactTrigger }}</span>
<kbd>Ctrl K</kbd>
</button>
@@ -498,7 +482,7 @@ onUnmounted(() => {
<div class="ov-docs-search-backdrop" @click.self="closeSearch">
<section
ref="dialogRef"
- aria-label="OpenViking docs search"
+ :aria-label="searchCopy.dialogLabel"
aria-modal="true"
class="ov-docs-search-dialog"
role="dialog"
@@ -510,7 +494,7 @@ onUnmounted(() => {
aria-controls="ov-docs-search-mode-menu"
:aria-expanded="isModeMenuOpen"
aria-haspopup="listbox"
- aria-label="Search mode"
+ :aria-label="searchCopy.modeLabel"
class="ov-docs-search-mode-button"
type="button"
@click="toggleModeMenu"
@@ -522,7 +506,7 @@ onUnmounted(() => {
<div
v-if="isModeMenuOpen"
id="ov-docs-search-mode-menu"
- aria-label="Search mode options"
+ :aria-label="searchCopy.modeOptionsLabel"
class="ov-docs-search-mode-menu"
role="listbox"
>
@@ -545,7 +529,7 @@ onUnmounted(() => {
<input
ref="inputRef"
v-model="query"
- aria-label="Search OpenViking docs"
+ :aria-label="searchCopy.inputLabel"
class="ov-docs-search-input"
:placeholder="activeMode.placeholder"
type="search"
@@ -556,12 +540,12 @@ onUnmounted(() => {
<p v-if="notice" class="ov-docs-search-notice">{{ notice }}</p>
<div class="ov-docs-search-results">
- <p v-if="isLoading" class="ov-docs-search-empty">Searching...</p>
+ <p v-if="isLoading" class="ov-docs-search-empty">{{ searchCopy.empty.loading }}</p>
<p v-else-if="trimmedQuery && resolvedResults.length === 0" class="ov-docs-search-empty">
- No results found.
+ {{ searchCopy.empty.noResults }}
</p>
<p v-else-if="!trimmedQuery" class="ov-docs-search-empty">
- Type a query to search the current language docs.
+ {{ searchCopy.empty.initial }}
</p>
<template v-else>
<a
diff --git a/docs/.vitepress/theme/openviking-search-i18n.test.ts b/docs/.vitepress/theme/openviking-search-i18n.test.ts
new file mode 100644
index 000000000..ed17c3d5f
--- /dev/null
+++ b/docs/.vitepress/theme/openviking-search-i18n.test.ts
@@ -0,0 +1,27 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+import { searchCopyForLocale } from './openviking-search-i18n.ts'
+
+test('returns Chinese search UI copy for zh docs', () => {
+ const copy = searchCopyForLocale('zh')
+
+ assert.equal(copy.trigger, '搜索文档')
+ assert.equal(copy.compactTrigger, '搜索')
+ assert.equal(copy.inputLabel, '搜索 OpenViking 文档')
+ assert.equal(copy.modes.semantic.label, '语义搜索')
+ assert.equal(copy.modes.keyword.placeholder, '搜索文档中的精确词句')
+ assert.equal(copy.empty.noResults, '未找到相关结果。')
+ assert.equal(copy.notice('timeout', 2), 'OpenViking 搜索超时。正在显示本地文档结果。')
+ assert.equal(copy.notice('rate_limited', 0), 'OpenViking 搜索请求过多。未找到本地结果。')
+})
+
+test('keeps English search UI copy as the default locale', () => {
+ const copy = searchCopyForLocale('en')
+
+ assert.equal(copy.trigger, 'Search docs')
+ assert.equal(copy.compactTrigger, 'Search')
+ assert.equal(copy.inputLabel, 'Search OpenViking docs')
+ assert.equal(copy.modes.semantic.label, 'Semantic')
+ assert.equal(copy.empty.initial, 'Type a query to search the current language docs.')
+})
diff --git a/docs/.vitepress/theme/openviking-search-i18n.ts b/docs/.vitepress/theme/openviking-search-i18n.ts
new file mode 100644
index 000000000..8434e8d69
--- /dev/null
+++ b/docs/.vitepress/theme/openviking-search-i18n.ts
@@ -0,0 +1,109 @@
+import type { SearchLocale, SearchMode } from './openviking-search-results'
+
+export type RemoteSearchFailureReason = 'rate_limited' | 'timeout' | 'unavailable'
+
+type ModeCopy = {
+ label: string
+ placeholder: string
+}
+
+type SearchCopy = {
+ compactTrigger: string
+ dialogLabel: string
+ empty: {
+ initial: string
+ loading: string
+ noResults: string
+ }
+ inputLabel: string
+ modeLabel: string
+ modeOptionsLabel: string
+ modes: Record<SearchMode, ModeCopy>
+ notice: (reason: RemoteSearchFailureReason, localResultCount: number) => string
+ trigger: string
+}
+
+const searchCopy: Record<SearchLocale, SearchCopy> = {
+ en: {
+ compactTrigger: 'Search',
+ dialogLabel: 'OpenViking docs search',
+ empty: {
+ initial: 'Type a query to search the current language docs.',
+ loading: 'Searching...',
+ noResults: 'No results found.'
+ },
+ inputLabel: 'Search OpenViking docs',
+ modeLabel: 'Search mode',
+ modeOptionsLabel: 'Search mode options',
+ modes: {
+ file: {
+ label: 'File',
+ placeholder: 'Find docs by path or filename'
+ },
+ keyword: {
+ label: 'Keyword',
+ placeholder: 'Search exact words in the docs'
+ },
+ semantic: {
+ label: 'Semantic',
+ placeholder: 'Ask a question about the docs'
+ }
+ },
+ notice: (reason, localResultCount) => {
+ const prefix =
+ reason === 'rate_limited'
+ ? 'OpenViking search is rate limited.'
+ : reason === 'timeout'
+ ? 'OpenViking search timed out.'
+ : 'OpenViking search is unavailable.'
+
+ return localResultCount > 0
+ ? `${prefix} Showing local docs results.`
+ : `${prefix} No local results found.`
+ },
+ trigger: 'Search docs'
+ },
+ zh: {
+ compactTrigger: '搜索',
+ dialogLabel: 'OpenViking 文档搜索',
+ empty: {
+ initial: '输入关键词,搜索当前语言的文档。',
+ loading: '搜索中...',
+ noResults: '未找到相关结果。'
+ },
+ inputLabel: '搜索 OpenViking 文档',
+ modeLabel: '搜索模式',
+ modeOptionsLabel: '搜索模式选项',
+ modes: {
+ file: {
+ label: '文件搜索',
+ placeholder: '按路径或文件名查找文档'
+ },
+ keyword: {
+ label: '关键词搜索',
+ placeholder: '搜索文档中的精确词句'
+ },
+ semantic: {
+ label: '语义搜索',
+ placeholder: '询问文档内容'
+ }
+ },
+ notice: (reason, localResultCount) => {
+ const prefix =
+ reason === 'rate_limited'
+ ? 'OpenViking 搜索请求过多。'
+ : reason === 'timeout'
+ ? 'OpenViking 搜索超时。'
+ : 'OpenViking 搜索暂不可用。'
+
+ return localResultCount > 0
+ ? `${prefix}正在显示本地文档结果。`
+ : `${prefix}未找到本地结果。`
+ },
+ trigger: '搜索文档'
+ }
+}
+
+export function searchCopyForLocale(locale: SearchLocale) {
+ return searchCopy[locale] ?? searchCopy.en
+}
diff --git a/docs/.vitepress/theme/openviking-search-results.test.ts b/docs/.vitepress/theme/openviking-search-results.test.ts
new file mode 100644
index 000000000..6e7ba1677
--- /dev/null
+++ b/docs/.vitepress/theme/openviking-search-results.test.ts
@@ -0,0 +1,53 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+import {
+ enrichSearchResultsWithLocalTitles,
+ localizeSearchResultTitles
+} from './openviking-search-results.ts'
+
+test('uses the localized docs index title for Chinese remote results', () => {
+ const results = enrichSearchResultsWithLocalTitles(
+ [
+ {
+ relativePath: 'agent-integrations/08-community-plugins.md',
+ snippet: '这是一份面向 OpenViking 使用者的社区插件参考文档。',
+ title: 'Community Plugins',
+ url: '/zh/agent-integrations/08-community-plugins'
+ }
+ ],
+ [
+ {
+ locale: 'zh',
+ path: 'zh/agent-integrations/08-community-plugins.md',
+ text: '社区插件',
+ title: '社区插件',
+ url: '/zh/agent-integrations/08-community-plugins'
+ }
+ ],
+ 'zh'
+ )
+
+ assert.equal(results[0].title, '社区插件')
+})
+
+test('keeps remote results when local title lookup fails', async () => {
+ const remoteResults = [
+ {
+ relativePath: 'agent-integrations/08-community-plugins.md',
+ snippet: 'remote snippet',
+ title: 'Community Plugins',
+ url: '/zh/agent-integrations/08-community-plugins'
+ }
+ ]
+
+ const results = await localizeSearchResultTitles(
+ remoteResults,
+ 'zh',
+ async () => {
+ throw new Error('local index unavailable')
+ }
+ )
+
+ assert.deepEqual(results, remoteResults)
+})
diff --git a/docs/.vitepress/theme/openviking-search-results.ts b/docs/.vitepress/theme/openviking-search-results.ts
new file mode 100644
index 000000000..2af890d0f
--- /dev/null
+++ b/docs/.vitepress/theme/openviking-search-results.ts
@@ -0,0 +1,124 @@
+export type SearchLocale = 'en' | 'zh'
+export type SearchMode = 'semantic' | 'keyword' | 'file'
+
+export type DocsIndexRecord = {
+ locale: SearchLocale
+ path: string
+ text: string
+ title: string
+ url: string
+}
+
+export type DocsSearchResult = {
+ line?: number | null
+ mode?: SearchMode
+ relativePath?: string
+ score?: number | null
+ snippet?: string
+ title?: string
+ uri?: string
+ url?: string
+}
+
+type LocalIndexLoader = () => Promise<DocsIndexRecord[]>
+
+export async function localizeSearchResultTitles(
+ results: DocsSearchResult[],
+ locale: SearchLocale,
+ loadLocalIndex: LocalIndexLoader
+) {
+ try {
+ const localIndex = await loadLocalIndex()
+ return enrichSearchResultsWithLocalTitles(results, localIndex, locale)
+ } catch {
+ return results
+ }
+}
+
+export function enrichSearchResultsWithLocalTitles(
+ results: DocsSearchResult[],
+ localIndex: DocsIndexRecord[],
+ locale: SearchLocale
+) {
+ const titleByKey = buildLocalTitleLookup(localIndex, locale)
+
+ return results.map((result) => {
+ const title = localizedTitleForResult(result, titleByKey, locale)
+ return title && title !== result.title ? { ...result, title } : result
+ })
+}
+
+function buildLocalTitleLookup(localIndex: DocsIndexRecord[], locale: SearchLocale) {
+ const titleByKey = new Map<string, string>()
+
+ for (const record of localIndex) {
+ if (record.locale !== locale || !record.title) continue
+
+ for (const key of localRecordKeys(record, locale)) {
+ titleByKey.set(key, record.title)
+ }
+ }
+
+ return titleByKey
+}
+
+function localizedTitleForResult(
+ result: DocsSearchResult,
+ titleByKey: Map<string, string>,
+ locale: SearchLocale
+) {
+ for (const key of resultKeys(result, locale)) {
+ const title = titleByKey.get(key)
+ if (title) return title
+ }
+
+ return result.title
+}
+
+function localRecordKeys(record: DocsIndexRecord, locale: SearchLocale) {
+ return [
+ normalizeDocsUrl(record.url),
+ normalizeLocalizedPath(record.path, locale),
+ normalizeDocsUrl(urlFromRelativePath(record.path, locale))
+ ].filter(Boolean)
+}
+
+function resultKeys(result: DocsSearchResult, locale: SearchLocale) {
+ return [
+ normalizeDocsUrl(result.url),
+ normalizeLocalizedPath(result.relativePath, locale),
+ normalizeDocsUrl(urlFromRelativePath(result.relativePath, locale)),
+ normalizeDocsUrl(urlFromVikingUri(result.uri))
+ ].filter(Boolean)
+}
+
+function normalizeDocsUrl(value: string | undefined) {
+ if (!value) return ''
+
+ const pathname = value.replace(/^https?:\/\/[^/]+/, '').split(/[?#]/, 1)[0]
+ return `/${pathname.replace(/^\/+/, '')}`.replace(/\/index$/, '')
+}
+
+function normalizeLocalizedPath(value: string | undefined, locale: SearchLocale) {
+ if (!value) return ''
+
+ return value
+ .replace(/^\/+/, '')
+ .replace(/^docs\//, '')
+ .replace(new RegExp(`^${locale}/`), '')
+ .replace(/(?:\/index)?\.mdx?$/, '')
+}
+
+function urlFromRelativePath(value: string | undefined, locale: SearchLocale) {
+ const normalizedPath = normalizeLocalizedPath(value, locale)
+ return normalizedPath ? `/${locale}/${normalizedPath}` : ''
+}
+
+function urlFromVikingUri(value: string | undefined) {
+ if (!value) return ''
+
+ const match = value.match(/\/docs\/(en|zh)\/(.+)$/)
+ if (!match) return ''
+
+ return `/${match[1]}/${match[2].replace(/(?:\/index)?\.mdx?$/, '')}`
+}
diff --git a/docs/package.json b/docs/package.json
index ce1d28f05..d7d42f56f 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -6,7 +6,8 @@
"scripts": {
"docs:dev": "vitepress dev . --host 0.0.0.0",
"docs:build": "vitepress build .",
- "docs:preview": "vitepress preview . --host 0.0.0.0"
+ "docs:preview": "vitepress preview . --host 0.0.0.0",
+ "test:search": "node --experimental-strip-types --test .vitepress/theme/openviking-search-*.test.ts"
},
"devDependencies": {
"vitepress": "1.6.4"