Overview
I had the opportunity to add Japanese translation to a documentation site built with sphinx, so this is a note for reference.
The target is the following.
https://github.com/artefactual/archivematica-storage-service-docs
Method
First, fork the target repository.

Next, clone it.
git clone https://github.com/nakamura196/archivematica-storage-service-docs
cd atom-docs
Here, we create a Python virtual environment.
python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
Adding Libraries
Add sphinx-intl to requirements.txt and install it.
sphinx
sphinx-intl
sphinx-autobuild
pip install -r requirements.txt
(Optional) conf.py
If language settings do not exist in conf.py, add them as follows.
...
# Language settings
locale_dirs = ['locale/'] # Directory to store translation files
gettext_compact = False # Do not shorten file names
language = "ja"
Then run the gettext build.
make gettext
Creating the Japanese Directory
Running the following creates po files in locale/ja.
sphinx-intl update -p _build/locale -l ja
Editing
Localization is done by editing the po files under locale/ja.
Development
The following command allows you to preview the site.
sphinx-autobuild . _build/html
Build
The following command stores the build results in _build/html.
sphinx-build . _build/html
Deployment
name: Deploy Sphinx Documentation to GitHub Pages
on:
push:
branches:
- "1.15"
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.10" # Specify the Python version
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install -r requirements.txt # if you have any dependencies
- name: Build Sphinx Documentation
run: |
sphinx-build . _build/html # Adjust paths if necessary
env:
TZ: UTC
# Save build directory as artifact
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: _build/html
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
As a result, it is deployed as follows.
https://nakamura196.github.io/archivematica-storage-service-docs/
Summary
I hope this is helpful.