Preface

The core design philosophy of DeepSeek Harness (DSH) is “everything is a plugin.” In the scenario of local PDF processing, manual intervention or reliance on expensive SaaS services is usually required. The dsh-pdf-translate plugin uses DeepSeek or any OpenAI-compatible API to perform full-text translation of text-based PDFs locally, outputting editable PDFs that preserve layout, font styles, images, and links.

Core Capabilities

The plugin resolves the tension between “translation” and “layout preservation.” Key capabilities include:

  • Input/Output: Supports text-based PDFs (with a text layer); outputs editable PDFs whose text can be selected and copied.
  • Layout preservation: Preserves paragraph regions, font styles, images, and links.
  • Source-text handling: Source text is truly removed through redaction, rather than simply covered by white blocks.
  • Translation control: Code blocks are preserved as-is; paragraph-level translation is supported, with style support (font size/color/alignment).
  • Single-task limit: A single task translates up to 50 pages; anything beyond must be split into multiple page-range tasks.
  • Termbase and caching: Supports importing JSON/TXT termbases to lock proper nouns; checkpoint/resume is implemented using paragraph hashes.

Installation and Activation

Install the plugin:

dsh plugin --profile desktop add dsh-pdf-translate

After installation, restart DSH Desktop. In the “Plugins” section of the settings page, find the “PDF Translation” card, enter the API key, and save. The API key is protected by role('secret') and is never written to session logs.

Usage

The plugin provides both tool invocation and command-line modes.

Agent Tool Invocation

The agent can invoke the translate_pdf tool:
* input: Absolute path of the input PDF.
* outputDir: Output directory.
* pageStart / pageEnd: Page range (1-based); full document by default; up to 50 pages per task.
* langPair: Language pair, such as en→zh.
* termbase: Path to the termbase file (JSON/TXT).

Command-line Usage

node scripts/translate-cli.mjs <input.pdf> <outputDir> 1 20 en→zh

The output directory will generate <bookTitle>.<langPair>.pdf and .translate-cache.json (for checkpoint/resume).

Termbase Format

The JSON format supports the locked field (locks a term so it is not translated):

[
  { "src": "API", "dst": "应用程序接口", "locked": false },
  { "src": "GPT", "dst": "GPT", "locked": true }
]

TXT format: each line is source,translation.

Technical Implementation

The plugin is built from TypeScript (Cordis) and Python (PyMuPDF).

  • Architecture: The TS layer is responsible for orchestration and API calls; the Python worker is responsible for low-level PDF operations.
  • Worker startup: It must be started using python -m worker.main, and the working directory must be the repository root.
  • Workflow:
    1. Detection: Detects the PDF text layer; an error is reported if no text layer is present.
    2. Extraction: Identifies paragraphs (column detection + line merging + list-item rules) and generates text blocks with IDs.
    3. Reconstruction: Two-stage reconstruction. First, all source text is removed via redaction; then translated text boxes are inserted based on geometric anchors.

Known Limitations

  • Text-based PDFs only: Scanned versions (requiring OCR) are out of scope for v1.
  • Loss of layout details: Underline styles may be lost; densely packed table rows may be merged.
  • Interaction interference: Link annotations that intersect redaction regions are removed; excessively long single-line translations may overflow the page.
  • Complex layouts: Layout handling is limited for overlapping text boxes or rotated text.

Resources