Skip to content

MkDocs多言語対応設定ガイド

MkDocsで多言語サイトを構築するための完全ガイドです。日本語と英語の2言語サイトの実装方法を詳しく解説します。

概要

MkDocsのi18nプラグインを使用することで、単一のプロジェクトから複数言語のサイトを生成できます。このガイドでは実際の設定例を基に、多言語対応の手順を説明します。

実現できること

  • 多言語サイト自動生成

    1つのプロジェクトから複数言語サイトを一括生成

  • ナビゲーション自動翻訳

    複雑な階層メニューも言語ごとに自動対応

  • :fontawesome-solid-exchange-alt:{ .lg .middle } シームレス言語切替

    ユーザーフレンドリーな言語選択メニュー

  • :fontawesome-solid-file-alt:{ .lg .middle } 段階的翻訳展開

    重要ページから順次翻訳で効率的な国際化

  • :fontawesome-solid-search:{ .lg .middle } 多言語検索対応

    日本語分かち書きなど言語特性に最適化

  • グローバルSEO自動化

    hreflang・サイトマップ等を自動生成

必要なプラグイン

mkdocs-static-i18nプラグインのインストール

pip install mkdocs-static-i18n

基本設定

mkdocs.ymlの設定

# 基本情報
site_name: note
site_url: https://aiedoc.github.io/note/
theme:
  name: 'material'
  language: 'ja'  # デフォルト言語

# プラグイン設定
plugins:
  - search
  - i18n:
      default_language: ja
      languages:
        - locale: ja
          name: 日本語
          build: true
          default: true
        - locale: en
          name: English
          build: true

言語切り替えメニューの設定

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

ナビゲーション翻訳

mkdocs.ymlでナビゲーション項目の翻訳を定義します：

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

詳細なナビゲーション翻訳例

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

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

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

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

コンテンツの多言語化

ファイル命名規則

  • 日本語（デフォルト）: filename.md
  • 英語版: filename.en.md

実装例

1. ホームページの多言語化

日本語版: docs/index.md

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

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

英語版: docs/index.en.md

# Technical Notes & Documentation

Technical documentation site using MkDocs Material.

2. 記事の多言語化

日本語版: docs/AI/claude-code-best-practices.md

# Claude Code実践ガイド

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

英語版: docs/AI/claude-code-best-practices.en.md

# Claude Code Best Practices

A guide to effectively using Claude Code.

ディレクトリ構造

note/
├── docs/
│   ├── index.md                    # 日本語ホーム
│   ├── index.en.md                 # 英語ホーム
│   ├── AI/
│   │   ├── claude-code-best-practices.md     # 日本語
│   │   └── claude-code-best-practices.en.md  # 英語
│   └── Tips/
│       └── MkDocs/
│           ├── 高度な設定.md       # 日本語
│           └── 高度な設定.en.md    # 英語
└── site/
    ├── index.html                  # 日本語サイト（ルート）
    └── en/
        └── index.html              # 英語サイト

高度な設定

検索機能の多言語対応

plugins:
  - search:
      lang: 
        - ja
        - en
  - i18n:
      # i18n設定...

Git修正日時プラグインの設定

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

ビルドとデプロイ

ローカルでのプレビュー

# 開発サーバー起動
mkdocs serve

# アクセス
# 日本語: http://127.0.0.1:8000/
# 英語: http://127.0.0.1:8000/en/

ビルド

# サイトをビルド
mkdocs build

# GitHub Pagesにデプロイ
mkdocs gh-deploy

生成されるファイル構造

site/
├── index.html                     # 日本語版（デフォルト）
├── AI/
│   └── claude-code-best-practices/
│       └── index.html             # 日本語記事
└── en/                            # 英語サイト
    ├── index.html                 # 英語ホーム
    └── AI/
        └── claude-code-best-practices/
            └── index.html         # 英語記事

トラブルシューティング

よくある警告と対処法

1. 設定警告

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

対処法: mkdocs-static-i18nのバージョンを確認し、最新版を使用してください。

2. Gitログ警告

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

対処法: 新しい.en.mdファイルをgitにコミットしてください。

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

3. 画像ファイルの警告

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

対処法: 画像ファイルを正しいパスに配置するか、リンクを修正してください。

Material Theme との互換性

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

対処法: navigation.instant機能を使用する場合は、言語切り替えが正常に動作することを確認してください。

ベストプラクティス

1. 段階的な多言語化

  • まず重要なページ（ホーム、主要ガイド）から英語化
  • ユーザーフィードバックを基に優先順位を決定
  • 定期的にコンテンツの同期を確認

2. 一貫性の維持

  • 翻訳規則を文書化
  • 用語集を作成・維持
  • レビュープロセスを確立

3. SEO対策

  • 各言語版に適切なメタデータを設定
  • hreflang属性の実装を検討
  • 言語固有のキーワード戦略

実装サンプル

カード機能を活用したコンテンツ表示

Material for MkDocsのカード機能を使って、言語学習リソースを整理した例：

  • 🇯🇵 日本語コンテンツ

    技術ドキュメントやガイドを日本語で提供。国内ユーザーのアクセシビリティを向上させます。

    日本語ページ一覧

  • 🇺🇸 English Content

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

    English Pages

  • 翻訳ガイドライン

    コンテンツの品質を保つための翻訳ガイドライン。用語集や表記統一のルールを定義します。

    ガイドライン詳細

機能別カテゴリ表示

  • 基本設定

    難易度: ⭐⭐☆
    所要時間: 30分
    対象: 初心者向け

    i18nプラグインの基本インストールと設定

  • ナビゲーション翻訳

    難易度: ⭐⭐⭐
    所要時間: 60分
    対象: 中級者向け

    複雑な階層構造のナビゲーション翻訳設定

  • 高度なカスタマイズ

    難易度: ⭐⭐⭐⭐
    所要時間: 120分
    対象: 上級者向け

    カスタムテーマと独自翻訳システムの構築

まとめ

MkDocsの多言語対応により、グローバルなドキュメントサイトを効率的に構築できます。段階的な実装により、メンテナンス負荷を抑えながら多言語サイトを運営することが可能です。

関連記事