MkDocs Multilingual Setup Guide

A complete guide to building multilingual sites with MkDocs. This article explains in detail how to implement a bilingual site in Japanese and English.

Overview

By using the MkDocs i18n plugin, you can generate sites in multiple languages from a single project. This guide explains the multilingual setup process based on actual configuration examples.

Key Points

• Automatic Multilingual Site Generation

  ---

  Batch generate multilingual sites from a single project

• Automatic Navigation Translation

  ---

  Automatically handle complex hierarchical menus for each language

• Seamless Language Switching

  ---

  User-friendly language selection menu

• Gradual Translation Rollout

  ---

  Efficient internationalization by translating important pages first

• Multilingual Search Support

  ---

  Optimized for language characteristics like Japanese word segmentation

• Global SEO Automation

  ---

  Automatically generate hreflang, sitemaps, etc.

Required Plugins

Installing the mkdocs-static-i18n Plugin

pip install mkdocs-static-i18n

Basic Configuration

Configuring mkdocs.yml

# Basic information
site_name: note
site_url: https://smartscope.github.io/note/
theme:
  name: 'material'
  language: 'ja'  # Default language

# Plugin configuration
plugins:
  - search
  - i18n:
      default_language: ja
      languages:
        - locale: ja
          name: 日本語
          build: true
          default: true
        - locale: en
          name: English
          build: true

Configuring the Language Switcher Menu

extra:
  alternate:
    - name: 日本語
      link: /
      lang: ja
    - name: English
      link: /en/
      lang: en

Navigation Translation

Configuring nav_translations

Define navigation item translations in mkdocs.yml:

plugins:
  - i18n:
      nav_translations:
        en:
          ホーム: Home
          学習・情報: Learning & Information
          インフラ・運用: Infrastructure & Operations
          AI開発: AI Development
          プログラミング: Programming
          ツール・Tips: Tools & Tips
          SEO実践ガイド: SEO Practical Guide

Detailed Navigation Translation Example

nav_translations:
  en:
    # Main sections
    ホーム: Home
    学習・情報: Learning & Information
    インフラ・運用: Infrastructure & Operations
    AI開発: AI Development
    プログラミング: Programming
    ツール・Tips: Tools & Tips
    SEO実践ガイド: SEO Practical Guide

    # Subsections
    システム基礎: System Basics
    自動化・スケジューリング: Automation & Scheduling
    ディスク・ストレージ: Disk & Storage
    パッケージ管理: Package Management
    コマンド・ツール: Commands & Tools

    # AI-related
    基本知識・トレンド: Basics & Trends
    実践ガイド: Practical Guide
    Claude Code活用法: Claude Code Best Practices
    LLMプログラミング: LLM Programming

    # Tips-related
    サイト構築・運用: Site Building & Operations
    開発効率化: Development Efficiency
    参考資料: References

Multilingual Content

File Naming Conventions

• Japanese (default): filename.md
• English version: filename.en.md

Automatic Generation of English Stubs

• Running the English stub generation script automatically generates .en.md stubs for Japanese articles that don't have an English version yet.
• Using the --dry-run option lets you preview the files that would be generated without actually writing them.
• The generated stubs include a translation-pending note and the original content, allowing you to pass mkdocs build --strict and the JP/EN article pair validation even before translation.
• When integrating into CI or local pre-build processing, run this script before pair checks or builds.

Implementation Examples

1. Multilingual Homepage

Japanese version: docs/index.md

# 技術ノート・ドキュメント集

MkDocs Materialを使用した技術ドキュメントサイトです。

English version: docs/index.en.md

# Technical Notes & Documentation

Technical documentation site using MkDocs Material.

2. Multilingual Articles

Japanese version: docs/AI/claude-code-best-practices.md

# Claude Code実践ガイド

Claude Codeの効果的な使用方法を解説します。

English version: docs/AI/claude-code-best-practices.en.md

# Claude Code Best Practices

A guide to effectively using Claude Code.

Directory Structure

note/
├── docs/
│   ├── index.md                    # Japanese home
│   ├── index.en.md                 # English home
│   ├── AI/
│   │   ├── claude-code-best-practices.md     # Japanese
│   │   └── claude-code-best-practices.en.md  # English
│   └── Tips/
│       └── MkDocs/
│           ├── 高度な設定.md       # Japanese
│           └── 高度な設定.en.md    # English
└── site/
    ├── index.html                  # Japanese site (root)
    └── en/
        └── index.html              # English site

Advanced Configuration

Multilingual Search Functionality

plugins:
  - search:
      lang: 
        - ja
        - en
  - i18n:
      # i18n configuration...

Git Revision Date Plugin Configuration

plugins:
  - git-revision-date-localized:
      type: datetime
      timezone: Asia/Tokyo
      locale: ja
      fallback_to_build_date: true

Build and Deploy

Local Preview

# Start development server
mkdocs serve

# Access
# Japanese: http://127.0.0.1:8000/
# English: http://127.0.0.1:8000/en/

Build

# Build the site
mkdocs build

# Deploy to GitHub Pages
mkdocs gh-deploy

Generated File Structure

site/
├── index.html                     # Japanese version (default)
├── AI/
│   └── claude-code-best-practices/
│       └── index.html             # Japanese article
└── en/                            # English site
    ├── index.html                 # English home
    └── AI/
        └── claude-code-best-practices/
            └── index.html         # English article

Troubleshooting

Common Warnings and Solutions

1. Configuration Warnings

WARNING - Config value 'plugins': Plugin 'i18n' option 'nav_translations': 
Unrecognised configuration name: nav_translations

Solution: Check the version of mkdocs-static-i18n and use the latest version.

2. Git Log Warnings

WARNING - [git-revision-date-localized-plugin] 'file.en.md' has no git logs

Solution: Commit the new .en.md files to git.

git add docs/**/*.en.md
git commit -m "Add English translations"

3. Image File Warnings

WARNING - Doc file contains a link './images/file.png', 
but the target is not found

Solution: Place the image file in the correct path or fix the link.

Material Theme Compatibility

WARNING - mkdocs-material language switcher contextual link is not compatible 
with theme.features = navigation.instant

Solution: If using the navigation.instant feature, verify that language switching works correctly.

Best Practices

1. Gradual Multilingualization

• Start with English versions of important pages (home, main guides)
• Determine priorities based on user feedback
• Regularly check content synchronization

2. Maintaining Consistency

• Document translation rules
• Create and maintain a glossary
• Establish a review process

3. SEO Measures

• Set appropriate metadata for each language version
• Consider implementing hreflang attributes
• Develop language-specific keyword strategies

Implementation Samples

Content Display Using Card Features

An example of organizing language learning resources using Material for MkDocs card features:

• Japanese Content

  ---

  Technical documentation and guides provided in Japanese. Improves accessibility for domestic users.

  Japanese Page List

• English Content

  ---

  Technical documentation and guides provided in English. Improves accessibility for international users.

  English Pages

• Translation Guidelines

  ---

  Translation guidelines to maintain content quality. Defines glossary and notation unification rules.

  Guideline Details

Feature-based Category Display

• Basic Configuration

  ---

  Difficulty: ⭐⭐☆
  Time Required: 30 minutes
  Target: Beginners

  Basic installation and configuration of the i18n plugin

• Navigation Translation

  ---

  Difficulty: ⭐⭐⭐
  Time Required: 60 minutes
  Target: Intermediate users

  Navigation translation configuration for complex hierarchical structures

• Advanced Customization

  ---

  Difficulty: ⭐⭐⭐⭐
  Time Required: 120 minutes
  Target: Advanced users

  Building custom themes and proprietary translation systems

Summary

With MkDocs multilingual support, you can efficiently build global documentation sites. Gradual implementation allows you to operate multilingual sites while keeping maintenance overhead low.

Related Articles

• MkDocs Notes
• How to Create GitHub Pages
• Advanced Configuration
• Design Improvement Guide