J

主题

2025-03-072025-07-03指南指南
1588
7.8m
Get...

国际化 ​

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*",
  },
});
最近更新