English | 中文

ContextWeave

Context-aware document translation / 语境感知文档翻译

ContextWeave (语络译) is a fully automatic desktop translation app for long novels, books, PDFs, scanned documents, manga, and subtitles. It aims to preserve source formatting while keeping terminology and translation style consistent across the whole work.

Advanced documentation covers glossary memory, previous-context injection, format preservation, CLI automation, and advanced use cases.

Who ContextWeave Is For

• Novel, web novel, and light novel translation
• Long books and documents that need consistent naming and terminology
• Scanned books, PDFs, and manga that need OCR before translation
• People who want a desktop workflow instead of managing prompts by hand

Why ContextWeave

• Builds a glossary from your source material
• Carries context forward across chapters and pages, with useful summaries injected alongside glossary context
• Preserves original formatting for text-native files
• Handles text, EPUB, PDF, scanned pages, manga, and subtitles in one app

Install

Current desktop builds are unsigned, so the first launch may show an OS security warning.

macOS

• Download the latest .dmg
• Open it and drag ContextWeave.app into Applications
• Launch ContextWeave.app from Applications
• If macOS blocks it because the developer cannot be verified, go to System Settings -> Privacy & Security
• In the Security section, click Open Anyway for ContextWeave.app, then confirm Open

Windows

• Download the latest .zip
• Unzip it anywhere
• Run ContextWeave.exe
• If Windows SmartScreen warns that the app is unrecognized, click More info -> Run anyway

Translation

1. Create a project

Pick a project name, target language, and workflow profile.

2. Open the project work page

Import files in reading order so terminology and context stay consistent across the whole book, then click Translate and Export to start. Double-click a file if you want to inspect each step manually or retouch images.

3. Optional: import existing term translations

Open Terms, then use Import Terms if you already have a terminology list you want ContextWeave to reuse. A simple JSON object like {"original": "translated"} is enough.

Demo EPUBs

This sample EPUB was generated with Translate and Export directly from the French Project Gutenberg EPUB for The Count of Monte Cristo, Tome I, using DeepSeek.

Quality can be dramatically better with Gemini or GPT. GPT-5.6 Luna is the recommended OpenAI starting point when cost matters.

• The Count of Monte Cristo.epub - English output. Cost: under $2.5.

CLI

ContextWeave also includes a small CLI for config-driven one-shot translation and basic book management. From a source checkout, use uv run contextweave-cli; from an installed package, use contextweave-cli.

contextweave-cli config path
contextweave-cli config init
contextweave-cli config validate

contextweave-cli run ./book.epub --output ./translated/book.epub
contextweave-cli run ./chapter.txt --output ./translated/chapter.txt --json
contextweave-cli run ./episode.srt --output ./translated/episode.srt --no-polish
contextweave-cli galgame inspect ./extracted-game --json
contextweave-cli galgame skill --output ./contextweave-galgame-translation
contextweave-cli run ./extracted-game --type galgame --output ./translated-patch --preserve-structure --json

contextweave-cli books list
contextweave-cli books show BOOK_ID
contextweave-cli books delete BOOK_ID --yes

The CLI resolves config from --config, then CONTEXTWEAVE_CONFIG, then the nearest contextweave.yaml/.contextweave.yaml walking upward, then the platform default shown by contextweave-cli config path. The config mirrors the setup UI: connections define provider endpoints and workflow_profiles route each translation step. Prefer api_key_env so API keys stay in environment variables instead of config files or task snapshots. Use --no-polish when a one-shot run should skip the polish pass, which can be useful for timing-sensitive subtitle output. Use --preserve-structure for patchable galgame/script exports.

For unsupported game engines, convert extracted script text into a supported intermediate format such as ParaTranz JSON or Translator++ .trans, then import that file or folder as --type galgame. contextweave-cli galgame skill writes a Codex/OpenAI-style skill file with this workflow for external extractor agents.

A commented starting point is available at docs/examples/contextweave-cli.yaml.

What To Know Before Using ContextWeave

• The recommended OpenAI profile uses GPT-5.6 Luna for every text-generation and image-understanding step. DeepSeek + Gemini is also supported, but I do not recommend going below DeepSeek-class models.
• Image editing is expensive, and hallucinations are still common. For image reembedding, the recommended OpenAI profile uses the specialized GPT Image 2 model instead of Luna.
• OCR does not preserve original layout for PDFs and scanned books. It rebuilds from content instead. Manga is the exception.
• Import in reading order if you want the glossary and context to build correctly.
• Samples are still limited because testing across formats is expensive. Bug reports are very welcome.

Supported Formats