A GitHub Action and CLI tool for managing translations of MyST Markdown documents using Claude AI.

Version: v0.26.0 | Full Documentation

What it does

GitHub Action — Runs in your CI pipeline with three modes:

Sync mode: When a PR is merged in the English source repo, automatically translates changed sections and opens a PR in the target language repo.
Review mode: When a translation PR is opened, posts an AI quality review with scores and suggestions.
Rebase mode: When a translation PR merges in the target repo, automatically rebases its open siblings, reusing cached translations for unchanged sections.

CLI tool (translate) — Eight commands for translation management:

status — Fast structural diagnostic (no LLM)
backward — Discover improvements in translations worth backporting to the source
review — Interactive walk-through of backward suggestions, creates GitHub Issues
forward — Recover from drift via whole-file RESYNC
init — Bulk-translate an entire project from scratch
setup — Scaffold a new target translation repository
doctor — Health check for target translation repos
headingmap — Generate heading-maps from source/target comparison (no LLM)

Quick start

GitHub Action

# .github/workflows/sync-translations.yml (in SOURCE repo)
name: Sync Translations
on:
  pull_request:
    types: [closed]
    paths: ['lectures/**/*.md']
  issue_comment:
    types: [created]
jobs:
  sync:
    # The issue_comment path needs a comment on a PR, the command, and a
    # trusted author — see the resync note below.
    if: >
      (github.event_name == 'pull_request' && github.event.pull_request.merged == true) ||
      (github.event_name == 'issue_comment' &&
       github.event.issue.pull_request &&
       startsWith(github.event.comment.body, '\translate-resync') &&
       contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association))
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 2
      - uses: quantecon/action-translation@v0
        with:
          mode: sync
          target-repo: 'quantecon/lecture-python.zh-cn'
          target-language: 'zh-cn'
          docs-folder: 'lectures/'
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          github-token: ${{ secrets.TRANSLATION_PAT }}

The issue_comment trigger enables the \translate-resync command — comment it on any merged PR to re-trigger sync (useful for recovering from failures). To retrigger only one language, add the code: \translate-resync fa or \translate-resync zh-cn. The run costs Anthropic credits and uses the target-repo PAT, so the if: admits only repo owners, org members and collaborators; comments from anyone else are ignored at the workflow level and never start a job.

CLI

npx translate status -s ~/repos/lecture-python-intro -t ~/repos/lecture-intro.zh-cn
npx translate backward -s SOURCE -t TARGET -o reports/
npx translate review reports/my-report --dry-run
npx translate forward -s SOURCE -t TARGET -f intro.md
npx translate init -s SOURCE -t TARGET --target-language zh-cn --dry-run

See the Quickstart guide for full setup instructions.

Documentation

Section	Description
Quickstart	Get running in 3 steps
Action Reference	All inputs, outputs, workflow examples
CLI Reference	All commands, options, examples
Glossary	Built-in and custom glossaries
Heading Maps	Cross-language section matching
Language Config	Language-specific rules
FAQ	Common questions and troubleshooting
Architecture	Design, modules, data flow
Testing	Test structure and how to write tests
Roadmap	Future features under consideration

Development

npm install          # Install dependencies
npm test             # Run the full test suite
npm run build        # Compile TypeScript + bundle the action (dist-action/)

License

MIT