pdf-translate

name pdf-translate description Translate English PDF documents (especially academic papers) into Chinese using PDFMathTranslate-next (pdf2zh), producing a monolingual Chinese PDF and a bilingual side-by-side PDF with formulas, figures, and layout preserved. Automatically installs the pdf2zh_next environment via uv and reuses the model/API the user already configured in Codex or Claude Code (any OpenAI-compatible gateway), falling back to the free SiliconFlow service when no key is present. Use this skill whenever the user wants to translate a PDF to Chinese (or another language), translate a paper/论文, produce a bilingual PDF, or mentions pdf2zh / PDFMathTranslate — even if they don't name the tool explicitly. Proactively invoke this skill (do not translate manually) whenever a PDF translation task appears. PDF Translate (English → Chinese) This skill translates PDF documents using PDFMathTranslate-next ( pdf2zh_next ), the BabelDOC-based translator that preserves formulas, charts, table of contents, and page layout. It produces two files per input: *-mono.pdf — monolingual translated PDF (Chinese only) *-dual.pdf — bilingual PDF (original + translation, side by side or alternating) Why this skill exists Translating an academic PDF well requires preserving math, figures, and layout — something plain LLM translation can't do. pdf2zh_next handles that, but it has a non-trivial install (Python 3.12, model assets) and many engine options. This skill automates the environment setup and picks a translation engine that reuses credentials the user already has, so translation "just works" without manual configuration. Workflow Run the setup script first (installs pdf2zh_next if missing, verifies it), then the translate script (detects the best engine and runs the translation). Both scripts are idempotent. Subsequent runs are fast. Once pdf2zh_next is installed and the model assets are downloaded (after the first successful translation), setup.sh becomes a silent sub-second no-op — it detects the install and the ~/.cache/babeldoc/models cache and returns immediately without spawning a Python import or re-downloading anything. Re-running it on every invocation is cheap and safe; you do not need to track whether setup has happened before. Step 1 — Ensure the environment is ready bash ~/.claude/skills/pdf-translate/scripts/setup.sh This installs pdf2zh_next via uv tool install --python 3.12 pdf2zh-next (the project requires Python ≥3.10,<3.14; 3.12 is the documented recommendation) and confirms it is on PATH. It is fast and safe to re-run. The first real translation downloads layout/translation model assets (DocLayout-YOLO + fonts, ~hundreds of MB) into ~/.cache/babeldoc/ — tell the user the first run is slow because of this one-time download. The setup and translate scripts detect this cache and skip the "slow first run" messaging once the models are present. Step 2 — Translate bash ~/.claude/skills/pdf-translate/scripts/translate.sh "<input.pdf>" [options] The script auto-detects a translation engine: ClaudeCode (default when claude CLI is available) — detects if the user is running from Claude Code by checking for the claude CLI on PATH. Uses the exact model Claude Code is configured to use (resolved via ANTHROPIC_DEFAULT_SONNET_MODEL , etc.). This is the default when working in Claude Code, so the translation uses the same model ecosystem the user is already in. Note: it spawns one claude -p subprocess per text segment, so it is slower than the OpenAI engine. OpenAI-compatible (fallback when API key exists) — used when claude CLI is not found but OPENAI_API_KEY is set. Reuses the model configured for Codex: reads base_url + model from ~/.codex/config.toml and the API key from OPENAI_API_KEY . Fast (HTTP, high concurrency), ideal for full papers. SiliconFlowFree (zero-config fallback) — used when neither claude CLI nor API key is detectable. The project's free GLM-4-9B service; needs no key. Note: file content is forwarded through the project maintainer's server. Override detection with flags: --engine openai|siliconflowfree|claudecode , --model <name> , --base-url <url> , --api-key <key> . Common options: --output <dir> — output directory (default: an output/ folder next to the input PDF) --pages "1-5,8" — translate only some pages --lang-in en --lang-out zh-CN — language codes (defaults: en → zh-CN) --qps N --pool-max-workers N — concurrency tuning (see references/advanced.md ) --no-dual / --no-mono — suppress one of the two outputs Pass any other pdf2zh_next flag through with -- <flag> <value> Step 3 — Report results After the script finishes, it prints the paths of the generated *-mono.pdf and *-dual.pdf . Tell the user where these files are (relative to the input), open/preview them if asked, and note the engine + model that was used. If the user wants different quality or speed, suggest overrides (see references/advanced.md ). Default behavior choices (and how to change them) Source/target language : English → Simplified Chinese ( en → zh-CN ). Override with --lang-in / --lang-out . Full language code list is in references/advanced.md . Engine : ClaudeCode when claude CLI is on PATH (default in Claude Code), else OpenAI-compatible when a key is found, else SiliconFlowFree. Use --engine openai to force the OpenAI engine even from Claude Code. The claudecode engine reuses Claude Code's configured model; the OpenAI engine reuses the model named in ~/.codex/config.toml . Model : for the openai engine, the model from ~/.codex/config.toml ; for claudecode, sonnet (resolved by Claude Code to the user's configured model). Reasoning models (e.g. gpt-5.5 , glm-5.2 ) work but are slower and use more tokens; for large papers consider a lighter chat model via --model . Concurrency : modest defaults ( --qps 10 --pool-max-workers 30 for the OpenAI engine; --qps 4 --pool-max-workers 8 for claudecode since each segment is a subprocess). Increase for faster translation if the gateway allows it. When something goes wrong command not found: pdf2zh_next after install — the uv tool bin dir isn't on PATH. The scripts add ~/.local/bin to PATH themselves, but if the user runs pdf2zh_next directly in their own shell, they need export PATH="$HOME/.local/bin:$PATH" (Linux/macOS). First translation hangs on "loading assets" / downloading — normal one-time model download. Wait it out. 429 / rate-limit errors — lower --qps and --pool-max-workers . Gateway returns errors for the OpenAI engine — the detected base_url may only expose the responses API, not chat-completions. Run with --engine siliconflowfree to bypass, or point --base-url at a chat-completions endpoint. Out-of-memory / very large PDFs — use --pages to translate in chunks, or --max-pages-per-part 50 . For the full option reference, engine configuration details, translating to other languages, glossaries, and offline/air-gapped usage, read references/advanced.md .