Update docs to reflect manual translation workflow

.github/workflows/check-headings.yml

@@ -7,7 +7,7 @@ jobs:
   check-headings:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Install uv
         uses: astral-sh/setup-uv@v5

.github/workflows/docker-devcontainer.yml

@@ -36,7 +36,7 @@ jobs:
           fi
 
       - name: Check out the repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up QEMU for multi-architecture builds
         uses: docker/setup-qemu-action@v3

.github/workflows/docker-mkdocs.yml

@@ -17,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out the repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Login to GitHub Container Registry
         uses: docker/login-action@v3

.github/workflows/docs.yml

@@ -25,7 +25,7 @@ jobs:
     outputs:
       languages: ${{ steps.find.outputs.languages }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           sparse-checkout: docs
 
@@ -45,9 +45,9 @@ jobs:
       matrix:
         lang: ${{ fromJson(needs.discover-languages.outputs.languages) }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 
@@ -57,7 +57,7 @@ jobs:
       - name: Build ${{ matrix.lang }} docs
         run: mkdocs build -f docs/${{ matrix.lang }}/mkdocs.yml -d ${{ github.workspace }}/site-${{ matrix.lang }}
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: site-${{ matrix.lang }}
           path: site-${{ matrix.lang }}/
@@ -93,15 +93,15 @@ jobs:
           echo "IS_RELEASE=$IS_RELEASE" >> $GITHUB_ENV
           echo "Building docs version: $VERSION (alias: $ALIAS, is_release: $IS_RELEASE)"
 
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           path: artifacts
 

.github/workflows/nextflow-lint-comment.yml

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Download lint results
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: lint-results
           github-token: ${{ github.token }}

.github/workflows/nextflow-lint.yml

@@ -8,7 +8,7 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Install Nextflow
         uses: nf-core/setup-nextflow@v2
@@ -195,7 +195,7 @@ jobs:
 
       - name: Upload lint results
         if: always() && github.event_name == 'pull_request'
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: lint-results
           path: lint-results/

.github/workflows/precommit.yml

@@ -8,8 +8,8 @@ jobs:
   pre-commit:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.x"
       - uses: pre-commit/action@v3.0.1

.github/workflows/translate.yml

@@ -1,8 +1,9 @@
 name: Translate
 
 on:
+  # Translations are triggered manually by maintainers, typically ahead of a new release.
   # Automatic: when English content or prompts change
-  # Commented out to save API costs - run manually as needed
+  # [EDIT] Commented out to save API costs - run manually as needed
   # push:
   #   branches:
   #     - master
@@ -41,7 +42,7 @@ jobs:
       languages: ${{ steps.detect.outputs.languages }}
       has_work: ${{ steps.detect.outputs.has_work }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -70,7 +71,7 @@ jobs:
       matrix:
         language: ${{ fromJson(needs.detect.outputs.languages) }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -89,7 +90,7 @@ jobs:
 
       - name: Upload translation artifacts
         if: success()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: translation-${{ matrix.language }}
           path: docs/${{ matrix.language }}/docs/
@@ -98,7 +99,7 @@ jobs:
 
       - name: Upload translation log
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: log-${{ matrix.language }}
           path: _scripts/translate-${{ matrix.language }}.json
@@ -110,14 +111,14 @@ jobs:
     if: always() && needs.detect.outputs.has_work == 'true' && !cancelled()
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
           ref: ${{ github.sha }} # Use trigger SHA, not latest master (avoids workflow file conflicts)
           token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Download all translation artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           pattern: translation-*
           path: artifacts/

CONTRIBUTING.md

@@ -113,7 +113,8 @@ Then use the GitHub Actions workflow to regenerate:
 2. Select the language and `sync` command
 3. The workflow will regenerate the translation with your prompt changes
 
-When prompts are merged to master, GitHub Actions automatically re-translates affected files to comply with the new guidelines.
+Translation runs are triggered manually by maintainers, typically ahead of a new release.
+Resulting translation PRs should be merged promptly to avoid them stacking up or becoming outdated.
 
 ### Why AI-Only?
 

TRANSLATING.md

@@ -22,7 +22,7 @@ The key insight: **to fix a translation, fix the prompt** - not the translated f
 ### Contents
 
 - [How to Improve Existing Translations](#how-to-improve-existing-translations)
-- [How Automatic Translation Updates Work](#how-automatic-translation-updates-work)
+- [How Translation Updates Work](#how-translation-updates-work)
 - [Reviewing Translation PRs](#reviewing-translation-prs)
 - [How to Add a Missing Course](#how-to-add-a-missing-course)
 - [How to Add a New Language](#how-to-add-a-new-language)
@@ -144,16 +144,20 @@ Good prompt improvements include:
 
 ---
 
-## How Automatic Translation Updates Work
+## How Translation Updates Work
 
-Translations are automatically updated via GitHub Actions when:
+Translation runs are triggered manually via the GitHub Actions workflow, typically ahead of a new release of the training materials (but can be done at any time).
+A maintainer triggers the workflow, which detects what has changed and updates the relevant translations.
 
-1. **English source files change** → Outdated translations are updated
-2. **Translation prompts change** → Existing translations are fixed to comply with new guidelines
+The workflow handles three types of changes:
+
+1. **English source files changed** → Outdated translations are updated
+2. **Language-specific prompt changed** → That language's translations are fixed to comply with new guidelines
+3. **General prompt changed** → All languages are re-translated
 
 ```mermaid
 flowchart TD
-    A[Change detected] --> B{What changed?}
+    A[Maintainer triggers<br>translation workflow] --> B{What changed<br>since last run?}
     B -->|English content| C[Detect outdated translations]
     B -->|Language prompt| D[Fix that language's translations]
     B -->|General prompt| E[Fix ALL languages]
@@ -166,25 +170,27 @@ flowchart TD
     I --> J
     J --> K[Human review]
     K --> L{Approved?}
-    L -->|Yes| M[Merge PR]
+    L -->|Yes| M[Merge PR promptly]
     L -->|No| N[Update llm-prompt.md]
     N --> O[Re-run translation]
     O --> K
 ```
 
 ### Key Points
 
+- Translation runs are **triggered manually**, not automatically on push
+- Runs are typically done **ahead of a new release**, but can be triggered at any time
 - The AI makes **minimal changes**, updating only sections that changed in English
 - Translations preserve line-by-line structure for easy diff review
 - Each language gets a separate PR for independent review/merge
 - The system uses git commit timestamps to detect outdated files
-- **Prompt changes trigger automatic re-translation** of affected files
+- **Translation PRs should be merged promptly** to avoid them stacking up or becoming outdated
 
 ---
 
 ## Reviewing Translation PRs
 
-When reviewing a translation PR (whether automatic or triggered manually), follow these guidelines:
+When reviewing a translation PR, follow these guidelines:
 
 ### What to Check