CLI Reference

The translate CLI tool provides local analysis and recovery capabilities for translation repositories. It complements the GitHub Action by handling tasks that require interactive use or don’t fit a CI/CD pipeline.

Installation¶

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

The CLI is available as npx translate from within the repository.

Environment variables¶

Commands¶

status — Sync diagnostic¶

Fast structural check with no LLM calls. Compares source and target repositories and reports per-file sync status.

npx translate status -s <source-path> -t <target-path> [options]

Options:

Status categories:

Example:

npx translate status \
  -s ~/repos/lecture-python-intro \
  -t ~/repos/lecture-intro.zh-cn

Output:

 Status Summary: lecture-python-intro ↔ lecture-intro.zh-cn
┌──────────────────────────────────┬──────────────────┐
│ File                             │ Status           │
├──────────────────────────────────┼──────────────────┤
│ cobweb.md                        │ ✅ ALIGNED       │
│ solow.md                         │ ✅ ALIGNED       │
│ cagan_adaptive.md                │ ⚠️  OUTDATED     │
│   ↳ SOURCE has 3 newer commits   │                  │
│ pv.md                            │ ⚠️  SOURCE_AHEAD │
│   ↳ SOURCE: 8 sections, TARGET: 7│                  │
└──────────────────────────────────┴──────────────────┘

backward — Discover backport suggestions¶

Two-stage analysis that finds improvements in translations worth backporting to the English source.

Stage 1 (triage): Lightweight LLM call per file — “Are there substantive changes beyond translation?” Most files are filtered out here (~80%).

Stage 2 (evaluation): Detailed LLM analysis of flagged files — per-section comparison producing categorised suggestions with confidence scores.

npx translate backward -s <source-path> -t <target-path> [options]

Options:

Bulk mode issues up to 5 concurrent Anthropic calls by default — --parallel is the concurrency (and cost-burst) control, clamped to [1, 10]. --source-language deliberately has no CLI default here: it resolves flag → .translate/config.yml source-language → en.

Single-file example:

npx translate backward \
  -s ~/repos/lecture-python-intro \
  -t ~/repos/lecture-intro.zh-cn \
  -f cobweb.md \
  -o ./reports

Bulk example (all files):

npx translate backward \
  -s ~/repos/lecture-python-intro \
  -t ~/repos/lecture-intro.zh-cn

Output structure (bulk mode):

reports/backward-2026-03-06/
├── _summary.md           # Aggregate summary
├── _summary.json         # (with --json)
├── .resync/              # Machine-readable data
│   ├── _progress.json    # Checkpoint manifest
│   ├── _log.txt          # Detailed processing log
│   ├── cobweb.json       # Per-file JSON sidecar
│   └── solow.json
├── cobweb.md             # Per-file Markdown report
└── solow.md

Suggestion categories:

review — Interactive suggestion review¶

Walks through backward analysis suggestions interactively, letting you accept, skip, or reject each one. Accepted suggestions become GitHub Issues in the source repository.

npx translate review <report-dir> [options]

Arguments:

Options:

Example:

# Dry run — preview what Issues would look like
npx translate review reports/backward-2026-03-06 --dry-run

# Create Issues in the source repo
npx translate review reports/backward-2026-03-06 \
  --repo QuantEcon/lecture-python-intro

Interactive controls:

Issues are created with labels: translate, translate:{category} (e.g., translate:bug-fix), translate:{language} (e.g., translate:zh-cn).

Requires the gh CLI to be installed and authenticated for Issue creation.

forward — Resync translations¶

Updates target translations to match current source content. Used for drift recovery when translations have fallen behind due to failed syncs, manual edits, or initial onboarding.

The forward pipeline:

1. Triage each file with a lightweight LLM call to distinguish real content changes from i18n-only differences

2. Whole-file RESYNC — sends the complete source and existing translation to Claude, which produces an updated translation preserving existing style and localisation

3. Write the updated file locally, or create a PR

npx translate forward -s <source-path> -t <target-path> [options]

Options:

Bulk mode issues up to 5 concurrent Anthropic calls by default (--parallel, clamped to [1, 10]); with --github it runs sequentially, because parallel git operations in one worktree would race. --source-language resolves flag → .translate/config.yml → en.

Single-file example:

npx translate forward \
  -s ~/repos/lecture-python-intro \
  -t ~/repos/lecture-intro.zh-cn \
  -f cobweb.md

After running, review the changes with git diff in the target repo. Use git restore . to undo if needed.

Bulk example (all outdated files):

# Run the resync
npx translate forward \
  -s ~/repos/lecture-python-intro \
  -t ~/repos/lecture-intro.zh-cn

On a partial edition, name each translated lecture with -f, or leave the English copies out with --exclude. A bulk run resyncs each copy the source has moved on from and writes a state file for it, and under sync-scope: existing that state file puts the copy in sync’s scope (see Partial editions).

GitHub PR mode:

npx translate forward \
  -s ~/repos/lecture-python-intro \
  -t ~/repos/lecture-intro.zh-cn \
  --github QuantEcon/lecture-intro.zh-cn

Creates one PR per file in the target repo with branch resync/{filename} and labels action-translation, action-translation-sync, resync. The action-translation label is the one the review workflow template gates on, so these PRs trigger AI review automatically.

Forward triage verdicts:

init — Bulk-translate a new project¶

One-time bulk translation of an entire lecture series from a local source repository. Reads _toc.yml for lecture discovery, translates each lecture sequentially with translateFullDocument(), generates heading-maps, and produces a translation report.

This is intended for onboarding a new project — use forward for incremental updates after the initial translation.

npx translate init -s <source-path> -t <target-path> --target-language <code> [options]

Options:

Localization rules¶

The --localize flag controls what gets localized inside code cells (which are normally preserved as-is). Each rule can be individually enabled or disabled via a comma-separated list.

All rules are ON by default. To disable all localization: --localize none. To use a subset: --localize code-comments,figure-labels.

Font configuration (i18n-font-config)¶

When i18n-font-config is active and the target language requires special fonts (currently zh-cn), the LLM is instructed to inject font setup code into the first code cell that imports matplotlib. The injected code references a font file at a hard-coded path: _fonts/<fontfile>.

zh-cn (Simplified Chinese):

The translated code cells will contain:

import matplotlib as mpl  # i18n
FONTPATH = "_fonts/SourceHanSerifSC-SemiBold.otf"  # i18n
mpl.font_manager.fontManager.addfont(FONTPATH)  # i18n
plt.rcParams['font.family'] = ['Source Han Serif SC']  # i18n

You must manually place the font file at <docs-folder>/_fonts/SourceHanSerifSC-SemiBold.otf in your target repository. The init command creates the _fonts/ directory and prints download instructions.

Download: Source Han Serif SC — use the SourceHanSerifSC-SemiBold.otf file from the release assets.

Other languages: fa (Farsi) does not require special font configuration. Languages without a font config entry silently skip this rule.

7-phase pipeline:

1. Load glossary — --glossary if given, else a repo-local glossary/<lang>.json, else the built-in glossary shipped with the package (see Glossary)

2. Parse _toc.yml — discovers lectures from the source repo’s table of contents

3. Setup target folder — creates the target directory structure

4. Copy non-markdown files — images, config, data files, CSS (preserves directory structure)

5. Translate lectures — sequentially with retry + progress bar

6. Generate heading-maps — position-based section matching, injected into frontmatter

7. Write report — TRANSLATION-REPORT.md with stats, config, and failure details

Dry run example (preview without API calls):

npx translate init \
  -s ~/repos/lecture-python-intro \
  -t ~/repos/lecture-python-intro.zh-cn \
  --target-language zh-cn \
  --dry-run

Output:

🔍 DRY RUN — No changes will be made

Source:   /Users/you/repos/lecture-python-intro
Target:   /Users/you/repos/lecture-python-intro.zh-cn
Language: en → zh-cn
Model:    claude-sonnet-5
✓ Loaded built-in glossary for zh-cn — 357 terms (/path/to/action-translation/glossary/zh-cn.json)

Found 51 lectures in _toc.yml

Would translate the following lectures:
  1. intro.md ✓
  2. getting_started.md ✓
  3. cobweb.md ✓
  ...

Would copy 24 non-markdown file(s)

Run without --dry-run to translate.

Full translation example:

npx translate init \
  -s ~/repos/lecture-python-intro \
  -t ~/repos/lecture-python-intro.zh-cn \
  --target-language zh-cn

One lecture, for an edition whose lectures are reviewed before they are published:

npx translate init \
  -s ~/repos/lecture-python-intro \
  -t ~/repos/lecture-python-intro.zh-cn \
  --target-language zh-cn \
  -f cobweb.md \
  --dry-run

-f names a lecture listed in the source _toc.yml, and takes the first entry in ToC order that equals or contains the name. Preview with --dry-run first: it prints the Translating single file: line with the lecture it matched, and stops before translating or writing anything. Then run the same command without --dry-run. -f narrows the translation, not the rest of the run: every run except a dry run rewrites .translate/config.yml and TRANSLATION-REPORT.md, and copies every non-Markdown file in the source docs folder into the target, _toc.yml and _config.yml included. Each lecture then joins the edition in its own PR, with its state file (see Tutorial: Fresh Setup).

Resume from a specific lecture (after a failure or interruption):

npx translate init \
  -s ~/repos/lecture-python-intro \
  -t ~/repos/lecture-python-intro.zh-cn \
  --target-language zh-cn \
  --resume-from cobweb.md

Partial filename matches are supported — --resume-from cobweb will also work.

Re-run after partial failure (skip already-translated files):

npx translate init \
  -s ~/repos/lecture-python-intro \
  -t ~/repos/lecture-python-intro.zh-cn \
  --target-language zh-cn \
  --skip-existing

This reads .translate/state/ entries and skips lectures that were already translated. Unlike --resume-from (which is linear), --skip-existing handles scattered failures across the TOC.

Parallel translation (4 concurrent workers):

npx translate init \
  -s ~/repos/lecture-python-intro \
  -t ~/repos/lecture-python-intro.zh-cn \
  --target-language zh-cn \
  -j 4

Output:

A TRANSLATION-REPORT.md file is written to the target directory with:

• Total lectures, success/failure/skipped counts

• Total tokens used, total time

• Configuration details

• List of any failures with error messages

Typical workflow¶

A complete translation maintenance workflow using the CLI:

# 1. Check sync status (free, instant)
npx translate status -s ~/source -t ~/target

# 2. Run backward analysis to find improvements (LLM, ~$1.10 for 51 files)
npx translate backward -s ~/source -t ~/target

# 3. Review suggestions interactively, create Issues for accepted ones
npx translate review reports/backward-2026-03-06 --repo QuantEcon/lecture-python-intro

# 4. Forward resync any outdated files (LLM, ~$0.16/file)
npx translate forward -s ~/source -t ~/target
cd ~/target && git diff  # Review changes

For initial project onboarding, use setup + init:

# Scaffold a new target repository
npx translate setup --source QuantEcon/lecture-python-intro --target-language zh-cn

# Translate entire project from scratch
npx translate init -s ~/source -t ~/target --target-language zh-cn --dry-run
npx translate init -s ~/source -t ~/target --target-language zh-cn

For existing paired projects, bootstrap .translate/ metadata:

# One-time: write .translate/ config + per-file state
npx translate status -s ~/source -t ~/target -l zh-cn --write-state

On a partial edition, run forward (step 4 above) and --write-state per translated lecture instead, or with the English copies excluded, so that no copy is rewritten or gets a state file (see Bootstrapping existing projects).

Cost estimates¶

Approximate costs using claude-sonnet-5 ($2 /$10 per M input/output tokens; cache reads $0.20 per M). The figures below are rough estimates made before prompt caching and at an earlier$3 / $15 price; the uncached whole-file French translation measured in the [thinking-sonnet5 report](https://github.com/QuantEcon/action-translation/blob/main/experiments/thinking-sonnet5/REPORT.md) (9,715 output tokens,$0.21 at that price) comes to about $0.14 at$2 / $10:

.translate/ metadata folder¶

The .translate/ folder in the target repo stores persistent sync metadata. It enables exact staleness detection, skip optimisation for backward analysis, and translation provenance. The sync Action reads it too: under sync-scope: existing, a lecture’s state file is what puts it in scope (see Partial editions).

Structure¶

.translate/
├── config.yml              # Project-level settings
└── state/
    ├── intro.md.yml        # Per-file sync metadata
    ├── cobweb.md.yml
    └── advanced/
        └── topic.md.yml    # Mirrors docs-folder subdirectories

config.yml¶

source-language: en
target-language: zh-cn
docs-folder: lectures
tool-version: <tool version>    # Version that last wrote this config

Provides defaults so CLI flags don’t need to be repeated every invocation.

Per-file state (state/<file>.yml)¶

source-sha: abc1234f           # Commit SHA that last touched the source file
synced-at: "2026-03-06"        # ISO date of last sync
model: claude-sonnet-5     # Model used for translation
mode: NEW                      # Translation mode: NEW / UPDATE / RESYNC
section-count: 5               # Source section count at sync time
tool-version: <tool version>   # Version that performed this sync

How each command uses .translate/¶

init does not fail when it cannot write a lecture’s state file. Check that .translate/state/<file>.yml exists before committing the lecture: without it, the lecture is out of scope under sync-scope: existing.

Graceful absence¶

If .translate/ doesn’t exist, status, backward and forward fall back to git heuristics, and a sync under the default sync-scope: all works as before; doctor reports the folder missing. Under sync-scope: existing, absence is not graceful: a lecture without a state file is out of scope, so an edition with no state files syncs no lecture. Only removals and _toc.yml changes reach it.

Bootstrapping existing projects¶

For projects that predate .translate/, bootstrap state with status --write-state:

npx translate status \
  -s /path/to/source \
  -t /path/to/target \
  -l zh-cn \
  --write-state

This:

1. Creates .translate/config.yml from the provided flags

2. For each translated file, records the current source commit as source-sha

3. Uses the target file’s last commit date as synced-at

4. Keeps the model a file’s existing state names; otherwise marks model: unknown (not recoverable from history)

It refuses in three cases:

• An English commit dated after the translation’s last commit. The translation may predate the English it would be recorded against: bring it up to date first, for example with forward. For a file without a state file this is the only check, and any later commit to the translation passes it, whether or not the translation carries the English: confirm the translation matches the current English before writing its state (--check-sync; Step 2 of Tutorial: Connect an Existing Target).

• English changes since the commit a state file records. When a file already has a state file and the English file has changed since the commit it records, recording the current commit would mark those changes as carried into the translation. The refusal lists each such file with the English commits since its recorded commit. It also refuses a file whose recorded commit is not in the local source clone, since git cannot tell what changed: pull or unshallow the clone. Once the translation carries every change and is committed, rerun with --carried to confirm it. A recorded commit whose version of the file is the current one, such as the merge commit a sync records, passes.

• A state file that exists but cannot be read. It is left as it is: repair or delete it.

The first two checks refuse the whole run before anything is written. The third lets the run write the config and the other files’ state, then fails, naming each unreadable file. --force skips all three; --carried skips only the second.

On a partial edition, write state only for the lectures it has translated. Without -f or --exclude, --write-state writes one for every .md file at the top level of the docs folder that both repositories have, English copies included, and under sync-scope: existing each state file puts its lecture in scope. Run it once per translated lecture with -f, or leave the English copies out with --exclude; a translated lecture in a subfolder needs -f either way, for example -f advanced/topic.md. Pass the edition’s own -l and -d every time, since each run rewrites .translate/config.yml from the flags:

npx translate status \
  -s /path/to/source \
  -t /path/to/target \
  -l ml \
  -d lectures \
  -f functions.md \
  --write-state

setup — Scaffold a target repository¶

Creates a new GitHub repository for hosting translations. Pairs with init for the complete onboarding workflow: setup → init → push → configure Action.

npx translate setup --source <owner/repo> --target-language <code> [options]

Options:

What it does:

1. Derives target repo name: {source-repo}.{lang} (e.g., lecture-python-intro.zh-cn)

2. Creates GitHub repo via gh repo create and clones it locally

3. Writes .translate/config.yml, .github/workflows/review-translations.yml, .github/workflows/rebase-translations.yml, .gitignore, README.md

4. Makes initial commit and pushes

Requirements: The gh CLI must be installed and authenticated (gh auth login).

Example:

# Scaffold and clone a new target repo
npx translate setup --source QuantEcon/lecture-python-intro --target-language zh-cn

# Preview without creating
npx translate setup --source QuantEcon/lecture-python-intro --target-language zh-cn --dry-run

doctor — Health check for target repos¶

Validates that a target translation repository is properly configured. Like brew doctor or flutter doctor — traffic-light output.

npx translate doctor -t <target-path> [options]

Options:

What it checks:

Exits with code 1 if any check fails — suitable for CI.

Example:

# Check a target repo
npx translate doctor -t ~/repos/lecture-python-intro.zh-cn

# Include source cross-checks
npx translate doctor -t ~/repos/lecture-python-intro.zh-cn -s ~/repos/lecture-python-intro

# JSON output for scripting
npx translate doctor -t ~/repos/lecture-python-intro.zh-cn --json

headingmap — Generate heading-maps¶

Generates heading-maps by comparing source and target section headings by position. No LLM calls required — a pure structural comparison.

npx translate headingmap -s <source-path> -t <target-path> [options]

Options:

What it does:

1. Parses both source and target files to extract section headings

2. Matches sections by position (first source section → first target section)

3. Builds a heading-map mapping source headings → target headings

4. Injects the heading-map into the target file’s YAML frontmatter

Example:

# Generate heading-maps for all files
npx translate headingmap -s ~/repos/lecture-python-intro -t ~/repos/lecture-python-intro.zh-cn

# Single file, preview only
npx translate headingmap -s ~/source -t ~/target -f intro.md --dry-run

# Exclude specific files
npx translate headingmap -s ~/source -t ~/target --exclude status.md --exclude about.md