GitBook Language Selector Plugin

一个用于 GitBook 的多语言选择器插件，支持在文档中添加语言切换功能。

安装

在你的 GitBook 项目的 book.json 文件中添加插件：

{
    "plugins": ["language-selector"]
}

配置

默认配置

插件默认支持英文和中文两种语言：

{
    "plugins": ["language-selector"],
    "pluginsConfig": {
        "language-selector": {
            "languages": [
                { "code": "en", "name": "English" },
                { "code": "zh", "name": "中文" }
            ],
            "defaultLanguage": "en",
            "label": {
                "en": "Language",
                "zh": "语言"
            }
        }
    }
}

自定义多语言配置

你可以通过配置添加更多语言：

{
    "plugins": ["language-selector"],
    "pluginsConfig": {
        "language-selector": {
            "languages": [
                { "code": "en", "name": "English" },
                { "code": "zh", "name": "中文" },
                { "code": "ja", "name": "日本語" },
                { "code": "ko", "name": "한국어" },
                { "code": "fr", "name": "Français" },
                { "code": "de", "name": "Deutsch" },
                { "code": "es", "name": "Español" }
            ],
            "defaultLanguage": "en",
            "label": {
                "en": "Language",
                "zh": "语言",
                "ja": "言語",
                "ko": "언어",
                "fr": "Langue",
                "de": "Sprache",
                "es": "Idioma"
            }
        }
    }
}

配置选项

| 选项 | 类型 | 默认值 | 描述 | |------|------|--------|------| | languages | Array | [{code: "en", name: "English"}, {code: "zh", name: "中文"}] | 支持的语言列表 | | defaultLanguage | String | "en" | 默认语言代码 | | label | Object | {en: "Language", zh: "语言"} | 各语言下的标签文本 |

languages 配置

每个语言对象包含：

• code: 语言代码（用于URL路径，如 /en/, /zh/）
• name: 显示在选择器中的语言名称

label 配置

为不同语言设置选择器的标签文本。键为语言代码，值为该语言下显示的标签。

目录结构

使用此插件时，你的 GitBook 项目应该按以下结构组织：

your-gitbook/
├── book.json
├── README.md
├── en/
│   ├── README.md
│   ├── chapter1.md
│   └── ...
├── zh/
│   ├── README.md
│   ├── chapter1.md
│   └── ...
└── ja/
    ├── README.md
    ├── chapter1.md
    └── ...

功能特性

• 🌍 支持无限多种语言配置
• 📱 响应式设计，适配移动端
• 🎨 两种显示位置：固定位置和侧边栏
• ⚡ 自动检测当前语言
• 🔄 智能路径切换
• 🔧 页面切换时自动重新初始化

故障排除

页面切换时语言选择器消失

问题：在GitBook中点击不同页面时，语言选择器可能会消失或失效。

原因：GitBook在页面切换时会重新渲染侧边栏，导致语言选择器DOM元素被移除。

解决方案：插件已经内置了以下机制来解决这个问题：

1. 智能检测机制：检查语言选择器是否存在，只在必要时重新创建
2. 平滑更新：如果选择器存在，只更新内容而不重新创建，避免闪烁
3. 事件委托：使用事件委托确保事件监听器不会丢失
4. CSS过渡效果：添加平滑的过渡动画，提升用户体验
5. 延迟初始化：使用适当的延迟确保DOM完全加载后再操作

页面切换时的闪烁问题

问题：页面切换时语言选择器可能会出现闪烁。

解决方案：

1. 避免重复创建：优先检测现有选择器，只在必要时创建新的
2. CSS过渡：使用CSS过渡效果让任何必要的更新都更加平滑
3. 加载状态：新创建的选择器使用loading状态，然后平滑显示
4. 更新状态：更新时添加updating类，提供视觉反馈

语言选择器位置问题

如果语言选择器没有出现在预期位置：

1. 检查侧边栏是否正确加载
2. 确保 .book-summary 元素存在
3. 插件会自动尝试多个位置来放置选择器

配置不生效

确保：

1. book.json 文件格式正确
2. 插件名称为 language-selector
3. 配置放在 pluginsConfig 下的正确位置

使用示例

1. 基础双语配置（英文 + 中文）
2. 多语言配置（支持 7+ 种语言）
3. 自定义标签（为每种语言设置本地化标签）

许可证

MIT License