One

主题

2025-03-072025-10-31指南指南
1588
7.8m
0

文章发布较早，内容可能过时，阅读注意甄别。

国际化 ​

Teek 默认使用中文，如果你希望使用其他语言，你可以参考下面的方案。

全局语言配置 v1.1.0 ​

在 Teek.Layout 组件传入 locale 参数，即可设置默认语言。

ts
// .vitepress/config.mts
import Teek, { en } from 'vitepress-theme-teek'
import 'vitepress-theme-teek/index.css'

export default {
  extends: Teek,
  Layout: h(Teek.Layout, { locale: en }),
}

如果希望根据 VitePress 的国际化动态切换语言，可以定义一个组件 TeekLayoutProvider.vue。

TeekLayoutProvider.vue
vue
<script setup lang="ts">
import Teek, { zhCn, en } from 'vitepress-theme-teek'
import { useData } from 'vitepress'
import { computed } from 'vue'

const { lang } = useData()

const locale = computed(() => {
  if (lang.value === 'zh-CN') return zhCn
  return en
})
</script>

<template>
  <Teek.Layout :locale />
</template>

然后在 .vitepress/theme/index.ts 中传入 TeekLayoutProvider 组件。

ts
// .vitepress/theme/index.ts
import Teek, { en } from 'vitepress-theme-teek'
import 'vitepress-theme-teek/index.css'
import TeekLayoutProvider from '../components/TeekLayoutProvider.vue'

export default {
  extends: Teek,
  Layout: TeekLayoutProvider,
}

lang 是 VitePress 国际化的一个配置项：

ts
import { defineConfig } from 'vitepress'

export default defineConfig({
  locales: {
    root: { lang: 'zh-CN' },
    en: { lang: 'en' },
  },
})

语言列表 ​

Teek 目前支持以下语言：

  • 简体中文（zh-cn）
  • English（en）

自定义语言 ​

如果你需要使用其他的语言，可以添加一个语言配置文件。

比如需要添加繁体中文（zh-tw）语言，步骤如下：

  1. 创建 .vitepress/theme/locale/zh-tw.ts 文件（路径位置任意）
  2. 然后参考 Teek 现有的任一 语言文件，将里面的内容拷贝到 zh-tw.ts 文件中，并将所有内容（Value）修改为 zh-tw 语言
  3. 最后通过 locale 属性传入到 Teek.Layout 组件中
TeekLayoutProvider.vue
vue
<script setup lang="ts">
import Teek from 'vitepress-theme-teek'
import { useData } from 'vitepress'
import zhTw from '../locale/zh-tw'

const { lang } = useData()
</script>

<template>
  <Teek.Layout :locale="zhTw" />
</template>

provide 方式 ​

除了通过 locale 属性传入语言配置，Teek 也支持通过 provide 方式传入语言配置：

vue
<script setup lang="ts">
import Teek, { localeContextKey, en } from 'vitepress-theme-teek'
import { provide } from 'vue'

provide(
  localeContextKey,
  computed(() => en) // 必须是 computer 或者 ref
)
</script>

<template>
  <Teek.Layout />
</template>

国际化下配置文件 ​

VitePress 配置 ​

假设国际化环境下，配置文件目录如下：

sh
.vitepress
├─ locales
│  ├─ zh.ts       # 中文配置
│  ├─ shared.ts   # 共享配置
│  ├─ en.ts       # 英文配置
│  ├─ xx.ts       # 其他语言配置
├─ config.mts

.vitepress/config.mts 内容如下：

ts
// .vitepress/config.mts
import { defineConfig } from 'vitepress'
import shared from './locales/shared'
import zh from './locales/zh'
import en from './locales/en'

export default defineConfig({
  ...shared,
  locales: {
    root: { label: '简体中文', ...zh },
    en: { label: 'English', ...en },
  },
})

VitePress 默认会对 shared.ts 和当前语言的配置文件进行合并，且配置同名时，以当前语言配置为主，如 zh.ts 和 en.ts 会覆盖 shared.ts 中的同名配置。

利用这个机制，你可以在 shared.ts 中定义一些通用的配置，然后 zh.ts 和 en.ts 里配置不同语言的配置，如：

ts
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'Hd Security',
  cleanUrls: false,
  lastUpdated: true,

  head: [
    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/teek-logo-mini.svg' }],
    ['link', { rel: 'icon', type: 'image/png', href: '/teek-logo-mini.png' }],
    ['meta', { property: 'og:type', content: 'website' }],
    ['meta', { property: 'og:locale', content: 'zh-CN' }],
    ['meta', { property: 'og:title', content: 'Teek | VitePress Theme' }],
    ['meta', { name: 'author', content: 'Teek' }],
    [
      'meta',
      {
        name: 'viewport',
        content: 'width=device-width,initial-scale=1,minimum-scale=1.0,maximum-scale=1.0,user-scalable=no',
      },
    ],
    ['link', { rel: 'icon', href: '/favicon.ico', type: 'image/png' }],
    ['link', { rel: 'stylesheet', href: '//at.alicdn.com/t/font_2989306_w303erbip9.css' }], // 阿里在线矢量库
  ],

  markdown: {
    lineNumbers: true,
  },

  // https://vitepress.dev/reference/default-theme-config
  themeConfig: {
    logo: 'https://testingcf.jsdelivr.net/gh/Kele-Bingtang/static/user/avatar1.png',
    search: {
      provider: 'local',
    },
  },
})
ts
import { defineConfig } from 'vitepress'

const description = ['Teek 使用文档', 'VitePress 主题'].toString()

export default defineConfig({
  lang: 'zh-CN',
  description: description,
  head: [
    ['meta', { name: 'description', description }],
    ['meta', { name: 'keywords', description }],
  ],
  markdown: {
    container: {
      tipLabel: '提示',
      warningLabel: '警告',
      dangerLabel: '危险',
      infoLabel: '信息',
      detailsLabel: '详细信息',
    },
  },
  themeConfig: {
    darkModeSwitchLabel: '主题',
    sidebarMenuLabel: '菜单',
    returnToTopLabel: '返回顶部',
    lastUpdatedText: '上次更新时间',
    outline: {
      level: [2, 4],
      label: '本页导航',
    },
    docFooter: {
      prev: '上一页',
      next: '下一页',
    },
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/intro' },
      { text: '配置', link: '/reference/config' },
      { text: '开发', link: '/develop/intro' },
      { text: '归档', link: '/archives' },
    ],
    editLink: {
      text: '在 GitHub 上编辑此页',
      pattern: 'https://github.com/Kele-Bingtang/vitepress-theme-teek/edit/master/docs/:path',
    },
  },
})
ts
import { defineConfig } from 'vitepress'

const description = ['Teek Documentation', 'VitePress Theme'].toString()

export default defineConfig({
  lang: 'en-US',
  description: description,
  head: [
    ['meta', { name: 'description', description }],
    ['meta', { name: 'keywords', description }],
  ],
  markdown: {
    container: {
      tipLabel: 'Tip',
      warningLabel: 'Warning',
      dangerLabel: 'Danger',
      infoLabel: 'Info',
      detailsLabel: 'Details',
    },
  },
  themeConfig: {
    ...teekConfig.themeConfig,
    darkModeSwitchLabel: 'Theme',
    sidebarMenuLabel: 'Menu',
    returnToTopLabel: 'To Top',
    lastUpdatedText: 'LastUpdated',
    outline: {
      level: [2, 4],
      label: 'Page Navigation',
    },
    docFooter: {
      prev: 'prev',
      next: 'next',
    },
    nav: [
      { text: 'index', link: '/en' },
      { text: 'guide', link: '/guide/intro' },
      { text: 'reference', link: '/reference/config' },
      { text: 'develop', link: '/develop/intro' },
      { text: 'archives', link: '/en/archives' },
    ],
    editLink: {
      text: 'Edit this page on GitHub',
      pattern: 'https://github.com/Kele-Bingtang/vitepress-theme-teek/edit/master/docs/:path',
    },
  },
})

Teek 配置 ​

在非国际化配置文件里下，您可以直接在 VitePress 的配置里使用 extends 来继承 Teek 的配置，但是在国际化配置文件下，extends 配置会失效。

因此需要将 Teek 配置的 themeConfig 手动添加到 VitePress 的 themeConfig 里。

ts
import { defineConfig } from 'vitepress'
import { defineTeekConfig } from 'vitepress-theme-teek/config'

const teekConfig = defineTeekConfig({
  // 公共配置 ...
})

export default defineConfig({
  extends: teekConfig,
  // ...
})
ts
import { defineConfig } from 'vitepress'
import { defineTeekConfig } from 'vitepress-theme-teek/config'

const teekConfig = defineTeekConfig({
  // zh 配置下配置 ...
})

export default defineConfig({
  themeConfig: {
    ...teekConfig.themeConfig,
    // ...
  },
})
ts
import { defineConfig } from 'vitepress'
import { defineTeekConfig } from 'vitepress-theme-teek/config'

const teekConfig = defineTeekConfig({
  // ...
})

export default defineConfig({
  themeConfig: {
    ...teekConfig.themeConfig,
    // en 环境下配置 ...
  },
})

举个例子，您可以在中文和英文环境下分别取不同的名字：

ts
import { defineConfig } from 'vitepress'
import { defineTeekConfig } from 'vitepress-theme-teek/config'

const teekConfig = defineTeekConfig({
  blogger: {
    name: '天客',
    slogan: '朝圣的使徒，正在走向编程的至高殿堂！',
  },
})

export default defineConfig({
  themeConfig: {
    ...teekConfig.themeConfig,
    // ...
  },
})
ts
import { defineConfig } from 'vitepress'
import { defineTeekConfig } from 'vitepress-theme-teek/config'

const teekConfig = defineTeekConfig({
  blogger: {
    name: 'Teeker',
    slogan: 'Code Pilgrims march to the summit of code mastery!',
  },
})

export default defineConfig({
  themeConfig: {
    ...teekConfig.themeConfig,
    // ...
  },
})

给 root 语言添加目录 ​

这里对一个特殊场景进行说明。

VitePress 支持的国际化文档目录如下：

sh
docs/
├─ es/
│  ├─ foo.md
├─ fr/
│  ├─ foo.md
├─ foo.md

根目录下的 foo.md 是 root 语言（默认语言）的文档，当 Markdown 文件多起来时，根目录下文件显得很拥挤，那么可以将这些文档放到一个目录下，假设默认语言是 zh，则：

sh
docs/
├─ es/
│  ├─ foo.md
├─ fr/
│  ├─ foo.md
├─ zh/
│  ├─ foo.md

但是 VitePress 无法感知到 root 语言（默认语言）的文档已经放到 zh 目录下，它依然只扫描根目录的 Markdown 文件作为默认语言的文档，因此需要使用 VitePress 提供的 rewrites 进行重定向，同时 Teek 也无法感知文档进行了移动，因此需要配置 vitePlugins.sidebarOption.localeRootDir

ts
import { defineConfig } from 'vitepress'
import { defineTeekConfig } from 'vitepress-theme-teek/config'

// Teek 主题配置
const teekConfig = defineTeekConfig({
  vitePlugins: {
    sidebarOption: {
      localeRootDir: 'zh',
    },
  },
})

// VitePress 配置
export default defineConfig({
  rewrites: {
    'zh/:rest*': ':rest*',
  },
})
最近更新