国际化
要使用内置的 i18n (国际化) 功能,需要创建类似于下面的目录结构:
docs/
├─ es/
│ ├─ foo.md
├─ fr/
│ ├─ foo.md
├─ foo.md
docs/
├─ es/
│ ├─ foo.md
├─ fr/
│ ├─ foo.md
├─ foo.md
然后在 docs/.vitepress/config.ts
中:
import { defineConfig } from 'vitepress'
export default defineConfig({
// shared properties and other top-level stuff...
locales: {
root: {
label: 'English',
lang: 'en'
},
fr: {
label: 'French',
lang: 'fr', // optional, will be added as `lang` attribute on `html` tag
link: '/fr/guide' // default /fr/ -- shows on navbar translations menu, can be external
// other locale specific properties...
}
}
})
import { defineConfig } from 'vitepress'
export default defineConfig({
// shared properties and other top-level stuff...
locales: {
root: {
label: 'English',
lang: 'en'
},
fr: {
label: 'French',
lang: 'fr', // optional, will be added as `lang` attribute on `html` tag
link: '/fr/guide' // default /fr/ -- shows on navbar translations menu, can be external
// other locale specific properties...
}
}
})
下面的属性能够被每个 locale 覆盖 (包括 root):
interface LocaleSpecificConfig<ThemeConfig = any> {
lang?: string
dir?: string
title?: string
titleTemplate?: string | boolean
description?: string
head?: HeadConfig[] // will be merged with existing head entries, duplicate meta tags are automatically removed
themeConfig?: ThemeConfig // will be shallow merged, common stuff can be put in top-level themeConfig entry
}
interface LocaleSpecificConfig<ThemeConfig = any> {
lang?: string
dir?: string
title?: string
titleTemplate?: string | boolean
description?: string
head?: HeadConfig[] // will be merged with existing head entries, duplicate meta tags are automatically removed
themeConfig?: ThemeConfig // will be shallow merged, common stuff can be put in top-level themeConfig entry
}
有关自定义默认主题的文本占位符的信息,请参考 DefaultTheme.Config
接口。不要在 locale 级别覆盖 themeConfig.algolia
或 themeConfig.carbonAds
。想获取多语言查询的信息,请参考 Algolia docs。
提示: 配置文件也可以存储在 docs/.vitepress/config/index.ts
。通过为每个语言环境创建一个配置文件,然后从 index.ts
合并并导出它们,你可以更好的组织文件。
为本地化设置子目录
下面是一个组织良好的结构:
docs/
├─ en/
│ ├─ foo.md
├─ es/
│ ├─ foo.md
├─ fr/
├─ foo.md
docs/
├─ en/
│ ├─ foo.md
├─ es/
│ ├─ foo.md
├─ fr/
├─ foo.md
但是,VitePress 默认不会将 /
重定向到 /en/
。你需要配置你的服务来实现这一点。例如,在使用 Netlify 时,你可以添加一个 docs/public/_redirects
文件,如下所示:
/* /es/:splat 302 Language=es
/* /fr/:splat 302 Language=fr
/* /en/:splat 302
/* /es/:splat 302 Language=es
/* /fr/:splat 302 Language=fr
/* /en/:splat 302
提示: 如果使用上述的方法,你可以使用nf_lang
cookie 来保存用户的语言选择。一个非常基础的方法是通过在自定义主题的 setup 函数中注册一个侦听器:
// docs/.vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
export default {
...DefaultTheme,
setup() {
const { lang } = useData()
watchEffect(() => {
if (inBrowser) {
document.cookie = `nf_lang=${lang.value}; expires=Mon, 1 Jan 2024 00:00:00 UTC; path=/`
}
})
}
}
// docs/.vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
export default {
...DefaultTheme,
setup() {
const { lang } = useData()
watchEffect(() => {
if (inBrowser) {
document.cookie = `nf_lang=${lang.value}; expires=Mon, 1 Jan 2024 00:00:00 UTC; path=/`
}
})
}
}
RTL 支持 (实验性功能)
要支持 RTL,需要在配置中指定 dir: 'rtl'
并且使用一些 RTLCSS PostCSS 插件,例如 https://github.com/MohammadYounes/rtlcss, https://github.com/vkalinichev/postcss-rtl 或者 https://github.com/elchininet/postcss-rtlcss。你需要配置 PostCSS 插件,使用 :where([dir="ltr"])
和 :where([dir="rtl"])
作为前缀,以防止 CSS 特异性问题。