多语言支持

学习如何在多语言 VitePress 项目中使用 VitePress Sidebar Tags Plugin。

🌍 多语言配置概述

VitePress Sidebar Tags Plugin 完全支持 VitePress 的多语言功能，可以为不同语言的侧边栏自动添加标签。

🚀 基础多语言配置

1. 项目结构

docs/
├── .vitepress/
│   └── config.ts
├── index.md
├── zh/
│   ├── index.md
│   ├── api/
│   │   ├── users.md
│   │   └── create-user.md
│   └── guide/
│       └── introduction.md
└── en/
    ├── index.md
    ├── api/
    │   ├── users.md
    │   └── create-user.md
    └── guide/
        └── introduction.md

2. 配置文件设置

typescript

// .vitepress/config.ts
import { defineConfig } from 'vitepress'
import { withMultiSidebarTags, createHttpMethodsTag, createVersionTag } from 'vitepress-plugin-sidebar-tags'

// 中文侧边栏
const zhSidebar = [
  {
    text: 'API 文档',
    items: [
      { text: '用户管理', link: '/zh/api/users' },
      { text: '创建用户', link: '/zh/api/create-user' }
    ]
  },
  {
    text: '指南',
    items: [
      { text: '介绍', link: '/zh/guide/introduction' }
    ]
  }
]

// 英文侧边栏
const enSidebar = [
  {
    text: 'API Documentation',
    items: [
      { text: 'User Management', link: '/en/api/users' },
      { text: 'Create User', link: '/en/api/create-user' }
    ]
  },
  {
    text: 'Guide',
    items: [
      { text: 'Introduction', link: '/en/guide/introduction' }
    ]
  }
]

// 多语言侧边栏配置
const multiSidebar = {
  '/zh/': zhSidebar,
  '/en/': enSidebar
}

export default defineConfig({
  title: 'VitePress Sidebar Tags',
  description: 'A powerful VitePress plugin for sidebar tags',
  
  // 多语言配置
  locales: {
    root: {
      label: '简体中文',
      lang: 'zh-CN'
    },
    en: {
      label: 'English',
      lang: 'en-US',
      title: 'VitePress Sidebar Tags',
      description: 'A powerful VitePress plugin for sidebar tags'
    }
  },

  themeConfig: {
    // 使用多语言侧边栏标签
    sidebar: withMultiSidebarTags(multiSidebar, [
      createHttpMethodsTag({
        rounded: 'sm',
        size: 'xs'
      }),
      createVersionTag({
        color: 'blue',
        rounded: 'md'
      })
    ], {
      docsPath: 'docs',
      debug: true
    })
  }
})

🏷️ 语言特定标签

中文标签配置

typescript

// 中文环境下的自定义标签
const zhTags = [
  createHttpMethodsTag({
    rounded: 'sm',
    size: 'xs'
  }),
  {
    field: 'difficulty',
    position: 'after',
    size: 'xs',
    variant: 'outline',
    color: 'warning',
    rounded: 'md',
    prefix: '难度: ',
    valueStyles: {
      'easy': { color: 'success' },
      'medium': { color: 'warning' },
      'hard': { color: 'error' }
    }
  },
  {
    field: 'status',
    position: 'after',
    size: 'xs',
    variant: 'soft',
    color: 'gray',
    rounded: 'lg',
    valueStyles: {
      'stable': { color: 'success' },
      'beta': { color: 'warning' },
      'experimental': { color: 'error' }
    }
  }
]

英文标签配置

typescript

// 英文环境下的自定义标签
const enTags = [
  createHttpMethodsTag({
    rounded: 'sm',
    size: 'xs'
  }),
  {
    field: 'difficulty',
    position: 'after',
    size: 'xs',
    variant: 'outline',
    color: 'warning',
    rounded: 'md',
    prefix: 'Level: ',
    valueStyles: {
      'beginner': { color: 'success' },
      'intermediate': { color: 'warning' },
      'advanced': { color: 'error' }
    }
  },
  {
    field: 'status',
    position: 'after',
    size: 'xs',
    variant: 'soft',
    color: 'gray',
    rounded: 'lg',
    valueStyles: {
      'stable': { color: 'success' },
      'beta': { color: 'warning' },
      'experimental': { color: 'error' }
    }
  }
]

📝 多语言 Frontmatter 示例

中文文档示例

markdown

---
method: GET
difficulty: easy
status: stable
version: v1.0
---

# 用户管理 API

这是一个用于获取用户列表的 API 接口。

## 请求参数

| 参数 | 类型 | 说明 |
|------|------|------|
| page | number | 页码 |
| limit | number | 每页数量 |

## 响应示例

```json
{
  "code": 200,
  "message": "获取成功",
  "data": []
}


### 英文文档示例

```markdown
---
method: GET
difficulty: beginner
status: stable
version: v1.0
---

# User Management API

This API endpoint is used to retrieve a list of users.

## Request Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| page | number | Page number |
| limit | number | Items per page |

## Response Example

```json
{
  "code": 200,
  "message": "Success",
  "data": []
}


## 🔧 高级多语言配置

### 条件语言配置

```typescript
import { defineConfig } from 'vitepress'

// 根据语言环境选择不同的标签配置
function getTagsForLocale(locale: string) {
  const baseConfig = [
    createHttpMethodsTag({ size: 'xs', rounded: 'sm' }),
    createVersionTag({ color: 'blue', rounded: 'md' })
  ]

  if (locale === 'zh') {
    return [
      ...baseConfig,
      {
        field: 'difficulty',
        prefix: '难度: ',
        valueStyles: {
          'easy': { color: 'success' },
          'medium': { color: 'warning' },
          'hard': { color: 'error' }
        }
      }
    ]
  }

  if (locale === 'en') {
    return [
      ...baseConfig,
      {
        field: 'difficulty',
        prefix: 'Level: ',
        valueStyles: {
          'beginner': { color: 'success' },
          'intermediate': { color: 'warning' },
          'advanced': { color: 'error' }
        }
      }
    ]
  }

  return baseConfig
}

export default defineConfig({
  // ... 其他配置
  themeConfig: {
    sidebar: withMultiSidebarTags(multiSidebar, getTagsForLocale('zh'))
  }
})

动态路径检测

typescript

// 自动检测语言路径并应用相应配置
const sidebarConfig = {
  '/': defaultSidebar,
  '/zh/': zhSidebar,
  '/en/': enSidebar,
  '/fr/': frSidebar,
  '/de/': deSidebar
}

export default defineConfig({
  themeConfig: {
    sidebar: withMultiSidebarTags(sidebarConfig, [
      createHttpMethodsTag(),
      createVersionTag()
    ], {
      docsPath: 'docs',
      autoDetectLocale: true // 自动检测语言环境
    })
  }
})

🎨 语言特定样式

CSS 变量覆盖

css

/* 中文环境样式 */
[lang="zh-CN"] .sidebar-tag {
  font-family: "PingFang SC", "Microsoft YaHei", sans-serif;
  letter-spacing: 0.5px;
}

/* 英文环境样式 */
[lang="en-US"] .sidebar-tag {
  font-family: "Inter", "Roboto", sans-serif;
  letter-spacing: 0.025em;
}

/* 日文环境样式 */
[lang="ja-JP"] .sidebar-tag {
  font-family: "Hiragino Sans", "Yu Gothic", sans-serif;
}

响应式语言切换

css

/* 移动端多语言适配 */
@media (max-width: 768px) {
  [lang="zh-CN"] .sidebar-tag {
    font-size: 10px;
    padding: 1px 4px;
  }
  
  [lang="en-US"] .sidebar-tag {
    font-size: 9px;
    padding: 1px 3px;
  }
}

📱 最佳实践

1. 统一标签字段

typescript

// 在所有语言中使用相同的 frontmatter 字段名
// ✅ 推荐
---
method: GET
status: stable
difficulty: easy
---

// ❌ 避免
---
方法: GET
状态: 稳定
难度: 简单
---

2. 语言特定值转换

typescript

{
  field: 'status',
  transform: (value, locale) => {
    const translations = {
      'zh': {
        'stable': '稳定',
        'beta': '测试',
        'experimental': '实验'
      },
      'en': {
        'stable': 'Stable',
        'beta': 'Beta',
        'experimental': 'Experimental'
      }
    }
    return translations[locale]?.[value] || value
  }
}

3. 一致的样式配置

typescript

// 在所有语言中保持一致的视觉风格
const globalTagConfig = {
  size: 'xs',
  variant: 'soft',
  rounded: 'md'
}

const zhTags = [
  { ...globalTagConfig, field: 'method' },
  { ...globalTagConfig, field: 'status' }
]

const enTags = [
  { ...globalTagConfig, field: 'method' },
  { ...globalTagConfig, field: 'status' }
]

🔍 故障排除

常见问题

标签不显示
- 检查语言路径配置是否正确
- 确认 frontmatter 字段名一致
- 验证 docsPath 设置
样式不一致
- 检查 CSS 语言选择器
- 确认字体设置
- 验证响应式配置
路径错误
- 检查多语言路径配置
- 确认文件结构
- 验证链接路径

下一步

样式定制 - 学习自定义样式
自定义标签 - 创建自定义标签
示例库 - 查看多语言示例

多语言支持 ​

🌍 多语言配置概述 ​

🚀 基础多语言配置 ​

1. 项目结构 ​

2. 配置文件设置 ​

🏷️ 语言特定标签 ​

中文标签配置 ​

英文标签配置 ​

📝 多语言 Frontmatter 示例 ​

中文文档示例 ​

动态路径检测 ​

🎨 语言特定样式 ​

CSS 变量覆盖 ​

响应式语言切换 ​

📱 最佳实践 ​

1. 统一标签字段 ​

2. 语言特定值转换 ​

3. 一致的样式配置 ​

🔍 故障排除 ​

常见问题 ​

下一步 ​

多语言支持

🌍 多语言配置概述

🚀 基础多语言配置

1. 项目结构

2. 配置文件设置

🏷️ 语言特定标签

中文标签配置

英文标签配置

📝 多语言 Frontmatter 示例

中文文档示例

动态路径检测

🎨 语言特定样式

CSS 变量覆盖

响应式语言切换

📱 最佳实践

1. 统一标签字段

2. 语言特定值转换

3. 一致的样式配置

🔍 故障排除

常见问题

下一步