epub_bilingual_translator/archive/v0.10/doc/OPERATION_MANUAL.md

Operation Manual & Change Log

Core Principles

1. Modularity: The system is divided into three distinct phases (Preprocessing, Translation, Assembly) with clear boundaries.
2. Immutability: book_structure.json is generated once during preprocessing and should not be modified by subsequent steps.
3. Source of Truth: manifest.json is the single source of truth for translations.
4. Idempotency: Translation steps can be retried without side effects (existing translations are preserved).

Directory Structure

• pipeline/: Executable scripts for each stage.
  • 01_preprocess.py: Clean EPUB, generate structure, extract text.
  • 02_translate.py: Translate text in manifest.
  • 03_assemble.py: Apply translations and build final EPUB.
• src/: Core logic modules.
  • preprocessing/: Cleaning, extraction, profiling.
  • translation/: LLM integration, manifest management.
  • assembly/: Backfilling, EPUB building.
  • common/: Shared data models and utils.
• work/: Working directory for intermediate files (ignored by git).

Pipeline Usage

Step 1: Preprocessing

python pipeline/01_preprocess.py inputs/my_book.epub

Generates work/my_book/book_structure.json and manifest.json.

Step 2: Translation

python pipeline/02_translate.py --input-epub inputs/my_book.epub

Translates entries in manifest.json. ensuring .env has OPENAI_API_KEY.

Step 3: Assembly

python pipeline/03_assemble.py inputs/my_book.epub --mode bilingual

Generates output/my_book_bilingual.epub.

Configuration

System settings are managed via config/config.yaml and environment variables.

config/config.yaml

Control LLM parameters and translation behavior:

llm:
  model: "gpt-3.5-turbo"           # LLM Model Name
  base_url: "https://api.openai.com/v1" 
  timeout: 60
  requests_per_minute: 60          # Rate limiting
  concurrent_requests: 5           # Parallel chunks

translation:
  chunk_size: 4000                 # Characters per chunk

Environment Variables (.env)

Security-sensitive credentials must be set here:

OPENAI_API_KEY=sk-...              # Required
OPENAI_BASE_URL=...                # Optional override for config

Known Issues & Troubleshooting

Missing Placeholders Warning

During assembly, you may see logs like: WARNING - Restoration warning: missing placeholders {'1'} This indicates that the LLM translation missed a placeholder tag (e.g. φ1φ). The system attempts to recover, but this warning is logged for review. These are usually minor and do not prevent EPUB generation.

Change Log

[2026-01-28] Bug Fixes

• Fix Cover Image: Resolved issue where book cover execution was missing in the final EPUB. Added cover_image_id tracking in BookStructure and restored proper OPF metadata in BilingualBuilder.

[2026-01-27] Externalized Configuration

• Config: Added config/config.yaml for tuning parameters (LLM model, RPM, Chunk Size).
• Logic: pipeline/02_translate.py now loads settings from config.yaml.
• Dependency: Added PyYAML to requirements.txt.

[2026-01-27] Architecture Refactoring

• Restructured: Moved source files into src/preprocessing, src/translation, src/assembly, src/common.
• Pipeline: Created individual pipeline scripts in pipeline/.
• Refactor: Renamed fine_grained_extractor to text_extractor, translator to translator_engine, etc.
• Logic: Enforced 100% text coverage check in format_extractor.py (removed 95% threshold).
• Docs: Created this Operation Manual.