Configure docs as three Read the Docs translation projects

.readthedocs.yaml

@@ -1,6 +1,11 @@
 # .readthedocs.yaml
-# Read the Docs configuration file
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+# Read the Docs configuration file for the English ("fileautomation") project.
+# Sibling files .readthedocs.zh-TW.yaml and .readthedocs.zh-CN.yaml configure
+# the two translation projects. Wire each translation project to its own YAML
+# in the RTD project admin (Settings → Default settings → Path), and link the
+# three projects via the main project's Translations tab.
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html
+#     https://docs.readthedocs.io/en/stable/localization.html
 
 # Required
 version: 2
@@ -11,7 +16,7 @@ build:
   tools:
     python: "3.11"
 
-# Build documentation in the "docs/" directory with Sphinx
+# Build the English documentation in docs/source with Sphinx.
 sphinx:
    configuration: docs/source/conf.py
 

.readthedocs.zh-CN.yaml

@@ -0,0 +1,22 @@
+# .readthedocs.zh-CN.yaml
+# Read the Docs configuration file for the Simplified Chinese
+# ("fileautomation-zh-cn") translation project. Linked from the main
+# "fileautomation" project's Translations tab so RTD serves it at
+# https://fileautomation.readthedocs.io/zh_CN/<version>/.
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html
+#     https://docs.readthedocs.io/en/stable/localization.html
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build the Simplified Chinese documentation in docs/source.zh-CN with Sphinx.
+sphinx:
+   configuration: docs/source.zh-CN/conf.py
+
+python:
+  install:
+  - requirements: docs/requirements.txt

.readthedocs.zh-TW.yaml

@@ -0,0 +1,22 @@
+# .readthedocs.zh-TW.yaml
+# Read the Docs configuration file for the Traditional Chinese
+# ("fileautomation-zh-tw") translation project. Linked from the main
+# "fileautomation" project's Translations tab so RTD serves it at
+# https://fileautomation.readthedocs.io/zh_TW/<version>/.
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html
+#     https://docs.readthedocs.io/en/stable/localization.html
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build the Traditional Chinese documentation in docs/source.zh-TW with Sphinx.
+sphinx:
+   configuration: docs/source.zh-TW/conf.py
+
+python:
+  install:
+  - requirements: docs/requirements.txt

docs/source.zh-CN/conf.py

@@ -16,6 +16,12 @@
 language = "zh_CN"
 html_title = "automation_file 文档（简体中文）"
 
+# Read the Docs sets READTHEDOCS_CANONICAL_URL to the per-translation canonical
+# URL (e.g. https://fileautomation.readthedocs.io/zh_CN/latest/). Use it as the
+# base URL so canonical <link rel="canonical"> tags and the translations flyout
+# resolve correctly. Empty string off-RTD.
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
+
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",

docs/source.zh-CN/index.rst

@@ -17,7 +17,13 @@ Dropbox、OneDrive、Box、SFTP、FTP / FTPS、WebDAV、SMB、fsspec）、
 * **Issue / 未来规划**：https://github.com/Integration-Automation/FileAutomation/issues
 * **许可**：MIT
 
-语言：`English <../html/index.html>`_ | `繁體中文 <../html-zh-TW/index.html>`_ | **简体中文**
+语言：`English <https://fileautomation.readthedocs.io/en/latest/>`_ | `繁體中文 <https://fileautomation.readthedocs.io/zh_TW/latest/>`_ | **简体中文**
+
+.. note::
+
+   每个语言都是独立的 Read the Docs 项目，并挂在主项目
+   ``fileautomation`` 下作为翻译。RTD 也会在每页右下角的版本菜单中
+   自动提供语言切换器。
 
 .. contents:: 本页目录
    :local:

docs/source.zh-TW/conf.py

@@ -16,6 +16,12 @@
 language = "zh_TW"
 html_title = "automation_file 文件（繁體中文）"
 
+# Read the Docs sets READTHEDOCS_CANONICAL_URL to the per-translation canonical
+# URL (e.g. https://fileautomation.readthedocs.io/zh_TW/latest/). Use it as the
+# base URL so canonical <link rel="canonical"> tags and the translations flyout
+# resolve correctly. Empty string off-RTD.
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
+
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",

docs/source.zh-TW/index.rst

@@ -17,7 +17,13 @@ Dropbox、OneDrive、Box、SFTP、FTP / FTPS、WebDAV、SMB、fsspec）、
 * **Issue / 未來規劃**：https://github.com/Integration-Automation/FileAutomation/issues
 * **授權**：MIT
 
-語言：`English <../html/index.html>`_ | **繁體中文** | `简体中文 <../html-zh-CN/index.html>`_
+語言：`English <https://fileautomation.readthedocs.io/en/latest/>`_ | **繁體中文** | `简体中文 <https://fileautomation.readthedocs.io/zh_CN/latest/>`_
+
+.. note::
+
+   每個語言都是獨立的 Read the Docs 專案，並掛在主專案
+   ``fileautomation`` 下作為翻譯。RTD 也會在每頁右下角的版本選單中
+   自動提供語言切換器。
 
 .. contents:: 本頁目錄
    :local:

docs/source/conf.py

@@ -13,6 +13,13 @@
 author = "JE-Chen"
 copyright = "2026, JE-Chen"  # pylint: disable=redefined-builtin  # Sphinx requires this name
 release = "0.0.32"
+language = "en"
+
+# Read the Docs sets READTHEDOCS_CANONICAL_URL to the per-translation canonical
+# URL (e.g. https://fileautomation.readthedocs.io/en/latest/). Use it as the
+# base URL so canonical <link rel="canonical"> tags and the translations flyout
+# resolve correctly. Empty string off-RTD.
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
 
 extensions = [
     "sphinx.ext.autodoc",

docs/source/index.rst

@@ -18,7 +18,13 @@ and exposed from a single ``automation_file`` facade.
 * **Issues / RoadMap** — https://github.com/Integration-Automation/FileAutomation/issues
 * **License** — MIT
 
-Languages: **English** | `繁體中文 <../html-zh-TW/index.html>`_ | `简体中文 <../html-zh-CN/index.html>`_
+Languages: **English** | `繁體中文 <https://fileautomation.readthedocs.io/zh_TW/latest/>`_ | `简体中文 <https://fileautomation.readthedocs.io/zh_CN/latest/>`_
+
+.. note::
+
+   Each language is served as its own Read the Docs project, linked as a
+   translation of ``fileautomation``. RTD also exposes a built-in language
+   selector inside the version flyout in the bottom-right of every page.
 
 .. contents:: On this page
    :local: