Translate

Workflow

1. Setup

• Load and parse common_glossary.csv (universal terms)
• Load and parse translated/<novel>/glossary.md (novel-specific terms)
• Identify the novel's folder in raw/ and translated/
• Read translated/<novel>/metadata.json to check existing chapter titles and find where translation left off

2. Identify Chapters

• Parse the chapter specifier from arguments:
  • Range (98-102): chapters 98 through 102
  • Single chapter (294): just that chapter
  • Count (15 when last translated chapter is 543): compute range as 544–558
• When interpreting as a count, read metadata.json to find the highest chapter number in chapter_titles, then set the range to (last + 1) through (last + N). Report the computed range to the user before proceeding (e.g., "Last translated chapter is 543. Translating chapters 544–558.")
• Locate matching raw files in raw/<novel>/ by chapter number prefix (format: NNN_[title].txt)
• If a chapter is already translated (file exists in translated/<novel>/), warn the user and skip unless they confirm overwrite

3. Translate Each Chapter

Process chapters strictly one at a time. Do NOT read ahead to the next raw file until the current chapter is fully written AND its glossary updates are appended. Sequential context is what keeps voice and terminology consistent across hundreds of chapters — batching or interleaving breaks it.

For each chapter, complete this full loop before touching the next one:

1. Read the raw Chinese text from raw/<novel>/NNN_[title].txt
2. Translate the full chapter following all rules in CLAUDE.md (glossary lookup, tone, measurements, currency, naming, formatting, inline marker handling). CLAUDE.md is the single source of truth on translation rules — do not improvise or restate rules covered there.
3. Write the translation to translated/<novel>/chapterN.txt (prose only, no title in the file body). Use --- on its own line as a scene break between distinct scenes (location changes, time jumps, POV shifts). Do not overuse — only where the original clearly marks a scene transition.
4. Update glossary immediately: Append any new novel-specific terms to translated/<novel>/glossary.md under the correct category heading. New terms must be available before translating the next chapter.

   | 新术语 | New Term | Optional description |
   

   If a category section doesn't exist yet, create a new ## Category section with the table header. Universal terms shared across novels go in common_glossary.csv instead.
5. Next: only now read the next chapter's raw file.

While translating, extract a natural English chapter title from the Chinese title or content for use in metadata.json (updated in step 4 below).

4. metadata.json

metadata.json updates can be per-chapter or batched at the end of the session — this is a title registry and does not affect translation quality. Add each chapter number and its English title to chapter_titles. Glossary updates, unlike metadata, are strictly per-chapter (see step 3.4 above) and must never be batched.

5. Wrap-up

After all chapters are complete:

1. Run python scripts/generate_index.py to refresh translated/index.json.
2. Stage and commit the new translations. Follow the existing commit-message style: translated chapters N-M of <Novel Name>. Keep the commit scoped to this session's novel unless there is clearly unrelated in-progress work that the user wants bundled — if in doubt, ask before bundling.
3. Push to origin main.
4. Run scripts/deploy.sh to rsync files to the VPS. This is what makes translations live on the reader at novels.homelab-remote.stream — Git push alone is just backup/version control. Do NOT skip the deploy step.
5. Briefly confirm to the user the chapter range that was translated and note any new glossary terms added or issues flagged. Do NOT summarize plot, events, or character developments — the user reads these novels and wants to avoid spoilers.

Workflow Rules

These govern workflow only — translation rules live in CLAUDE.md.

• NEVER read the next chapter's raw file before the current chapter is fully written AND its glossary entries are appended — one chapter at a time, no interleaving
• ALWAYS save the chapter immediately after translating (don't batch saves — a crash loses everything)
• ALWAYS update the novel glossary after each chapter that introduces new terms — needed for consistency in subsequent chapters
• metadata.json can be batched at the end of the session — it doesn't affect translation quality
• If a raw chapter file is missing, report it and continue with the next chapter
• Match the existing chapter numbering in metadata.json (don't create gaps)