sphinxを用いた作成されたドキュメントサイトに日本語訳を追加する

概要

sphinxを用いた作成されたドキュメントサイトに日本語訳を追加することがあり、その備忘録です。

以下を対象にします。

https://github.com/artefactual/archivematica-storage-service-docs

方法

まず、対象リポジトリをForkします。

次に、Cloneします。

git clone https://github.com/nakamura196/archivematica-storage-service-docs
cd atom-docs

ここでは、Pythonの仮想環境を作成しておきます。

python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

ライブラリの追加

requirements.txtにsphinx-intlを追加して、インストールします。

requirements.txt

sphinx
sphinx-intl
sphinx-autobuild

pip install -r requirements.txt

（オプション） conf.py

conf.pyに言語設定が存在しない場合には、以下のように追加します。

conf.py

...
# 言語設定
locale_dirs = ['locale/']  # 翻訳ファイルを格納するディレクトリ
gettext_compact = False  # ファイル名を短くしない
language = "ja"

そして、gettextビルドを実行します。

make gettext

日本語ディクレトリの作成

以下を実行すると、locale/jaにpoファイルが作成されます。

sphinx-intl update -p _build/locale -l ja

編集

locale/ja以下のpoファイルを編集することで、多言語化を行います。

開発

以下のコマンドにより、サイトをプレビューできます。

sphinx-autobuild . _build/html

ビルド

以下のコマンドにより、ビルド結果が_build/htmlに格納されます。

sphinx-build . _build/html

デプロイ

/.github/workflows/deploy.yml

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

      # buildディレクトリのアーティファクトとして保存
      - 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

結果、以下のようにデプロイされます。

https://nakamura196.github.io/archivematica-storage-service-docs/

まとめ

参考になりましたら幸いです。