fix: Use mkdocs-static-i18n plugin for proper bilingual site

lixin0304 · lixin0304 · commit 361d0ee331d5 · 2026-03-11T14:15:43.000+08:00
- Rename all _zh.md to .zh.md (required by i18n plugin suffix mode)
- Add mkdocs-static-i18n plugin with Chinese nav configuration
- Remove separate mkdocs.zh.yml (no longer needed)
- Simplify deploy workflow back to single mkdocs gh-deploy
- Fix internal links in Chinese docs to use new .zh.md naming
- Remove navigation.instant (incompatible with language switcher)
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
@@ -36,13 +36,5 @@ jobs:
       - name: Install dependencies
         run: pip install -r docs-requirements.txt
 
-      - name: Build English site
-        run: mkdocs build --site-dir site
-
-      - name: Build Chinese site
-        run: mkdocs build --config-file mkdocs.zh.yml
-
       - name: Deploy to GitHub Pages
-        run: |
-          pip install ghp-import
-          ghp-import site -p -f -r origin -b gh-pages
+        run: mkdocs gh-deploy --force
diff --git a/doc/advanced/chinese-data.zh.md b/doc/advanced/chinese-data.zh.md
@@ -1,6 +1,6 @@
 # 中文数据处理
 
-**[English](chinese-data.md)** | **[中文](chinese-data_zh.md)**
+**[English](chinese-data.md)** | **[中文](chinese-data.zh.md)**
 
 ---
 
diff --git a/doc/advanced/custom-datasets.zh.md b/doc/advanced/custom-datasets.zh.md
@@ -1,6 +1,6 @@
 # 使用自定义数据集
 
-**[English](custom-datasets.md)** | **[中文](custom-datasets_zh.md)**
+**[English](custom-datasets.md)** | **[中文](custom-datasets.zh.md)**
 
 ---
 
diff --git a/doc/advanced/distributed-training.zh.md b/doc/advanced/distributed-training.zh.md
@@ -1,6 +1,6 @@
 # 分布式与内存高效训练
 
-**[English](distributed-training.md)** | **[中文](distributed-training_zh.md)**
+**[English](distributed-training.md)** | **[中文](distributed-training.zh.md)**
 
 ---
 
diff --git a/doc/advanced/hyperparameters.zh.md b/doc/advanced/hyperparameters.zh.md
@@ -1,6 +1,6 @@
 # 超参数调优
 
-**[English](hyperparameters.md)** | **[中文](hyperparameters_zh.md)**
+**[English](hyperparameters.md)** | **[中文](hyperparameters.zh.md)**
 
 ---
 
diff --git a/doc/api/prepare-data.zh.md b/doc/api/prepare-data.zh.md
@@ -1,6 +1,6 @@
 # prepare_data.py
 
-**[English](prepare-data.md)** | **[中文](prepare-data_zh.md)**
+**[English](prepare-data.md)** | **[中文](prepare-data.zh.md)**
 
 ---
 
diff --git a/doc/api/run-pipeline.zh.md b/doc/api/run-pipeline.zh.md
@@ -1,6 +1,6 @@
 # run_pipeline.py
 
-**[English](run-pipeline.md)** | **[中文](run-pipeline_zh.md)**
+**[English](run-pipeline.md)** | **[中文](run-pipeline.zh.md)**
 
 ---
 
diff --git a/doc/api/visualization.zh.md b/doc/api/visualization.zh.md
@@ -1,6 +1,6 @@
 # visualization.run_visualization
 
-**[English](visualization.md)** | **[中文](visualization_zh.md)**
+**[English](visualization.md)** | **[中文](visualization.zh.md)**
 
 ---
 
diff --git a/doc/appendix/faq.zh.md b/doc/appendix/faq.zh.md
@@ -1,6 +1,6 @@
 # 附录
 
-**[English](faq.md)** | **[中文](faq_zh.md)**
+**[English](faq.md)** | **[中文](faq.zh.md)**
 
 ---
 
diff --git a/doc/examples/chinese-dataset.zh.md b/doc/examples/chinese-dataset.zh.md
@@ -1,6 +1,6 @@
 # 中文数据集示例
 
-**[English](chinese-dataset.md)** | **[中文](chinese-dataset_zh.md)**
+**[English](chinese-dataset.md)** | **[中文](chinese-dataset.zh.md)**
 
 ---
 
diff --git a/doc/examples/english-dataset.zh.md b/doc/examples/english-dataset.zh.md
@@ -1,6 +1,6 @@
 # 英文数据集示例
 
-**[English](english-dataset.md)** | **[中文](english-dataset_zh.md)**
+**[English](english-dataset.md)** | **[中文](english-dataset.zh.md)**
 
 ---
 
diff --git a/doc/examples/supervised-learning.zh.md b/doc/examples/supervised-learning.zh.md
@@ -1,6 +1,6 @@
 # 有监督学习示例
 
-**[English](supervised-learning.md)** | **[中文](supervised-learning_zh.md)**
+**[English](supervised-learning.md)** | **[中文](supervised-learning.zh.md)**
 
 ---
 
diff --git a/doc/getting-started/installation.zh.md b/doc/getting-started/installation.zh.md
diff --git a/doc/getting-started/overview.zh.md b/doc/getting-started/overview.zh.md
diff --git a/doc/getting-started/quickstart.zh.md b/doc/getting-started/quickstart.zh.md
diff --git a/doc/index.zh.md b/doc/index.zh.md
diff --git a/doc/models/baselines.zh.md b/doc/models/baselines.zh.md
@@ -1,6 +1,6 @@
 # 基线模型
 
-**[English](baselines.md)** | **[中文](baselines_zh.md)**
+**[English](baselines.md)** | **[中文](baselines.zh.md)**
 
 ---
 
diff --git a/doc/models/comparison.zh.md b/doc/models/comparison.zh.md
@@ -1,6 +1,6 @@
 # 模型比较
 
-**[English](comparison.md)** | **[中文](comparison_zh.md)**
+**[English](comparison.md)** | **[中文](comparison.zh.md)**
 
 ---
 
diff --git a/doc/models/theta.zh.md b/doc/models/theta.zh.md
@@ -1,6 +1,6 @@
 # THETA模型
 
-**[English](theta.md)** | **[中文](theta_zh.md)**
+**[English](theta.md)** | **[中文](theta.zh.md)**
 
 ---
 
diff --git a/doc/troubleshooting.zh.md b/doc/troubleshooting.zh.md
diff --git a/doc/user-guide/data-preparation.zh.md b/doc/user-guide/data-preparation.zh.md
@@ -1,6 +1,6 @@
 # 数据准备
 
-**[English](data-preparation.md)** | **[中文](data-preparation_zh.md)**
+**[English](data-preparation.md)** | **[中文](data-preparation.zh.md)**
 
 ---
 
diff --git a/doc/user-guide/evaluation.zh.md b/doc/user-guide/evaluation.zh.md
@@ -1,6 +1,6 @@
 # 评估
 
-**[English](evaluation.md)** | **[中文](evaluation_zh.md)**
+**[English](evaluation.md)** | **[中文](evaluation.zh.md)**
 
 ---
 
diff --git a/doc/user-guide/preprocessing.zh.md b/doc/user-guide/preprocessing.zh.md
@@ -1,6 +1,6 @@
 # 数据预处理
 
-**[English](preprocessing.md)** | **[中文](preprocessing_zh.md)**
+**[English](preprocessing.md)** | **[中文](preprocessing.zh.md)**
 
 ---
 
diff --git a/doc/user-guide/training.zh.md b/doc/user-guide/training.zh.md
@@ -1,6 +1,6 @@
 # 训练模型
 
-**[English](training.md)** | **[中文](training_zh.md)**
+**[English](training.md)** | **[中文](training.zh.md)**
 
 ---
 
diff --git a/doc/user-guide/visualization.zh.md b/doc/user-guide/visualization.zh.md
@@ -1,6 +1,6 @@
 # 可视化
 
-**[English](visualization.md)** | **[中文](visualization_zh.md)**
+**[English](visualization.md)** | **[中文](visualization.zh.md)**
 
 ---
 
diff --git a/docs-requirements.txt b/docs-requirements.txt
@@ -1,2 +1,3 @@
 mkdocs>=1.5
 mkdocs-material>=9.5
+mkdocs-static-i18n>=1.2
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -34,7 +34,6 @@ theme:
         name: Switch to light mode
 
   features:
-    - navigation.instant
     - navigation.tracking
     - navigation.tabs
     - navigation.tabs.sticky
@@ -59,6 +58,47 @@ plugins:
       lang:
         - en
         - zh
+  - i18n:
+      docs_structure: suffix
+      languages:
+        - locale: en
+          default: true
+          name: English
+          build: true
+        - locale: zh
+          name: 中文
+          build: true
+          nav:
+            - 首页: index.md
+            - 快速入门:
+                - 项目概述: getting-started/overview.md
+                - 安装: getting-started/installation.md
+                - 快速开始: getting-started/quickstart.md
+            - 用户指南:
+                - 数据准备: user-guide/data-preparation.md
+                - 数据预处理: user-guide/preprocessing.md
+                - 训练模型: user-guide/training.md
+                - 评估: user-guide/evaluation.md
+                - 可视化: user-guide/visualization.md
+            - 模型:
+                - THETA模型: models/theta.md
+                - 基线模型: models/baselines.md
+                - 模型比较: models/comparison.md
+            - 高级:
+                - 自定义数据集: advanced/custom-datasets.md
+                - 超参数调优: advanced/hyperparameters.md
+                - 中文数据处理: advanced/chinese-data.md
+                - 分布式训练: advanced/distributed-training.md
+            - API参考:
+                - prepare_data.py: api/prepare-data.md
+                - run_pipeline.py: api/run-pipeline.md
+                - 可视化: api/visualization.md
+            - 示例:
+                - 英文数据集: examples/english-dataset.md
+                - 中文数据集: examples/chinese-dataset.md
+                - 有监督学习: examples/supervised-learning.md
+            - 故障排除: troubleshooting.md
+            - 附录: appendix/faq.md
 
 # Markdown Extensions
 markdown_extensions:
@@ -125,13 +165,6 @@ nav:
 
 # Extra
 extra:
-  alternate:
-    - name: English
-      link: /THETA/
-      lang: en
-    - name: 中文
-      link: /THETA/zh/
-      lang: zh
   social:
     - icon: fontawesome/brands/github
       link: https://github.com/CodeSoul-co/THETA
diff --git a/mkdocs.zh.yml b/mkdocs.zh.yml
