List all cached translation books with progress (including temporary caches). The returned id is the book_id used by every other tool. Note: segmenting the same book with different engine / target language / merge settings produces multiple caches (same title, different ids) — duplicate titles are flagged duplicate_title=true; disambiguate by engine/target_lang/merge_length and pick one, since picking the wrong book makes every later read/write land on the wrong cache. keyword fuzzy-filters by title/engine/language (useful when there are many books). persistent=false means a temporary cache (destroyed as soon as the advanced-mode window closes).

Details of one book's cache: engine, target language, merge / alignment rules, progress, and the list of non-aligned (yellow- highlighted) chunk ids.

Lightweight list of every chunk id of one book with status, without full texts (to keep context small); mirrors the left-hand table of the UI. status options: all / untranslated / translated / misaligned (the UI's yellow rows); keyword fuzzy-matches original or translation text. Each item contains: chunk_id (for addressing; never changes; valid only inside this book), ui_row (UI display position, human reference only), status, alignment, block count, character count and a one-line preview. Always address chunks as book_id + chunk_id — never use ui_row, and never carry this book's chunk_id over to another book. The response echoes book_id and title so the caller can verify it is working on the intended book.

Read the full original text of one chunk — identical to what the UI's proofreading panel shows, so the agent sees the same text a human sees. chunk_id is this book's database cache id (never changes; see list_chunks; valid only inside this book — never use it across books). When merged translation is enabled the response includes blocks: the translation's blank-line block count must equal it to be aligned (otherwise the UI highlights the chunk yellow). include_raw=True additionally returns the raw HTML. The response echoes book_id and title — verify it is the intended book.

Export one chunk's original text to a local file and return only metadata — the text itself never enters the conversation (zero content tokens, no truncation risk on huge chunks). Mirrors get_original (same metadata fields, same stripped text as the UI proofreading panel shows) and is the symmetric counterpart of write_chunk_from_file: originals flow cache -> file, translations flow file -> cache, bulk text never passes through the agent.

Typical use: the first pass of a formal translation workflow — export the original to a file, translate against the file, write the result back with write_chunk_from_file. For ad-hoc inspection prefer get_original directly.

File handling: UTF-8 without BOM, LF line endings. Missing parent directories are created automatically (creating a directory destroys nothing; the resolved path is echoed as exported_file). An existing file is NOT overwritten unless overwrite=True — a mistyped path must never silently destroy an existing file (e.g. a finished translation draft). After writing, the file is read back and verified; verify_mismatch appears only if it differs. Relative paths resolve against the server process's working directory, which may differ from the caller's — absolute paths are strongly recommended. chunk_id is this book's database cache id (see list_chunks); the response echoes book_id and title — verify it is the intended book.

Read the full translation and alignment state of one chunk — identical to what the UI's proofreading panel shows. chunk_id is this book's database cache id (never changes; see list_chunks; valid only inside this book — never use it across books). translation is null when the chunk is untranslated. When merged translation is enabled the response carries the alignment verdict (whether translation and original have equal blank-line block counts, i.e. whether the UI highlights the row yellow). The response echoes book_id and title — verify it is the intended book.

Export one chunk's current translation to a local file and return only metadata — the text itself never enters the conversation. Mirrors get_translation (same metadata and alignment fields, same stripped text as the UI proofreading panel shows).

Typical uses:

• Rework a yellow (misaligned) chunk without any bulk text through the agent: export the translation, fix the block count offline (editor or script — deterministic, zero tokens), write it back with write_chunk_from_file.

• Migrate translations after changing engine / target language / merge settings (the plugin then creates a new cache file): export every chunk from the old cache, write them into the new one.

• Hand the current draft to a human reviewer, or archive a book's translations as plain text.

The chunk must already have a translation (status translated); exporting an untranslated chunk is an error. File handling is the same as get_original_to_file: UTF-8 without BOM, LF; missing parent directories are created automatically; an existing file is not overwritten unless overwrite=True; the file is read back and verified (verify_mismatch appears only on mismatch). Relative paths resolve against the server process's working directory — absolute paths recommended. chunk_id is this book's database cache id (see list_chunks); the response echoes book_id and title — verify it is the intended book.

Write the full translation of one chunk (stripped before writing, matching plugin behavior; engine name and target language are recorded). chunk_id is this book's database cache id (never changes; see list_chunks; valid only inside this book). Right after writing, the tool replicates the UI alignment check and returns the aligned state — mismatched block counts come with a warning (the chunk will be highlighted yellow in the UI), and the stored text is read back and verified (verify_mismatch appears only if it differs). With overwrite=False an existing translation is skipped. The response echoes book_id and title: writing is irreversible, verify it is the intended book first. For very large translations prefer write_chunk_from_file (file-based: zero content tokens, no truncation risk).

Write one chunk's translation from a local text (.txt) file — the recommended path for large translations. The agent passes only a file path, never the content: zero token cost for the text and no risk of truncation or mutation in transit. Whatever is in the file is exactly what gets stored (the local file is the source of truth, the cache is the mirror).

File handling: the file must exist and be valid UTF-8. A UTF-8 BOM is stripped automatically; leading/trailing whitespace is stripped exactly like write_chunk; and — with the default LF-based alignment separator — CRLF/CR line endings are normalized to LF (text stored with CRLF could never match an LF separator and every multi-block chunk would be flagged misaligned). If the configured separator itself contains CR, line endings are preserved verbatim instead. Empty or whitespace-only files are rejected. Relative paths resolve against the server process's working directory, which may differ from the caller's — absolute paths are strongly recommended (the resolved path is echoed back as source_file so mismatches are visible).

The response has the same structure as write_chunk (written / characters / alignment / progress / warning), plus source_file. After writing, the stored text is read back and compared inside this tool: if verify_mismatch is present (true), the stored text differs from the file — do not trust the write; inspect with get_translation and retry. overwrite=False skips chunks that already have a translation. chunk_id is this book's database cache id (see list_chunks); the response echoes book_id and title — verify it is the intended book.

Clear the translations of the given chunks (for rework); originals and all other fields are untouched. chunk_ids is a list of this book's database cache ids (never change; see list_chunks; valid only inside this book). A chunk that went wrong only needs its own redo — other chunks are not affected. The response echoes book_id and title; verify them.