Once you’re comfortable creating a single-language documentation site with ReadtheDocs, expanding it to support multiple languages is a relatively straightforward process. Essentially, you’ll need to create separate builds for each language and then link them together. The following links are the examples:
Before we move forward, you’d better read the guidelines of how to build a single-language document:
Step 1: Organize Directories for Each Language
1.1 Create Root and Language-Specific Folders
First, create a root directory for the entire project. Then, create separate subdirectories for each language. For instance, if you’re building documentation in English and Chinese, your folder structure might look like this:
- Project Name
- docs/
- en/
- zh_CN/
1.2 Set Up a Virtual Environment
In this example, we’ll create a virtual environment called venv_100things. For a guide on setting up a virtual environment in VS Code, read this article:
1.3 Initialize the English Version
Navigate to the English directory and initialize the Sphinx project:
cd docs/en
sphinx-quickstart
When prompted, set the project language to “en”:
1.4 Initialize the Chinese Version
Return to the root directory and navigate to the Chinese directory:
cd ../..
cd docs/zh_CN
sphinx-quickstart
When prompted, set the project language to “cn”. Then, build documents separately.
Step 2: Configure Settings
2.1 Create .readthedocs.yaml File
# Required
version: 2
# Set the OS, Python version and other tools you might need
build:
os: ubuntu-22.04
tools:
python: "3.9"
# You can also specify other tool versions:
# nodejs: "20"
# rust: "1.70"
# golang: "1.20"
# Build documentation in the "docs/" directory with Sphinx
sphinx:
configuration: docs/en/source/conf.py
builder: html
# Removed the output key since it's not valid
# You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
# builder: "dirhtml"
# Fail on all warnings to avoid broken references
# fail_on_warning: true
# Optionally build your docs in additional formats such as PDF and ePub
# formats:
# - pdf
# - epub
# Optional but recommended, declare the Python requirements required
# to build your documentation
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
python:
install:
- requirements: requirements.txtDuplicate this file and place it in the root directories of both the en and zh_CN folders.
2.2 Create conf.py File
Create a conf.py file for Sphinx with the following content:
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
import os
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = '100things'
copyright = '2023, Henry Wu'
author = 'Henry Wu'
release = '2.4'
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = [
'sphinx.ext.autosectionlabel'
]
templates_path = ['_templates']
exclude_patterns = []
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
html_build_dir = os.environ.get('READTHEDOCS_OUTPUT', 'docs/en/build/html')Place this file in the source directory of the en folder. Duplicate it, modify the last line as shown, and place it in the zh_CN folder.
The final file structure is as follows:
Step 3: Upload to GitHub
If you haven’t yet created a GitHub repository, you can easily do so using the GitHub Desktop App.
3.1 Click the “Add” button and select “Add Existing Repository.”
3.2 Navigate to and choose the directory where your project resides.
3.3 Once you’ve added your repository, click “Commit to main” to upload your files to GitHub.
Step 4: Build the English Version
4.1 Log in the readthedocs.org
4.2 Click the “Import a Project” button:
4.3 Click the “+” button after the name of the repository:
4.4 Go to the “Admin” setting
4.5 Make sure the URL and language settings are correct
4.6 Go to the “Advanced Setting”
4.7 Make sure the setting is correct. The most crucial settings here are:
- Default version
- Default branch
- Path for
.readthedocs.yaml - Python configuration file
4.8 Build version
Go to the tab “Overview” and click the “Build version” button.
4.9 View Docs
After building the version, click the “View Docs” button to check the online document.
Step 5: Build the Chinese version
Follow the same steps as for the English version, with a few differences:
5.1 Import Manually: Since the GitHub repository link is already used for the English version, click “Import Manually” and input the same link.
5.2 Admin and Advanced Settings: Make sure to set the language to Chinese and update the .readthedocs.yaml and Python configuration file paths accordingly. The most crucial settings here are:
- Default version
- Default branch
- Path for
.readthedocs.yaml - Python configuration file
5.3 Build and View: Just like with the English version, build the documentation and view it to ensure everything looks as expected.
After building the version, click the “View Docs” button to check the online document.
Step 6: Combine Both Versions
Navigate to the “Admin” page of the English version on Read the Docs.
Switch to the “Translation” tab.
Select “zh_CN” from the “Project” dropdown and then click the “Add” button to link the Chinese documentation as a translation.
Everything is set up. Now, you have a multiple-language version of an online document.
