CatScribe Docs

#Common Issues & Fixes

Use this page when a file is rejected or the output looks wrong after translation, review, or export. For engine, install, and download errors, see Troubleshooting.

#File Rejected At Upload

Symptoms:

  • The file picker refuses your file, or upload fails immediately with a format or size message.

Causes and fixes:

Message / behavior Cause Fix
"This file type is not supported for file translation." File Translation accepts PDF, DOCX, and EPUB only Convert the file, or use the right screen (subtitles go to Subtitle Translation)
Document upload fails at 50 MB Hard limit: "Documents up to 50MB" Split the document (for example, one EPUB/PDF per part)
"Could not convert .doc to .docx automatically. Install LibreOffice (soffice) and try again." Legacy .doc files are converted via LibreOffice, which is not installed Install LibreOffice, or save the file as .docx yourself
"Only video files (.mp4, .mkv, .avi, .mov, .webm) or subtitle files (.srt, .vtt) are supported." Unsupported file in Subtitle Translation Convert the subtitle to SRT/VTT or the video to a supported container
"Subtitle file is too large (max 5MB)." / "Video file is too large (max 500MB)." Hard subtitle/video caps Split the subtitle file; use a smaller or re-encoded video
"Text exceeds the maximum length of 8,192 characters." Quick Translate source cap Use File Translation for anything longer than a snippet

These limits are enforced, not advisory — the same summary appears in Settings under "Upload limits".

#A Chunk Failed

Symptoms:

  • A chunk shows status "Failed", or the CAT editor banner says: "This chunk failed. Type your translation below and Save, or use Re-run chunk with a different engine."

What to try:

  1. Failed chunks are retried automatically up to 3 times during the job; check whether it already recovered.
  2. On the job in the Translations screen, click "Retry Failed" (or "Retry All").
  3. In the CAT editor, use the "Chunk Override" panel and "Re-run chunk" with a different engine.
  4. Or simply type the translation yourself and "Save" — a failed chunk does not block the rest of the job.
  5. If every chunk failed, the engine was down: see Troubleshooting.

#Job Seems Stuck Or Paused

Symptoms:

  • Progress stops advancing, or the job sits in "Paused" / "Pending".

What to try:

  1. Long "Preparing" phases are normal for big books: "Extracting EPUB contents and building translation parts. Large books may take a few minutes."
  2. Paused jobs resume automatically once the engine is idle and ready, or manually via "Resume" on the Translations screen.
  3. If the machine slept mid-job, enable "Prevent system sleep while translating" in Settings for future runs.
  4. If a brief error storm occurred, the app backs off on its own: "Local engine paused briefly after errors — retries resume automatically."
  5. Still wedged after several minutes? Quit fully (Tray → Quit Application), relaunch, and let auto-resume pick the job up.

#Glossary Terms Not Applied

Symptoms:

  • Names or terms in the output ignore your glossary.

What to try:

  1. Confirm groups were attached to the job. The empty state is explicit: "No groups selected — glossary will not be used."
  2. Check the language pair. The app's own hint: "No glossary groups for this language pair. Create groups in the Glossary tab, or switch Source/Target languages to match an existing glossary group (e.g. if your glossary is en → pt but you selected en → pt-BR here)."
  3. Enable "Verify Glossary Terms" so the pipeline double-checks terms after translation.
  4. Review the "QA Flags" panel in the CAT editor — misses appear as "Glossary term "X" not translated as one of: …".
  5. Matching is case-insensitive; you do not need to add capitalization variants.

#Formatting Breaks

Symptoms:

  • Italics, bold text, links, or headings are missing.
  • Raw tags are visible in the final text.
  • The QA Flags panel reports "Tag count mismatch (source: N, target: M). Check that HTML/formatting tags match (e.g. , ,

    )."

What to try:

  1. Open the flagged chunk in the CAT editor and compare Source and Target.
  2. Restore missing opening or closing tags in the translated text, keeping them around the same words as the source.
  3. Export a small sample and inspect the result before re-running anything large.
  4. If the issue repeats across many chunks, check the source file's structure before retranslating.

#Edits Lost On Export

Symptoms:

  • Formatting you applied in the CAT editor does not appear in the exported file.

Cause: by design, EPUB export preserves the original book's formatting and takes only your text. The editor states this in its banner: "EPUB Translation Mode: only text edits are exported. Formatting changes are preserved from the original EPUB." For DOCX/PDF, inline styling (bold/italic) survives but block-level structure changes (new headings, lists) do not.

Fix: make text edits in CatScribe; make structural or heavy styling changes in a document editor after export. Details in Editing Without Breaking Formatting.

#Merged Words

Symptoms:

  • Words appear joined together, such as umabertura.
  • Spaces disappear near line breaks or punctuation.

What to try:

  1. Correct the affected chunk manually in the CAT editor.
  2. Check nearby chunks for the same extraction issue.
  3. If the source is a PDF, this is usually a text-extraction artifact — try the "High Fidelity (preserves layout and tables)" PDF mode, or a cleaner source format (EPUB/DOCX) if you have one.
  4. Do not use glossary entries to hide extraction problems — they mask, not fix.

#PDF Output Quirks

Symptoms:

  • Bold Chinese/Japanese/Korean text renders as regular weight.
  • You cannot find a PDF option in "Output Format".
  • Multi-column layout came out as one column.

Causes and fixes:

  1. CJK bold is a known limitation — bold CJK text degrades to regular weight in generated PDFs (an installer-size tradeoff); CJK italic is unavailable too.
  2. PDF output exists only via "Same as input" on a PDF source; other inputs export to TXT, DOCX, or EPUB.
  3. Column handling depends on the detected document profile and the "PDF Translation Mode" — try "High Fidelity (preserves layout and tables)".

#Subtitle Readability Warnings

Symptoms:

  • The CPS badge turns amber or red; the quality report says "Reading speed is above subtitle comfort range."
  • Auto QC suggests "Split long line to improve readability timing."

Cause: CatScribe validates subtitles against 25 characters-per-second maximum and 42 characters per line (the badge turns amber at CPS ≥ 20, red above 25). It also flags timing overlaps ("Timing overlap with next subtitle.") and negative durations.

What to try:

  1. Shorten the translation — subtitle language can be more compact than document prose.
  2. Split long cues, or extend timing with the per-cue "Edit timing" fields (Start/End in MM:SS.d format).
  3. Use "Auto QC Suggestions" on the chunk for concrete proposals.

#Subtitle Tag Inconsistencies

Symptoms:

  • Italics continue longer than expected, or players show raw tags.
  • A line has an opening tag without a closing tag.

What to try:

  1. Compare the translated cue with the source — CatScribe preserves <i>, <b>, <u> inline tags, so a mismatch is visible side by side.
  2. Restore missing tags around the intended words.
  3. Test the exported SRT/VTT in a real video player.
  4. Review neighboring cues when a sentence spans multiple entries.

#Inconsistent Names Or Terms

Symptoms:

  • A character name changes spelling; a title or technical term drifts across chapters.

What to try:

  1. Add the preferred term to a glossary group and attach it to the job (Glossaries).
  2. Re-run only affected chunks (Chunk Overrides).
  3. Follow the strategy in Maintaining Consistency.

#Quality Score Looks Wrong Or Missing

Symptoms:

  • BLEU shows "N/A (reference required)"; COMET shows "Unavailable"; a chunk shows "⚠ Short segment".

Causes:

  1. BLEU needs a human reference translation in the target language — it is never computed from source vs. translation. Paste a reference to calculate it.
  2. COMET is an optional ~1–2 GB install ("Enable COMET quality scoring" in Settings); without it only heuristic scores appear.
  3. "Short segments have too little context, so this quality estimate is less reliable." — trust your own review over the number for tiny chunks.