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.