docs: Update documentation for multi-language support and language sw…

…itcher

Add source repository, branch, and directory configurations. Implement a language switcher on the documentation website. Update the build process to generate POT files and update PO files for each language. Create a language selection page. Update GitHub Actions workflow to use a personal access token for deploying documentation.

Signed-off-by: longhao <hal.long@outlook.com>

.github/workflows/docs.yml

@@ -60,7 +60,7 @@ jobs:
         if: github.event_name == 'push' && github.ref == 'refs/heads/main'
         uses: peaceiris/actions-gh-pages@v4
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
+          github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
           publish_dir: ./docs/build/html
           destination_dir: ${{ github.ref_name }}  # Deploy to branch-specific directory
           keep_files: true  # Keep previously deployed files

docs/source/_templates/languages.html

@@ -0,0 +1,13 @@
+{% if language == 'en_US' %}
+    <div class="language-switcher">
+        <strong>Language:</strong>
+        <span>English</span> |
+        <a href="{{ pathto('../zh/' + pagename + '.html', 1) }}">中文</a>
+    </div>
+{% elif language == 'zh_CN' %}
+    <div class="language-switcher">
+        <strong>语言：</strong>
+        <a href="{{ pathto('../en/' + pagename + '.html', 1) }}">English</a> |
+        <span>中文</span>
+    </div>
+{% endif %}

docs/source/conf.py

@@ -66,6 +66,22 @@
             "class": "",
         },
     ],
+    "source_repository": "https://github.com/yourusername/persistent_ssh_agent",
+    "source_branch": "main",
+    "source_directory": "docs/",
+    "announcement": """
+        <div class="language-switcher">
+            {% if language == 'en_US' %}
+                <strong>Language:</strong>
+                <span class="current-lang">English</span> |
+                <a href="../zh_CN/{{ pagename }}.html">中文</a>
+            {% else %}
+                <strong>语言：</strong>
+                <a href="../en/{{ pagename }}.html">English</a> |
+                <span class="current-lang">中文</span>
+            {% endif %}
+        </div>
+    """,
 }
 
 # Configure templates
@@ -75,35 +91,37 @@
 language = os.getenv("SPHINX_LANGUAGE", "en")
 
 # Mapping of supported languages
-language_mapping = {
-    "en": "English",
-    "zh_CN": "简体中文"
-}
+languages = ["en", "zh_CN"]
 
 # Locale directories for translations
 locale_dirs = ["locale/"]
 gettext_compact = False
+gettext_uuid = True  # 添加 UUID 以便更好地追踪翻译
+gettext_location = True  # 添加位置信息以便更好地维护翻译
 
 # Language to use for generating the HTML full-text search index.
-# Sphinx supports the following languages:
-#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
-#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'ar', 'fa', 'hi',
-#   'ko', 'zh'
 html_search_language = {
     "en": "en",
     "zh_CN": "zh"
 }.get(language, "en")
 
+# 语言切换配置
+language_links = {
+    "en": {
+        "zh_CN": "../zh_CN/",
+    },
+    "zh_CN": {
+        "en": "../en/",
+    }
+}
+
 html_context = {
+    "language": language,
+    "language_links": language_links.get(language, {}),
     "languages": {
         "en": "English",
         "zh_CN": "简体中文",
     },
-    "current_language": language,
-    "language_links": {
-        "en": "/persistent_ssh_agent/en/",
-        "zh_CN": "/persistent_ssh_agent/zh_CN/",
-    }
 }
 
 # Configure master document

nox_actions/docs.py

@@ -337,6 +337,16 @@ def docs_i18n(session: Session) -> None:
 def docs_build(session: Session) -> None:
     """Build documentation for all languages.
 
+    The output structure will be:
+    build/html/
+    ├── en/         # English documentation
+    │   ├── index.html
+    │   └── ...
+    ├── zh_CN/      # Chinese documentation
+    │   ├── index.html
+    │   └── ...
+    └── index.html  # Language selection page
+
     Args:
         session: Nox session object
     """
@@ -346,19 +356,59 @@ def docs_build(session: Session) -> None:
     # Clean build directory first
     clean_docs(session)
 
-    # Build for each language
-    for lang in languages:
-        session.log(f"Building documentation for {lang}")
-        env = {"SPHINX_LANGUAGE": lang}
-        output_dir = f"build/html/{lang}"
-        with session.chdir(str(get_docs_dir())):
+    # First generate POT files
+    with session.chdir(str(get_docs_dir())):
+        session.run(
+            "sphinx-build",
+            "-b", "gettext",
+            "source",
+            "build/gettext"
+        )
+
+        # Update PO files for each language
+        session.run("sphinx-intl", "update", "-p", "build/gettext", "-l", "zh_CN")
+
+        # Build documentation for each language
+        for lang in ["en", "zh_CN"]:
+            session.log(f"Building documentation for {lang}")
+            output_dir = f"build/html/{lang}"
             session.run(
                 "sphinx-build",
                 "-b", "html",
                 "-D", f"language={lang}",
                 "source",
-                output_dir,
-                env=env
+                output_dir
             )
 
+    # Create a simple language selection page
+    index_html = """
+    <!DOCTYPE html>
+    <html>
+    <head>
+        <meta charset="UTF-8">
+        <meta http-equiv="refresh" content="0; url=en/">
+        <script>
+            var lang = navigator.language || navigator.userLanguage;
+            if (lang.toLowerCase().startsWith('zh')) {
+                window.location.href = 'zh_CN/';
+            } else {
+                window.location.href = 'en/';
+            }
+        </script>
+        <title>Redirecting...</title>
+    </head>
+    <body>
+        <h1>Redirecting...</h1>
+        <p>
+            <a href="en/">English</a><br>
+            <a href="zh_CN/">中文</a>
+        </p>
+    </body>
+    </html>
+    """
+
+    # Write the language selection page
+    index_path = Path(get_docs_dir()) / "build" / "html" / "index.html"
+    index_path.write_text(index_html, encoding="utf-8")
+
     session.log("Documentation built successfully for all languages")