多语言支持¶

Material for MkDocs提供了强大的多语言支持功能，可以轻松创建多语言文档网站。

基础配置¶

1. 安装依赖¶

pip install mkdocs-i18n

2. 配置多语言¶

在mkdocs.yml中配置多语言支持：

site_name: My Documentation
site_url: https://example.com

plugins:
  - i18n:
      default_language: en
      default_language_only: false
      languages:
        en: English
        zh-CN: 中文
        ja: 日本語
        es: Español
      language_switcher: true
      lang_name: Language
      lang_icon: material/translate
      locale: en_US

      # 自动生成翻译（需要API密钥）
      auto_translate: false

      # 翻译API配置
      translate_api: google
      translate_key: YOUR_API_KEY

      # 语言特定配置
      configs:
        en:
          site_name: English Documentation
          site_description: Documentation in English
          copyright: © 2024 English Docs
        zh-CN:
          site_name: 中文文档
          site_description: 中文文档说明
          copyright: © 2024 中文文档

目录结构¶

替代结构¶

docs/
├── en/
│   ├── index.md
│   ├── about.md
│   └── guides/
│       └── getting-started.md
├── zh-CN/
│   ├── index.md
│   ├── about.md
│   └── guides/
│       └── getting-started.md
├── ja/
│   └── ...
└── index.md              # 语言选择器

语言切换器¶

配置切换器¶

plugins:
  - i18n:
      languages:
        en: English 🇺🇸
        zh-CN: 中文 🇨🇳
        ja: 日本語 🇯🇵
      language_switcher:
        enabled: true
        show_names: true
        show_flags: true
        flag_style: emoji  # 或 emoji, svg

切换器位置¶

theme:
  features:
    - navigation.language  # 在导航栏显示语言切换器
    - footer.language     # 在页脚显示语言切换器

自定义切换器样式¶

/* docs/assets/css/custom.css */

/* 语言切换器按钮 */
.md-language-switcher {
  position: relative;
  display: inline-block;
}

/* 切换器下拉菜单 */
.md-language-switcher__dropdown {
  display: none;
  position: absolute;
  background-color: white;
  min-width: 160px;
  box-shadow: 0 8px 16px rgba(0,0,0,0.1);
  z-index: 1000;
  border-radius: 8px;
  overflow: hidden;
}

.md-language-switcher:hover .md-language-switcher__dropdown {
  display: block;
}

/* 语言选项 */
.md-language-switcher__option {
  display: block;
  padding: 0.75rem 1rem;
  text-decoration: none;
  color: var(--md-text-color);
  transition: background-color 0.2s ease;
}

.md-language-switcher__option:hover {
  background-color: var(--md-background-secondary-color);
}

/* 当前语言高亮 */
.md-language-switcher__option--active {
  background-color: var(--md-primary-fg-color);
  color: white;
  font-weight: 600;
}

/* 移动端样式 */
@media (max-width: 768px) {
  .md-language-switcher__dropdown {
    position: fixed;
    top: 60px;
    left: 0;
    right: 0;
    width: 100%;
  }
}

翻译管理¶

1. 手动翻译¶

为每个页面创建翻译版本：

# docs/en/index.md

# Welcome to My Docs

This is the English version of the documentation.

# docs/zh-CN/index.md

# 欢迎来到我的文档

这是文档的中文版本。

2. 自动翻译¶

配置自动翻译：

plugins:
  - i18n:
      auto_translate: true
      translate_api: google
      translate_key: YOUR_GOOGLE_TRANSLATE_API_KEY
      translate_model: nmt  # 或 base, nmt

      # 翻译选项
      translate_options:
        format: html         # 或 text
        source_lang: en
        target_langs:
          - zh-CN
          - ja
          - es

      # 缓存配置
      cache_translations: true
      cache_dir: .cache/i18n

3. 混合模式¶

plugins:
  - i18n:
      auto_translate: true
      manual_translation_fallback: true  # 优先使用手动翻译
      translate_untranslated: true       # 自动翻译未翻译页面

导航配置¶

多语言导航¶

nav:
  - Home: index.md
  - About: about.md
  - Guides:
    - Getting Started: guides/getting-started.md
    - Advanced: guides/advanced.md

# 语言特定导航
extra:
  nav_en:
    - Home: en/index.md
    - About: en/about.md
    - Guides:
      - Getting Started: en/guides/getting-started.md
  nav_zh-CN:
    - 首页: zh-CN/index.md
    - 关于: zh-CN/about.md
    - 指南:
      - 快速开始: zh-CN/guides/getting-started.md

语言检测¶

plugins:
  - i18n:
      # 根据浏览器语言自动重定向
      browser_redirect: true
      redirect_template: '{lang}/index.html'

      # 语言优先级
      language_priority:
        - en
        - zh-CN
        - ja

      # 未配置语言时的回退策略
      fallback_to_default: true

内容翻译¶

1. 页面级翻译¶

在页面顶部添加语言元数据：

---
title: Home
lang: en
translation:
  zh-CN: /zh-CN/index.html
  ja: /ja/index.html
---

# Welcome

2. 变量翻译¶

创建翻译文件：

# docs/i18n/en.yml
site:
  name: My Documentation
  description: Professional documentation
copyright: © 2024 My Docs

nav:
  home: Home
  about: About
  guides: Guides

buttons:
  read_more: Read More
  submit: Submit
  cancel: Cancel

messages:
  welcome: Welcome to our documentation!
  error: An error occurred

# docs/i18n/zh-CN.yml
site:
  name: 我的文档
  description: 专业文档
copyright: © 2024 我的文档

nav:
  home: 首页
  about: 关于
  guides: 指南

buttons:
  read_more: 了解更多
  submit: 提交
  cancel: 取消

messages:
  welcome: 欢迎使用我们的文档！
  error: 发生了一个错误

3. 在Markdown中使用翻译¶

<!-- 使用翻译 -->
# {{ i18n.site.name }}

{{ i18n.messages.welcome }}

<!-- 条件翻译 -->
{% if lang == 'en' %}
This is English content.
{% elif lang == 'zh-CN' %}
这是中文内容。
{% endif %}

<!-- 变量替换 -->
{{ i18n.buttons.read_more }}

4. 图片翻译¶

# docs/i18n/en.yml
images:
  logo: /assets/images/logo-en.png
  diagram: /assets/images/diagram-en.png

# docs/i18n/zh-CN.yml
images:
  logo: /assets/images/logo-zh.png
  diagram: /assets/images/diagram-zh.png

<!-- 使用翻译后的图片 -->
![Logo]({{ i18n.images.logo }})

![流程图]({{ i18n.images.diagram }})

SEO优化¶

多语言SEO配置¶

plugins:
  - i18n:
      # SEO优化
      seo_optimize: true
      alternate_links: true
      hreflang_tags: true

      # Sitemap配置
      sitemap: true
      sitemap_lang: true

      # Robots.txt配置
      robots_txt: true
      robots_lang: true

语言特定的SEO¶

extra:
  seo_en:
    locale: en_US
    type: website
    twitter: '@en_account'

  seo_zh-CN:
    locale: zh_CN
    type: website
    twitter: '@zh_account'

结构化数据¶

extra:
  structured_data:
    '@context': https://schema.org
    '@type': WebSite
    name: My Documentation
    url: https://example.com
    inLanguage: en
    alternateName:
      zh-CN: 我的文档
      ja: マイドキュメント

构建和部署¶

构建所有语言¶

# 构建所有语言版本
mkdocs build --all-langs

# 或构建特定语言
mkdocs build --lang en
mkdocs build --lang zh-CN

# 构建并部署
mkdocs gh-deploy --all-langs

GitHub Actions配置¶

name: Multi-language Deploy

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'

      - name: Install dependencies
        run: |
          pip install mkdocs mkdocs-material mkdocs-i18n

      - name: Build all languages
        run: mkdocs build --all-langs

      - name: Deploy to GitHub Pages
        run: mkdocs gh-deploy --force --all-langs

高级功能¶

1. 语言检测中间件¶

# docs/plugins/language_middleware.py
from mkdocs.plugins import BasePlugin

class LanguageMiddleware(BasePlugin):
    def on_pre_build(self, config, **kwargs):
        # 添加语言检测逻辑
        pass

    def on_post_page(self, output, page, config, **kwargs):
        # 修改页面内容
        return output

2. 自定义翻译API¶

# docs/plugins/custom_translator.py
import requests

class CustomTranslator:
    def __init__(self, api_key):
        self.api_key = api_key

    def translate(self, text, target_lang):
        # 实现自定义翻译逻辑
        response = requests.post(
            'https://api.example.com/translate',
            headers={'Authorization': f'Bearer {self.api_key}'},
            json={'text': text, 'target': target_lang}
        )
        return response.json()['translated_text']

3. 翻译缓存¶

plugins:
  - i18n:
      cache_translations: true
      cache_dir: .cache/translations
      cache_format: json  # 或 yaml, pickle
      cache_ttl: 86400   # 24小时
      cache_compress: true

测试和验证¶

验证翻译¶

# 检查翻译完整性
mkdocs i18n validate

# 列出未翻译的页面
mkdocs i18n list-untranslated

# 检查语言配置
mkdocs i18n check-config

测试多语言站点¶

# 启动多语言开发服务器
mkdocs serve --lang en
mkdocs serve --lang zh-CN

# 测试所有语言
mkdocs serve --all-langs

最佳实践¶

1. 翻译质量¶

plugins:
  - i18n:
      # 翻译质量检查
      quality_check: true
      min_translation_ratio: 0.8  # 至少80%翻译完成
      require_review: true        # 需要人工审核
      review_team:
        - translator1@example.com
        - translator2@example.com

2. 版本控制¶

# 忽略自动生成的翻译
echo "*.auto.*" >> .gitignore

# 只跟踪手动翻译
git add docs/zh-CN/*.md
git add docs/ja/*.md

# 使用Git LFS存储大文件
git lfs track "docs/assets/images/*"

3. 翻译工作流程¶

# .github/workflows/translate.yml
name: Translation Workflow

on:
  push:
    branches:
      - main

jobs:
  auto-translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Auto-translate new content
        run: mkdocs i18n auto-translate

      - name: Create translation PR
        uses: peter-evans/create-pull-request@v4
        with:
          title: "Auto-translate: New content"
          body: "Automatically translated new content"
          branch: auto-translate

下一步: 性能优化

多语言支持¶

基础配置¶

1. 安装依赖¶

2. 配置多语言¶

目录结构¶

推荐结构¶

替代结构¶

语言切换器¶

配置切换器¶

切换器位置¶

自定义切换器样式¶

翻译管理¶

1. 手动翻译¶

2. 自动翻译¶

3. 混合模式¶

导航配置¶

多语言导航¶

语言检测¶

内容翻译¶

1. 页面级翻译¶

2. 变量翻译¶

3. 在Markdown中使用翻译¶

4. 图片翻译¶

SEO优化¶

多语言SEO配置¶

语言特定的SEO¶

结构化数据¶

构建和部署¶

构建所有语言¶

GitHub Actions配置¶

高级功能¶

1. 语言检测中间件¶

2. 自定义翻译API¶

3. 翻译缓存¶

测试和验证¶

验证翻译¶

测试多语言站点¶

最佳实践¶

1. 翻译质量¶

2. 版本控制¶

3. 翻译工作流程¶