ContextWeave

Advanced Usage and Feature Guide

A practical guide to ContextWeave's long-document translation features, glossary memory, previous-context injection, format preservation guarantees, OCR workflows, manga translation, CLI automation, troubleshooting, and cost-aware model routing.

English

Feature Introduction

ContextWeave is designed around a project-level translation pipeline. It does not ask users to manually maintain long prompts. Instead, it extracts source text, builds a glossary, summarizes context, translates in batches, optionally polishes the result, and exports the final file.

Project Workflow

Import documents in reading order, choose a target language and workflow profile, then run the translation pipeline from the UI or CLI. Reading order matters because glossary evidence and context are accumulated from earlier content to later content.

Glossary Extraction

ContextWeave scans chunks for names, organizations, places, skills, items, settings, and other terms that need stable translation. Additional extraction passes controlled by max_gleaning can recover terms missed by the first pass.

Term Summary

Character and organization terms receive compact memory summaries built from their source occurrences. These summaries preserve identity, relationships, aliases, and translation-relevant facts without sending every raw occurrence to later translation calls.

Previous-Context Injection

Before translating a batch, ContextWeave can summarize earlier chunks in the same document and inject the most recent summaries within a prompt budget. This helps resolve omitted subjects, pronouns, who is speaking or being addressed, and immediate scene continuity.

Format Preservation

Text-native inputs keep Markdown, line structure, and EPUB inline markers. OCR-based PDFs and scanned books rebuild output from recognized content, while manga uses a specialized image workflow.

Polish and Review

Translation can be followed by a polish step that improves target language readability without changing facts, terms, point of view, or the order in which information is revealed. Term review and quality review help catch glossary issues before they propagate.

Glossary Memory

Term and Context Lifecycle

ContextWeave separates term discovery, term translation, term memory, and local scene context. This keeps prompts compact while still giving the translator the facts most likely to matter for the current batch.

Stage What ContextWeave Does Why It Matters
Extraction Records the term name, type, description, occurrence position, and the source chunk each occurrence came from. Stable translations need evidence. Position-linked evidence lets ContextWeave use only information available before the current point in the book.
Additional Extraction Runs follow-up extraction passes controlled by max_gleaning to find additional candidate terms. Names and setting words are often missed on the first pass. More passes improve recall but increase cost.
Glossary Translation Generates target-language term translations from source evidence and optional imported glossary entries. Glossary mistakes propagate widely, so use stronger models or manual review for important names and terminology.
Term Summary Builds compact memory summaries for character and organization terms from earlier source occurrences. The translator can see relationships, aliases, and identity facts without sending every raw occurrence again.
Term Matching Before each translation batch, ContextWeave selects glossary terms that appear in or are directly relevant to the current source text. The model sees the names and term notes needed for the current passage, without loading unrelated glossary entries from the whole book.
Term Review Users confirm or fix term translations, types, aliases, and important notes on the Terms page or from automated review results. Reviewing terms before body translation reduces cascading mistakes, especially for aliases, titles, factions, and invented words.

Local Context

Previous-Context Injection in Practice

Previous-context injection has a narrow purpose: helping the model understand immediate continuity. It must not override, translate, or expand the current source text.

What Gets Injected

ContextWeave summarizes the most recent preceding chunks in the source language and passes those summaries as local context. The summary is short, factual, and meant to describe what just happened, not to become translated output.

Issues It Helps With

It is most useful for omitted subjects or objects, pronouns, who is speaking, who is being addressed, and immediate scene continuity across chunk boundaries.

What It Must Not Do

It should not invent missing facts, rewrite the current paragraph, add explanations, pull in future revelations, or translate content that is only present in the summary.

Budget Controls

dynamic_context_enabled turns this feature on or off. dynamic_context_max_prompt_tokens reserves prompt space for recent summaries, so raising it improves continuity at the cost of fewer tokens for other context.

When to Raise It

Increase the budget for dialogue-heavy novels, dense pronoun usage, scene cuts that continue across chunks, or languages where subjects are frequently omitted.

When to Lower It

Lower or disable it for short standalone documents, highly structured technical text, subtitle lines where timing is more important, or when cost needs to be minimized.

Mechanics

How Context Is Used

ContextWeave combines global glossary memory with short local context. This is the core difference between a one-off prompt and a book-scale translation workflow.

1

Extract Term Evidence

Source chunks are scanned for terms. Each term keeps descriptions tied to chunk positions, occurrence data, votes, and type hints.

2

Build Term Memory

For character and organization terms, ContextWeave builds an ordered memory timeline. When translating a later chapter, ContextWeave can use what was known before that point without pulling in future-only revelations.

3

Match Relevant Terms

Each translation batch receives only terms that appear in or are directly relevant to the current source text. Duplicate normalized terms with the same translation are collapsed to keep prompts smaller.

4

Inject Recent Summaries

ContextWeave can reserve part of the prompt budget for recent prior-chunk summaries. Current source text always takes priority if the summary is irrelevant or conflicts with the batch.

Output Fidelity

Format Preservation Guarantee

ContextWeave treats source formatting as part of the translation contract, but the guarantee is scoped by the input type and by what the parser can extract. The current source text still has priority over contextual summaries or polish steps.

Text-Native Documents

Markdown blocks, paragraph order, line structure, and supported inline markers are preserved when translating text-native inputs such as Markdown, plain text, and EPUB-derived text.

EPUB Inline Markers

EPUB inline markers, including ruby-related markers when enabled, are kept as structural tokens rather than being translated as normal prose.

OCR and Scanned PDFs

OCR workflows preserve recognized content flow, not pixel-perfect page layout. Expect rebuilt EPUB or Markdown-style output instead of an exact visual clone of the original scan or PDF page.

Manga Image Workflows

Manga translation uses a separate image workflow. Text regions are detected, translated, and rendered back into images, so users should inspect sample pages before running a full volume.

Use Cases

Advanced Use Cases

Use case Recommended approach Advanced notes
Long novels and web novels Import all files in reading order, build glossary, translate glossary entries, review key terms, then translate and export. Term memory summaries and previous-context injection are most useful here because names, relationships, and scene continuity span many chunks.
Existing fan glossary or terminology list Open the project Terms page and import JSON before translation. A simple mapping like {"original":"translated"} is enough for basic seeding. Imported terms can override early model guesses and reduce cascading terminology mistakes.
PDFs and scanned books Run OCR first, inspect OCR output where needed, then build glossary and translate. OCR output is content-preserving, not page-layout preserving. Expect EPUB or Markdown-style rebuilt output rather than a perfect PDF clone.
Manga and image-heavy chapters Use the manga workflow for CBZ or image folders. Inspect OCR and translated pages before export if quality matters. Image OCR and text re-embedding are costlier and more sensitive to model quality. Use a strong vision/image model and smaller test runs before translating a full volume.
Subtitles Use one-shot translation through the UI or CLI and consider disabling polish for time-sensitive output. Subtitle files need compact, aligned text. Polish can improve readability, but it can also alter timing-sensitive phrasing.
CLI automation Use contextweave-cli run ./book.epub --output ./translated/book.epub with a project config file. Use api_key_env in config so keys stay in environment variables instead of checked-in files.
Cost-controlled translation Use cheaper models for extraction and summaries, stronger models for glossary translation, main translation, polish, and quality review. Lower max_gleaning, chunk sizes, concurrency, or polish usage when running exploratory test passes.
Large remote batch jobs Use supported batch providers for translation and polish when available. Batch tasks persist request state, poll remote jobs, validate output, and keep enough state to recover failed or interrupted jobs.

Tuning

Configuration Levers

Most users should start with the setup wizard. Advanced users can tune these settings in workflow profiles or CLI config files.

max_gleaning

More extraction follow-up passes can find missed terms, but each pass costs another LLM call per chunk.

max_term_description_length

Caps term descriptions in translation prompts. Lower values save tokens; higher values preserve more nuance.

chunk_size

Controls source chunking. Smaller chunks are cheaper and safer; larger chunks give the model more local text.

max_tokens_per_llm_call

Caps each translation request payload. ContextWeave uses this to group chunks into batches without exceeding the request budget.

dynamic_context_enabled

Enables or disables previous-context injection for text translation batches.

dynamic_context_max_prompt_tokens

Reserves prompt space for recent prior-chunk summaries. Raise it when dialogue continuity is poor; lower it to save tokens.

enable_polish

Runs a second editor-style pass after translation. It improves prose but adds cost and latency.

concurrency

Controls parallel LLM calls. Higher values are faster but can hit provider rate limits or increase cost spikes.

num_of_chunks_per_llm_call

Controls how many chunks can be grouped into one translation request. Keep it modest; values above 10 are unsafe for quality.

max_term_name_length

Rejects term candidates whose names are too long. Lower it if extraction starts treating whole sentences as terms.

strip_epub_ruby

Controls whether EPUB ruby annotations are removed before translation. Keep it enabled when ruby markup hurts prose quality.

ocr_dpi

Controls the image resolution used for OCR. Higher DPI can help small text but increases request size, latency, and cost.

strip_llm_artifacts

Removes common OCR model artifacts such as tokenizer leftovers. Disable only when debugging raw OCR output.

batch_size

Controls remote batch job size for supported providers. Larger batches reduce overhead but make failed retries heavier.

Automation

CLI and Config-Driven Runs

The CLI is useful for repeatable one-shot translation, scripted experiments, and library management. It mirrors the setup UI through YAML workflow profiles.

Common Commands

contextweave-cli config path
contextweave-cli config init
contextweave-cli config validate
contextweave-cli run ./book.epub --output ./translated/book.epub
contextweave-cli run ./episode.srt --output ./translated/episode.srt --no-polish
contextweave-cli books list
contextweave-cli books show BOOK_ID

Config Resolution

ContextWeave checks --config, then CONTEXTWEAVE_CONFIG, then the nearest contextweave.yaml, contextweave.yml, .contextweave.yaml, or .contextweave.yml, then the platform default shown by contextweave-cli config path.

See the commented example config at docs/examples/contextweave-cli.yaml.

Secrets

Prefer api_key_env in YAML. This keeps provider keys in environment variables instead of config files, book snapshots, or repository history.

One-Shot Limits

In the current v1 CLI flow, contextweave-cli run imports one input document and expects exactly one imported document. Existing --book-id runs cannot be combined with --config.

Quality Control

Troubleshooting and Review Checklist

Most translation quality problems come from one of four sources: source extraction, glossary quality, context budget, or model choice. Fix the earliest broken step instead of patching the final export.

Symptom Likely Cause Recommended Action
Pronouns or speakers are wrong Local context budget is too small, chunks are too isolated, or the model is weak at discourse tracking. Raise dynamic_context_max_prompt_tokens, use a stronger translator model, and test one dialogue-heavy chapter.
OCR text contains broken lines or garbage Input scan quality, DPI, or OCR model quality is insufficient. Inspect OCR before translation, increase ocr_dpi for small text, or switch to a stronger vision model.
PDF export does not match the original page OCR PDF/scanned-book workflow rebuilds content flow, not exact page layout. Use EPUB, Markdown, or text output expectations. Use manga/image workflow only for image-page translation.
Polish changes meaning or timing The polish model is over-editing, or the file is timing-sensitive like subtitles. Disable polish with --no-polish, or route the polish step to a model that follows the built-in prompt more reliably and over-edits less.
Costs climb too quickly Too many additional extraction passes, large chunks, strong models on every step, high concurrency, OCR, or image redrawing. Run smaller samples, use cheaper extraction/summarization models, lower max_gleaning, and reserve strong models for final prose.