Quick Start - action-translation

Get action-translation running in your repositories in three steps.

Prerequisites¶

Two GitHub repositories: a source (English) and a target (translated) repo
Both repos contain MyST Markdown files in a docs folder (e.g., lectures/)
An Anthropic API key for Claude
A GitHub Personal Access Token (PAT) with repo scope for cross-repo access

Step 1: Set up secrets¶

In your source repository, go to Settings → Secrets and variables → Actions and add:

Secret	Value
`ANTHROPIC_API_KEY`	Your Anthropic API key
`TRANSLATION_PAT`	A GitHub PAT with `repo` scope for the target repository

Step 2: Add the sync workflow¶

Create .github/workflows/sync-translations.yml in your source repository:

name: Sync Translations

on:
  pull_request:
    types: [closed]
    paths:
      - 'lectures/**/*.md'
      - '_toc.yml'
  issue_comment:
    types: [created]

jobs:
  sync-to-chinese:
    # The issue_comment path requires all three: a comment on a PR (not a bare
    # issue), the command, and a trusted author — otherwise any account could
    # fire a secrets-bearing run (Anthropic spend plus the PAT) from any comment.
    if: >
      (github.event_name == 'pull_request' && github.event.pull_request.merged == true) ||
      (github.event_name == 'issue_comment' &&
       github.event.issue.pull_request &&
       contains(github.event.comment.body, '\translate-resync') &&
       contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association))
    runs-on: ubuntu-latest

    # The action authenticates with TRANSLATION_PAT; the ambient GITHUB_TOKEN
    # is unused beyond checkout, so keep it read-only.
    permissions:
      contents: read

    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 2

      - uses: QuantEcon/action-translation@v0
        with:
          mode: sync
          target-repo: 'YourOrg/your-repo.zh-cn'
          target-language: 'zh-cn'
          docs-folder: 'lectures/'
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          github-token: ${{ secrets.TRANSLATION_PAT }}

This workflow triggers whenever a PR that touches Markdown files in lectures/ is merged. It detects which sections changed and creates a translation PR in the target repository. The issue_comment trigger enables re-syncing by commenting \translate-resync on a merged PR. To retrigger only one language, add the language code (e.g., \translate-resync zh-cn).

The author_association check on that clause is a trust gate: an issue_comment workflow runs with full access to your secrets, so without it any GitHub account could spend Anthropic credits by commenting on a merged PR. Keep all four conditions — dropping any one of them re-opens that.

Step 3: Add the review workflow (optional)¶

Create .github/workflows/review-translations.yml in your target repository:

name: Review Translations

on:
  pull_request:
    types: [opened, synchronize, labeled, reopened]

jobs:
  review:
    # `labeled` matters: the sync applies its labels after opening the PR.
    # The second clause ignores `labeled` events for every other label.
    if: >
      contains(github.event.pull_request.labels.*.name, 'action-translation') &&
      (github.event.action != 'labeled' || github.event.label.name == 'action-translation')
    runs-on: ubuntu-latest

    permissions:
      contents: read
      pull-requests: write

    # One review per PR — supersede an in-flight review instead of running both
    concurrency:
      group: review-translations-${{ github.event.pull_request.number }}
      cancel-in-progress: true

    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 2

      - uses: QuantEcon/action-translation@v0
        with:
          mode: review
          source-repo: 'YourOrg/your-source-repo'
          source-language: 'en'
          docs-folder: 'lectures/'
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

This posts an AI-generated quality review comment on each translation PR, including a translation score, diff quality score, and improvement suggestions. There is no target-language input in review mode — the language is detected from the repository-name suffix (your-repo.zh-cn → zh-cn).

What happens next¶

You merge a PR in the source repo that changes lectures/cobweb.md
The sync workflow detects the changed sections, translates them with Claude, and creates a PR in the target repo
The action posts a confirmation comment on the source PR with a link to the translation PR
The review workflow (if configured) automatically reviews the translation PR and posts quality feedback
A human reviewer approves and merges the translation PR

If the sync fails, the action automatically opens a GitHub Issue with error details and recovery instructions. You can re-run the sync by commenting \translate-resync on the merged PR, or target a specific language with \translate-resync fa.

Only changed sections are translated — the rest of the document is preserved exactly as-is.

Using the CLI tool¶

For local analysis and drift recovery, install the CLI:

# Clone the repository
git clone https://github.com/QuantEcon/action-translation.git
cd action-translation
npm install
npm run build:cli

# Check sync status (no API key needed)
npx translate status -s ~/source-repo -t ~/target-repo

# Run backward analysis (finds improvements in translations)
export ANTHROPIC_API_KEY=your-key
npx translate backward -s ~/source-repo -t ~/target-repo

# Forward resync (updates translations to match source)
npx translate forward -s ~/source-repo -t ~/target-repo -f cobweb.md

See the CLI Reference for full command documentation.

Next steps¶

Action Reference — All inputs, outputs, and configuration options
CLI Reference — Complete CLI command documentation
Glossary — How to use and extend translation glossaries
Heading Maps — Understanding the cross-language section matching system