A GitHub Action and CLI toolkit for automatically translating and reviewing MyST Markdown documents using Claude AI.
Built by QuantEcon for managing multilingual lecture sites.
What it does¶
action-translation keeps translated repositories in sync with an English source. When content changes in the source, the system detects which sections changed and translates only those sections — preserving existing translations, technical formatting, and translator style.
The system has two main components:
GitHub Action — Runs automatically in your CI/CD pipeline:
Sync mode: Watches for merged PRs in the source repo, translates changed sections, and creates translation PRs in the target repo
Review mode: Posts AI-powered quality reviews on translation PRs with scores and suggestions
CLI tool (translate) — Runs locally for analysis and recovery:
status: Quick structural diagnostic — no LLM calls, shows which files are in sync, outdated, or missingbackward: Discovers improvements in translations worth backporting to the English sourcereview: Interactive walk-through of backward suggestions with GitHub Issue creationforward: Resyncs drifted translations to match current source contentinit: Bulk-translates an entire project from scratchsetup: Scaffolds a new target translation repositorydoctor: Checks health of a target translation repositoryheadingmap: Generates heading-maps by comparing source/target headings (no LLM)
Key features¶
Section-based translation — Only changed sections are re-translated, not entire documents
Heading-map system — Robust cross-language section matching via explicit ID mapping in frontmatter
Translation glossary — 357-term glossaries (zh-cn, fa) for consistent technical terminology
MyST Markdown aware — Preserves code blocks, math equations, directives, and cross-references
Language-extensible — Configurable rules per target language (punctuation, typography)
Multiple translation modes — UPDATE (incremental), NEW (fresh), RESYNC (drift recovery)
Documentation¶
Get started with the GitHub Action and CLI tool. Configuration reference, usage examples, and troubleshooting.
System architecture, module design, testing guide, and development roadmap for contributors.
Tutorials¶
Step-by-step guides for common scenarios:
| Tutorial | Scenario |
|---|---|
| Fresh Setup | Create a new translation project from scratch |
| Connect Existing Target | Add action-translation to a repo that was already translated |
| Resync Drifted Target | Catch up when translations fall behind the source |
| Backward Analysis & Review | Find improvements in translations worth backporting to the source |
| Adding a New Language | Extend to a new target language (glossary, config, workflows) |
| Automated Maintenance | Set up scheduled status checks and backward analysis |
Quick links¶
| Resource | Description |
|---|---|
| Quick Start | Set up the Action in 10 minutes |
| Action Reference | All GitHub Action inputs and outputs |
| CLI Reference | status, backward, review, forward, init, setup, doctor, headingmap commands |
| Architecture | System design and module map |
| GitHub Repository | Source code and issue tracker |
Current status¶
Version: v0.8.0
Tests: 873 (39 suites)
Glossary: 357 terms (zh-cn, fa)
Languages: English → Simplified Chinese, Farsi (more planned)