start-translation.yml

# Sync existing Boost submodules (update docs and submodule pointers).
#
# Trigger: repository_dispatch with event_type EVENT_START_TRANSLATION (start-translation).
# Example: POST /repos/{owner}/{repo}/dispatches
#   Body: {"event_type": "start-translation", "client_payload": {"version": "boost-1.90.0"}}
#
# Submodules list is taken from .gitmodules of this repository at master
# (only libs/ entries). No new org repos are created; run add-submodules first.
#
# Jobs:
#   setup — validate lang_codes and emit matrix JSON.
#   sync-mirrors — sync mirror master for all submodules; update super-repo master.
#     Zero libs/ entries in .gitmodules is a fatal precondition (run add-submodules first).
#     On partial submodule failure: finalize successful pointers, then exit non-zero.
#   start-local (matrix per lang) — local-{lang_code} in mirrors + super-repo + Weblate.
#     Runs per language when sync-mirrors succeeded (see job if:).
#     Requires a non-empty updated_submodules handoff; empty array is a job failure.
#
# client_payload:
#   lang_codes: (optional) Comma-separated lang codes (e.g. zh_Hans,ja). Defaults to vars.LANG_CODES.
#   version: (optional) Boost release ref (e.g. boost-1.90.0). Defaults to develop.
#   extensions: (optional) File extensions for Weblate (e.g. [.adoc, .md]). Default empty.
#
# Required secrets: SYNC_TOKEN, WEBLATE_URL, WEBLATE_TOKEN.
#   SYNC_TOKEN: push/PR access in MODULE_ORG. Repository variable SUBMODULES_ORG: org for
#   library repos (e.g. CppDigest). If unset, MODULE_ORG is this repo's org.
# Optional: LANG_CODES (used when lang_codes not in client_payload).

name: Start translation

on:
  repository_dispatch:
    # Must match EVENT_START_TRANSLATION in assets/env.sh
    types: [start-translation]

permissions:
  contents: read

jobs:
  setup:
    runs-on: ubuntu-latest
    outputs:
      json: ${{ steps.langs.outputs.json }}
    steps:
      - name: Checkout repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          token: ${{ secrets.SYNC_TOKEN }}
          persist-credentials: false

      - name: Prepare language matrix
        id: langs
        env:
          LANG_CODES: ${{ github.event.client_payload.lang_codes || vars.LANG_CODES }}
        run: |
          set -euo pipefail
          # shellcheck source=assets/env.sh
          source "$GITHUB_WORKSPACE/.github/workflows/assets/env.sh"
          # shellcheck source=assets/lib.sh
          source "$GITHUB_WORKSPACE/.github/workflows/assets/lib.sh"
          begin_phase "$PHASE_SETUP" "Validate language matrix"
          parse_and_validate_lang_codes
          langs_json=$(submodule_names_to_json "${lang_codes_arr[@]}")
          echo "json=$langs_json" >> "$GITHUB_OUTPUT"
          echo "Lang codes: ${lang_codes_arr[*]}" >&2
          end_phase

  sync-mirrors:
    needs: setup
    runs-on: ubuntu-latest
    outputs:
      updated_submodules: ${{ steps.sync.outputs.updated_submodules }}
    concurrency:
      group: translations-mirror-master
      cancel-in-progress: false
    steps:
      - name: Checkout repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          token: ${{ secrets.SYNC_TOKEN }}
          persist-credentials: false

      - name: Checkout master for .gitmodules
        run: |
          set -euo pipefail
          # shellcheck source=assets/env.sh
          source "$GITHUB_WORKSPACE/.github/workflows/assets/env.sh"
          git checkout "$MASTER_BRANCH"

      - name: Sync mirror master
        id: sync
        shell: bash
        env:
          GITHUB_TOKEN: ${{ secrets.SYNC_TOKEN }}
          LIBS_REF: ${{ github.event.client_payload.version || 'develop' }}
          SUBMODULES_ORG: ${{ vars.SUBMODULES_ORG }}
        run: |
          set -euo pipefail

          # shellcheck disable=SC2034
          lang_codes_arr=()

          # shellcheck source=assets/env.sh
          source "$GITHUB_WORKSPACE/.github/workflows/assets/env.sh"
          # shellcheck source=assets/lib.sh
          source "$GITHUB_WORKSPACE/.github/workflows/assets/lib.sh"
          # shellcheck source=assets/translation.sh
          source "$GITHUB_WORKSPACE/.github/workflows/assets/translation.sh"
          # shellcheck source=assets/submodule_ops.sh
          source "$GITHUB_WORKSPACE/.github/workflows/assets/submodule_ops.sh"

          init_translation_state
          init_submodule_summary_buckets

          begin_phase "$PHASE_SETUP" "Prepare workspace"
          validate_secrets

          init_translation_work_dirs with_org_work
          gh auth setup-git

          # shellcheck disable=SC2034
          START_PHASE="$START_PHASE_MIRRORS"
          # libs_ref is read by translation.sh (sourced).
          # shellcheck disable=SC2034
          libs_ref="${LIBS_REF:?}"

          [[ ! -f .gitmodules ]] && {
            phase_err ".gitmodules not found (run from translations repo with master checked out)"
            end_phase
            exit 1
          }

          require_libs_submodules_in_gitmodules ".gitmodules" || {
            end_phase
            exit 1
          }

          mapfile -t submodule_names < <(libs_submodule_names_from_gitmodules_file ".gitmodules")
          end_phase

          begin_phase "$PHASE_PROCESS_SUBMODULES" "Sync mirror master"
          echo "Syncing mirror master for ${#submodule_names[@]} submodules." >&2

          rc=0
          ensure_translations_cloned "$ORG" "$TRANSLATIONS_REPO" "$TRANS_DIR" || rc=$?
          if [[ $rc -ne 0 ]]; then
            end_phase
            exit $rc
          fi

          process_submodule_list sync_one_submodule "${submodule_names[@]}"
          end_phase

          begin_phase "$PHASE_FINALIZE_TRANSLATIONS" "Finalize translations master"
          rc=0
          finalize_translations_master "$TRANS_DIR" "$LIBS_REF" || rc=$?
          end_phase

          combine_batch_and_finalize_rc "$rc" || exit_rc=$?
          if [[ ${exit_rc:-0} -eq 0 ]]; then
            updated_json=$(submodule_names_to_json "${UPDATES[@]}")
            echo "updated_submodules=$updated_json" >> "$GITHUB_OUTPUT"
            echo "Submodules for start-local: $updated_json" >&2
            echo "Done." >&2
          else
            exit "$exit_rc"
          fi

  start-local:
    # Run when sync-mirrors succeeded; empty updated_submodules is a fatal error inside the job.
    if: ${{ always() && !cancelled() && needs.setup.result == 'success' && needs.sync-mirrors.result == 'success' }}
    needs: [setup, sync-mirrors]
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        lang: ${{ fromJson(needs.setup.outputs.json) }}
    concurrency:
      group: local-branch-${{ matrix.lang }}
      cancel-in-progress: false
    steps:
      - name: Checkout repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          token: ${{ secrets.SYNC_TOKEN }}
          persist-credentials: false

      - name: Checkout master for .gitmodules
        run: |
          set -euo pipefail
          # shellcheck source=assets/env.sh
          source "$GITHUB_WORKSPACE/.github/workflows/assets/env.sh"
          git checkout "$MASTER_BRANCH"

      - name: Start translation for ${{ matrix.lang }}
        shell: bash
        env:
          GITHUB_TOKEN: ${{ secrets.SYNC_TOKEN }}
          LIBS_REF: ${{ github.event.client_payload.version || 'develop' }}
          LANG_CODE: ${{ matrix.lang }}
          EXTENSIONS: ${{ github.event.client_payload.extensions || '' }}
          WEBLATE_URL: ${{ secrets.WEBLATE_URL }}
          WEBLATE_TOKEN: ${{ secrets.WEBLATE_TOKEN }}
          SUBMODULES_ORG: ${{ vars.SUBMODULES_ORG }}
          SYNC_MIRROR_UPDATES: ${{ needs.sync-mirrors.outputs.updated_submodules }}
        run: |
          set -euo pipefail

          # shellcheck source=assets/env.sh
          source "$GITHUB_WORKSPACE/.github/workflows/assets/env.sh"
          # shellcheck source=assets/lib.sh
          source "$GITHUB_WORKSPACE/.github/workflows/assets/lib.sh"
          # shellcheck source=assets/translation.sh
          source "$GITHUB_WORKSPACE/.github/workflows/assets/translation.sh"
          # shellcheck source=assets/submodule_ops.sh
          source "$GITHUB_WORKSPACE/.github/workflows/assets/submodule_ops.sh"

          init_translation_state
          init_submodule_summary_buckets

          begin_phase "$PHASE_SETUP" "Prepare workspace"
          validate_secrets weblate

          init_translation_work_dirs with_org_work
          gh auth setup-git

          # shellcheck disable=SC2034
          START_PHASE="$START_PHASE_LOCAL"
          # shellcheck disable=SC2034,SC2153
          libs_ref="${LIBS_REF:?}"

          echo "Lang code: $LANG_CODE" >&2

          # Read by sync_one_submodule in translation.sh (sourced above).
          # shellcheck disable=SC2034
          lang_codes_arr=("$LANG_CODE")
          init_add_or_update_lang "$LANG_CODE"

          echo "Submodules from sync-mirrors: ${SYNC_MIRROR_UPDATES:-[]}" >&2
          mapfile -t submodule_names < <(parse_submodule_names_json "${SYNC_MIRROR_UPDATES:-[]}")

          [[ ${#submodule_names[@]} -eq 0 ]] && {
            phase_err "No submodules from sync-mirrors to process (updated_submodules is empty)."
            end_phase
            exit 1
          }
          end_phase

          begin_phase "$PHASE_ENSURE_BRANCHES" "Ensure local branch in translations repo"
          rc=0
          ensure_translations_cloned "$ORG" "$TRANSLATIONS_REPO" "$TRANS_DIR" || rc=$?
          if [[ $rc -eq 0 ]]; then
            ensure_local_branch_in_translations "$TRANS_DIR" "$LANG_CODE" || rc=$?
          fi
          end_phase
          [[ $rc -ne 0 ]] && exit $rc

          begin_phase "$PHASE_PROCESS_SUBMODULES" "Process local branches"
          echo "Processing local branches for ${#submodule_names[@]} submodules." >&2

          process_submodule_list sync_one_submodule "${submodule_names[@]}"
          end_phase

          begin_phase "$PHASE_FINALIZE_TRANSLATIONS" "Finalize translations local branch"
          rc=0
          finalize_translations_local "$TRANS_DIR" "$LIBS_REF" "$LANG_CODE" || rc=$?
          end_phase

          weblate_rc=0
          if [[ $rc -eq 0 ]]; then
            begin_phase "$PHASE_TRIGGER_WEBLATE" "Trigger Weblate add-or-update"
            ext_arr=()
            [[ -n "${EXTENSIONS:-}" ]] && mapfile -t ext_arr < <(parse_extensions "$EXTENSIONS")
            exts_json="[]"
            [[ ${#ext_arr[@]} -gt 0 ]] && \
              exts_json=$(printf '%s\n' "${ext_arr[@]}" | jq -R . | jq -s .)

            trigger_weblate "$WEBLATE_URL" "$WEBLATE_TOKEN" "$LIBS_REF" "$exts_json" "$LANG_CODE" || weblate_rc=$?
            end_phase
          else
            echo "Skipping Weblate add-or-update: finalize_translations_local failed (rc=$rc)." >&2
          fi

          combine_batch_and_finalize_rc "$rc" "$weblate_rc" || exit $?

          echo "Done." >&2