Skip to content

quickstart.md

Latest commit

 

History

History
166 lines (126 loc) · 6.48 KB

quickstart.md

File metadata and controls

166 lines (126 loc) · 6.48 KB
Raw
title Quick Start

Quick Start

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]
    branches: [main]
    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 &&
       startsWith(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 into main — branches: [main] is what keeps a merge into a work-in-progress branch from being translated as if it were published (the action itself checks against the repository's default branch, so edit the filter if yours is not main). 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

  1. You merge a PR in the source repo that changes lectures/cobweb.md
  2. The sync workflow detects the changed sections, translates them with Claude, and creates a PR in the target repo
  3. The action posts a confirmation comment on the source PR with a link to the translation PR
  4. The review workflow (if configured) automatically reviews the translation PR and posts quality feedback
  5. 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