name: Update Chinese Documentation Translations

on:
  schedule:
    - cron: "0 9 * * 1"
  workflow_dispatch:
    inputs:
      max_entries:
        description: "Maximum entries to translate in this run"
        required: false
        default: "50"

concurrency:
    group: update-chinese-docs
    cancel-in-progress: false

permissions:
  contents: write
  pull-requests: write

jobs:
  translate-docs:
    name: Update Chinese docs translations
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
        with:
          egress-policy: audit

      - name: Checkout code
        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
        with:
          ref: dev

      - name: Setup Python 3.13
        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
        with:
          python-version: "3.13"

      - name: Install Dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements/docs.txt

      - name: Reuse translations from open PR
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          # Reuse the automation branch only while its PR is open; a closed PR's
          # branch is stale and would overwrite human edits merged to dev.
          open_prs=$(gh pr list --repo "$GITHUB_REPOSITORY" \
            --head automation/update-chinese-docs --state open \
            --json number --jq 'length' || echo 0)
          if [ "${open_prs:-0}" -gt 0 ] && \
             git fetch origin automation/update-chinese-docs 2>/dev/null; then
            echo "Open translation PR found; reusing its translations."
            git checkout FETCH_HEAD -- docs/source/locale/zh_CN/LC_MESSAGES/ || true
          else
            echo "No open translation PR; using dev as the translation base."
          fi

      - name: Update gettext catalogs
        run: |
          sphinx-build -b gettext docs/source docs/build/gettext
          sphinx-intl update -p docs/build/gettext -l zh_CN -d docs/source/locale -j 1

      - name: Delete translations for renamed or removed docs
        run: |
          find docs/source/locale/zh_CN/LC_MESSAGES -name '*.po' | while read -r po; do
            rel="${po#docs/source/locale/zh_CN/LC_MESSAGES/}"
            if [ ! -f "docs/build/gettext/${rel%.po}.pot" ]; then
              echo "deleting $po (no matching source doc)"
              git rm -fq --ignore-unmatch "$po"
            fi
          done

      - name: Translate missing Chinese entries
        env:
          TRANSLATION_API_BASE_URL: ${{ secrets.TRANSLATION_API_BASE_URL }}
          TRANSLATION_API_KEY: ${{ secrets.TRANSLATION_API_KEY }}
          TRANSLATION_MODEL: ${{ secrets.TRANSLATION_MODEL }}
          TRANSLATION_MAX_ENTRIES: ${{ inputs.max_entries || '500' }}
        run: |
          python tools/translate_docs_zh.py

      - name: Validate Chinese docs build
        run: |
          SPHINX_LANGUAGE=zh_CN sphinx-build -b html docs/source docs/build/html/zh_CN

      - name: Open or update translation PR
        uses: peter-evans/create-pull-request@v8
        with:
          token: ${{ github.token }}
          branch: automation/update-chinese-docs
          base: dev
          delete-branch: true
          signoff: true
          add-paths: |
            docs/source/locale/zh_CN/LC_MESSAGES
          commit-message: "Update Chinese documentation translations"
          title: "Update Chinese documentation translations"
          body: |
            Automated weekly update for Chinese documentation translations.

            Generated by `.github/workflows/translate_doc_zh.yml`.
          labels: |
            documentation
            automation