epub-translator 0.1.1__tar.gz → 0.1.4__tar.gz

{epub_translator-0.1.1 → epub_translator-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: epub-translator
-Version: 0.1.1
+Version: 0.1.4
 Summary: Translate the epub book using LLM. The translated book will retain the original text and list the translated text side by side with the original text.
 License: MIT
 Keywords: epub,llm,translation,translator
@@ -78,8 +78,7 @@ The easiest way to use EPUB Translator is through OOMOL Studio with a visual int
 ### Using Python API
 
 ```python
-from pathlib import Path
-from epub_translator import LLM, translate, language
+from epub_translator import LLM, translate, language, SubmitKind
 
 # Initialize LLM with your API credentials
 llm = LLM(
@@ -91,10 +90,11 @@ llm = LLM(
 
 # Translate EPUB file using language constants
 translate(
-    llm=llm,
-    source_path=Path("source.epub"),
-    target_path=Path("translated.epub"),
+    source_path="source.epub",
+    target_path="translated.epub",
     target_language=language.ENGLISH,
+    submit=SubmitKind.APPEND_BLOCK,
+    llm=llm,
 )
 ```
 
@@ -113,10 +113,11 @@ with tqdm(total=100, desc="Translating", unit="%") as pbar:
         last_progress = progress
 
     translate(
-        llm=llm,
-        source_path=Path("source.epub"),
-        target_path=Path("translated.epub"),
+        source_path="source.epub",
+        target_path="translated.epub",
         target_language="English",
+        submit=SubmitKind.APPEND_BLOCK,
+        llm=llm,
         on_progress=on_progress,
     )
 ```
@@ -149,14 +150,63 @@ Translate an EPUB file:
 
 ```python
 translate(
-    llm: LLM,                          # LLM instance
-    source_path: Path,                 # Source EPUB file path
-    target_path: Path,                 # Output EPUB file path
+    source_path: PathLike | str,       # Source EPUB file path
+    target_path: PathLike | str,       # Output EPUB file path
     target_language: str,              # Target language (e.g., "English", "Chinese")
+    submit: SubmitKind,                # How to insert translations (REPLACE, APPEND_TEXT, or APPEND_BLOCK)
     user_prompt: str | None = None,    # Custom translation instructions
     max_retries: int = 5,              # Maximum retries for failed translations
     max_group_tokens: int = 1200,      # Maximum tokens per translation group
+    llm: LLM | None = None,            # Single LLM instance for both translation and filling
+    translation_llm: LLM | None = None,  # LLM instance for translation (overrides llm)
+    fill_llm: LLM | None = None,       # LLM instance for XML filling (overrides llm)
     on_progress: Callable[[float], None] | None = None,  # Progress callback (0.0-1.0)
+    on_fill_failed: Callable[[FillFailedEvent], None] | None = None,  # Error callback
+)
+```
+
+**Note**: Either `llm` or both `translation_llm` and `fill_llm` must be provided. Using separate LLMs allows for task-specific optimization.
+
+#### Submit Modes
+
+The `submit` parameter controls how translated content is inserted into the document. Use `SubmitKind` enum to specify the insertion mode:
+
+```python
+from epub_translator import SubmitKind
+
+# Three available modes:
+# - SubmitKind.REPLACE: Replace original content with translation (single-language output)
+# - SubmitKind.APPEND_TEXT: Append translation as inline text (bilingual output)
+# - SubmitKind.APPEND_BLOCK: Append translation as block elements (bilingual output, recommended)
+```
+
+**Mode Comparison:**
+
+- **`SubmitKind.REPLACE`**: Creates a single-language translation by replacing original text with translated content. Useful for creating books in the target language only.
+
+- **`SubmitKind.APPEND_TEXT`**: Appends translations as inline text immediately after the original content. Both languages appear in the same paragraph, creating a continuous reading flow.
+
+- **`SubmitKind.APPEND_BLOCK`** (Recommended): Appends translations as separate block elements (paragraphs) after the original. This creates clear visual separation between languages, making it ideal for side-by-side bilingual reading.
+
+**Example:**
+
+```python
+# For bilingual books (recommended)
+translate(
+    source_path="source.epub",
+    target_path="translated.epub",
+    target_language=language.ENGLISH,
+    submit=SubmitKind.APPEND_BLOCK,
+    llm=llm,
+)
+
+# For single-language translation
+translate(
+    source_path="source.epub",
+    target_path="translated.epub",
+    target_language=language.ENGLISH,
+    submit=SubmitKind.REPLACE,
+    llm=llm,
 )
 ```
 
@@ -169,18 +219,80 @@ from epub_translator import language
 
 # Usage example:
 translate(
-    llm=llm,
-    source_path=Path("source.epub"),
-    target_path=Path("translated.epub"),
+    source_path="source.epub",
+    target_path="translated.epub",
     target_language=language.ENGLISH,
+    submit=SubmitKind.APPEND_BLOCK,
+    llm=llm,
 )
 
 # You can also use custom language strings:
 translate(
-    llm=llm,
-    source_path=Path("source.epub"),
-    target_path=Path("translated.epub"),
+    source_path="source.epub",
+    target_path="translated.epub",
     target_language="Icelandic",  # For languages not in the constants
+    submit=SubmitKind.APPEND_BLOCK,
+    llm=llm,
+)
+```
+
+### Error Handling with `on_fill_failed`
+
+Monitor and handle translation errors using the `on_fill_failed` callback:
+
+```python
+from epub_translator import FillFailedEvent
+
+def handle_fill_error(event: FillFailedEvent):
+    print(f"Translation error (attempt {event.retried_count}):")
+    print(f"  {event.error_message}")
+    if event.over_maximum_retries:
+        print("  Maximum retries exceeded!")
+
+translate(
+    source_path="source.epub",
+    target_path="translated.epub",
+    target_language=language.ENGLISH,
+    submit=SubmitKind.APPEND_BLOCK,
+    llm=llm,
+    on_fill_failed=handle_fill_error,
+)
+```
+
+The `FillFailedEvent` contains:
+- `error_message: str` - Description of the error
+- `retried_count: int` - Current retry attempt number
+- `over_maximum_retries: bool` - Whether max retries has been exceeded
+
+### Dual-LLM Architecture
+
+Use separate LLM instances for translation and XML structure filling with different optimization parameters:
+
+```python
+# Create two LLM instances with different temperatures
+translation_llm = LLM(
+    key="your-api-key",
+    url="https://api.openai.com/v1",
+    model="gpt-4",
+    token_encoding="o200k_base",
+    temperature=0.8,  # Higher temperature for creative translation
+)
+
+fill_llm = LLM(
+    key="your-api-key",
+    url="https://api.openai.com/v1",
+    model="gpt-4",
+    token_encoding="o200k_base",
+    temperature=0.3,  # Lower temperature for structure preservation
+)
+
+translate(
+    source_path="source.epub",
+    target_path="translated.epub",
+    target_language=language.ENGLISH,
+    submit=SubmitKind.APPEND_BLOCK,
+    translation_llm=translation_llm,
+    fill_llm=fill_llm,
 )
 ```
 
@@ -236,10 +348,11 @@ Provide specific translation instructions:
 
 ```python
 translate(
-    llm=llm,
-    source_path=Path("source.epub"),
-    target_path=Path("translated.epub"),
+    source_path="source.epub",
+    target_path="translated.epub",
     target_language="English",
+    submit=SubmitKind.APPEND_BLOCK,
+    llm=llm,
     user_prompt="Use formal language and preserve technical terminology",
 )
 ```

{epub_translator-0.1.1 → epub_translator-0.1.4}/README.md

@@ -45,8 +45,7 @@ The easiest way to use EPUB Translator is through OOMOL Studio with a visual int
 ### Using Python API
 
 ```python
-from pathlib import Path
-from epub_translator import LLM, translate, language
+from epub_translator import LLM, translate, language, SubmitKind
 
 # Initialize LLM with your API credentials
 llm = LLM(
@@ -58,10 +57,11 @@ llm = LLM(
 
 # Translate EPUB file using language constants
 translate(
-    llm=llm,
-    source_path=Path("source.epub"),
-    target_path=Path("translated.epub"),
+    source_path="source.epub",
+    target_path="translated.epub",
     target_language=language.ENGLISH,
+    submit=SubmitKind.APPEND_BLOCK,
+    llm=llm,
 )
 ```
 
@@ -80,10 +80,11 @@ with tqdm(total=100, desc="Translating", unit="%") as pbar:
         last_progress = progress
 
     translate(
-        llm=llm,
-        source_path=Path("source.epub"),
-        target_path=Path("translated.epub"),
+        source_path="source.epub",
+        target_path="translated.epub",
         target_language="English",
+        submit=SubmitKind.APPEND_BLOCK,
+        llm=llm,
         on_progress=on_progress,
     )
 ```
@@ -116,14 +117,63 @@ Translate an EPUB file:
 
 ```python
 translate(
-    llm: LLM,                          # LLM instance
-    source_path: Path,                 # Source EPUB file path
-    target_path: Path,                 # Output EPUB file path
+    source_path: PathLike | str,       # Source EPUB file path
+    target_path: PathLike | str,       # Output EPUB file path
     target_language: str,              # Target language (e.g., "English", "Chinese")
+    submit: SubmitKind,                # How to insert translations (REPLACE, APPEND_TEXT, or APPEND_BLOCK)
     user_prompt: str | None = None,    # Custom translation instructions
     max_retries: int = 5,              # Maximum retries for failed translations
     max_group_tokens: int = 1200,      # Maximum tokens per translation group
+    llm: LLM | None = None,            # Single LLM instance for both translation and filling
+    translation_llm: LLM | None = None,  # LLM instance for translation (overrides llm)
+    fill_llm: LLM | None = None,       # LLM instance for XML filling (overrides llm)
     on_progress: Callable[[float], None] | None = None,  # Progress callback (0.0-1.0)
+    on_fill_failed: Callable[[FillFailedEvent], None] | None = None,  # Error callback
+)
+```
+
+**Note**: Either `llm` or both `translation_llm` and `fill_llm` must be provided. Using separate LLMs allows for task-specific optimization.
+
+#### Submit Modes
+
+The `submit` parameter controls how translated content is inserted into the document. Use `SubmitKind` enum to specify the insertion mode:
+
+```python
+from epub_translator import SubmitKind
+
+# Three available modes:
+# - SubmitKind.REPLACE: Replace original content with translation (single-language output)
+# - SubmitKind.APPEND_TEXT: Append translation as inline text (bilingual output)
+# - SubmitKind.APPEND_BLOCK: Append translation as block elements (bilingual output, recommended)
+```
+
+**Mode Comparison:**
+
+- **`SubmitKind.REPLACE`**: Creates a single-language translation by replacing original text with translated content. Useful for creating books in the target language only.
+
+- **`SubmitKind.APPEND_TEXT`**: Appends translations as inline text immediately after the original content. Both languages appear in the same paragraph, creating a continuous reading flow.
+
+- **`SubmitKind.APPEND_BLOCK`** (Recommended): Appends translations as separate block elements (paragraphs) after the original. This creates clear visual separation between languages, making it ideal for side-by-side bilingual reading.
+
+**Example:**
+
+```python
+# For bilingual books (recommended)
+translate(
+    source_path="source.epub",
+    target_path="translated.epub",
+    target_language=language.ENGLISH,
+    submit=SubmitKind.APPEND_BLOCK,
+    llm=llm,
+)
+
+# For single-language translation
+translate(
+    source_path="source.epub",
+    target_path="translated.epub",
+    target_language=language.ENGLISH,
+    submit=SubmitKind.REPLACE,
+    llm=llm,
 )
 ```
 
@@ -136,18 +186,80 @@ from epub_translator import language
 
 # Usage example:
 translate(
-    llm=llm,
-    source_path=Path("source.epub"),
-    target_path=Path("translated.epub"),
+    source_path="source.epub",
+    target_path="translated.epub",
     target_language=language.ENGLISH,
+    submit=SubmitKind.APPEND_BLOCK,
+    llm=llm,
 )
 
 # You can also use custom language strings:
 translate(
-    llm=llm,
-    source_path=Path("source.epub"),
-    target_path=Path("translated.epub"),
+    source_path="source.epub",
+    target_path="translated.epub",
     target_language="Icelandic",  # For languages not in the constants
+    submit=SubmitKind.APPEND_BLOCK,
+    llm=llm,
+)
+```
+
+### Error Handling with `on_fill_failed`
+
+Monitor and handle translation errors using the `on_fill_failed` callback:
+
+```python
+from epub_translator import FillFailedEvent
+
+def handle_fill_error(event: FillFailedEvent):
+    print(f"Translation error (attempt {event.retried_count}):")
+    print(f"  {event.error_message}")
+    if event.over_maximum_retries:
+        print("  Maximum retries exceeded!")
+
+translate(
+    source_path="source.epub",
+    target_path="translated.epub",
+    target_language=language.ENGLISH,
+    submit=SubmitKind.APPEND_BLOCK,
+    llm=llm,
+    on_fill_failed=handle_fill_error,
+)
+```
+
+The `FillFailedEvent` contains:
+- `error_message: str` - Description of the error
+- `retried_count: int` - Current retry attempt number
+- `over_maximum_retries: bool` - Whether max retries has been exceeded
+
+### Dual-LLM Architecture
+
+Use separate LLM instances for translation and XML structure filling with different optimization parameters:
+
+```python
+# Create two LLM instances with different temperatures
+translation_llm = LLM(
+    key="your-api-key",
+    url="https://api.openai.com/v1",
+    model="gpt-4",
+    token_encoding="o200k_base",
+    temperature=0.8,  # Higher temperature for creative translation
+)
+
+fill_llm = LLM(
+    key="your-api-key",
+    url="https://api.openai.com/v1",
+    model="gpt-4",
+    token_encoding="o200k_base",
+    temperature=0.3,  # Lower temperature for structure preservation
+)
+
+translate(
+    source_path="source.epub",
+    target_path="translated.epub",
+    target_language=language.ENGLISH,
+    submit=SubmitKind.APPEND_BLOCK,
+    translation_llm=translation_llm,
+    fill_llm=fill_llm,
 )
 ```
 
@@ -203,10 +315,11 @@ Provide specific translation instructions:
 
 ```python
 translate(
-    llm=llm,
-    source_path=Path("source.epub"),
-    target_path=Path("translated.epub"),
+    source_path="source.epub",
+    target_path="translated.epub",
     target_language="English",
+    submit=SubmitKind.APPEND_BLOCK,
+    llm=llm,
     user_prompt="Use formal language and preserve technical terminology",
 )
 ```

epub_translator-0.1.4/epub_translator/__init__.py

@@ -0,0 +1,12 @@
+from . import language
+from .llm import LLM
+from .translator import FillFailedEvent, translate
+from .xml_translator import SubmitKind
+
+__all__ = [
+    "LLM",
+    "translate",
+    "language",
+    "FillFailedEvent",
+    "SubmitKind",
+]

epub_translator-0.1.4/epub_translator/data/fill.jinja

@@ -0,0 +1,171 @@
+You are an XML structure validator. Your ONLY task is to preserve the exact XML structure from the template while filling in translated text.
+
+CRITICAL RULES:
+
+1. Structure Preservation: The output XML MUST have the EXACT SAME structure as the template
+   - Same tags in the same order
+   - Same nesting hierarchy
+   - Same attributes (especially id attributes)
+
+   IMPORTANT: Translation fluency is SECONDARY to structure preservation.
+   If the translated text flows naturally but doesn't match template structure,
+   you MUST break the flow to insert required tags.
+
+2. ID Handling:
+   - Tags WITH id="X": Disambiguation markers for structurally similar elements
+   - Tags WITHOUT id: Structurally unique, match by position and tag name
+   - NEVER add, remove, or change id attributes
+
+3. Text Filling Strategy:
+   - Compare source text with translated text
+   - Identify how source maps to template structure
+   - Apply the same mapping to translated text
+   - Preserve paragraph breaks (elements are natural separators)
+   - IMPORTANT: Translation may change word order - use SEMANTIC matching, not position
+
+---
+
+COMMON ERRORS TO AVOID:
+
+Error Type 1: Missing expected blocks
+❌ WRONG: Omitting elements with id attributes
+✓ CORRECT: Every <tag id="X"> in template MUST appear in output
+
+Error Type 2: Tag count mismatch for non-id elements
+Example template:
+<p id="1">
+  <span>text1</span>
+  <span>text2</span>
+</p>
+
+❌ WRONG: <p id="1"><span>merged text</span></p>  (only 1 span, expected 2)
+✓ CORRECT: <p id="1"><span>text1</span><span>text2</span></p>
+
+Error Type 3: Adding unexpected IDs
+❌ WRONG: Adding id="99" to a tag that didn't have an id in template
+✓ CORRECT: If template has <span>text</span>, output should be <span>译文</span> (no id)
+
+Error Type 4: Wrong tag names
+❌ WRONG: Changing <em id="5"> to <i id="5">
+✓ CORRECT: Keep exact tag name from template
+
+Error Type 5: Missing ID on required elements
+❌ WRONG: <span>text</span> when template has <span id="5">text</span>
+✓ CORRECT: <span id="5">译文</span>
+
+Error Type 6: Wrong text mapping when word order changes
+Example 1: Template has "reviewer of <span id="5">Book</span> in <span id="6">Journal</span>"
+Translation: "Journal 上对 Book 的评论者"
+
+❌ WRONG: Journal 上对 <span id="5">Book</span> 的评论者<span id="6">Journal</span>
+  (appending original text at end)
+✓ CORRECT: <span id="6">Journal</span> 上对 <span id="5">Book</span> 的评论者
+  (wrapping semantic equivalents in translated positions)
+
+Example 2: Breaking fluent translation to preserve structure
+Template: "published in <span id="5">Book Title</span> in 1990"
+Translation: "于1990年出版的《书名》" (flows naturally, but loses structure)
+
+❌ WRONG: 于1990年出版的《书名》 (fluent but missing <span id="5">)
+✓ CORRECT: 于1990年出版的<span id="5">《书名》</span>
+  (Break fluency to preserve structure - this is REQUIRED)
+
+Error Type 7: Wrong semantic matching when word order changes
+When translation changes word order, match elements by SEMANTIC TYPE, not position.
+
+Example: Book title and year
+Template: "<span id="3">Book Title</span> in <span id="4"><a>1990</a></span>"
+Translation: "《书名》于1990年出版"
+
+❌ WRONG: 《书名》于<span id="3">1990</span>年出版...
+  (Matching by position: "1990" appears after "于", so wrapping it with id="3")
+  (WRONG because you matched a YEAR to a slot expecting BOOK TITLE)
+
+✓ CORRECT: <span id="3">《书名》</span>于<span id="4"><a>1990</a></span>年出版
+  (Matching by semantic type: book title → book title, year → year)
+
+KEY PRINCIPLE: Semantic type matching beats position matching!
+- Identify semantic types: book titles, journal names, years (4-digit numbers), person names, etc.
+- Match each to its corresponding slot, regardless of position in translation
+- data-orig-len hints at length: book/journal titles usually longer than years/numbers
+
+---
+
+FILLING ALGORITHM:
+
+1. Analyze template structure: count elements at each level, note id attributes
+
+2. Segment source text by elements (elements are natural separators)
+
+3. Apply to translation - STRICT STRUCTURAL MATCHING:
+
+   A. For elements WITH id:
+      - Locate semantic equivalent in translation
+      - Wrap with same tag+id
+      - If translation merged multiple spans: You MUST still output all original spans separately
+        Example: Template has id="1" and id="2", translation merged both
+        → Output BOTH spans, use source text fallback for missing one
+
+   B. For elements WITHOUT id:
+      - Match by STRUCTURAL POSITION only (template order)
+      - Count MUST be exact: 7 spans in template = 7 spans in output
+      - Even if content repeats (e.g., 3 instances of "x"), each gets its own span
+      - Process sequentially: wrap 1st occurrence with 1st span, 2nd with 2nd span, etc.
+      - DO NOT merge, skip, or add extra elements
+
+      CRITICAL for repeated content:
+      If template has: "...<span>Word</span>...more text...<span>Word</span>"
+      And translation has: "...词...更多文字...词"
+      → Wrap 1st occurrence of "词" with 1st span, 2nd occurrence with 2nd span
+      → Even if the words are identical, treat each span position independently
+
+4. Verify: same element counts, all ids preserved, tag names match
+
+CRITICAL: Template structure is LAW. Translation fluency is secondary.
+
+---
+
+SPECIAL CASES:
+
+1. data-orig-len attribute: Token count hint. Longer counts usually = titles/names, shorter = numbers/symbols.
+
+2. Name+Number as single unit (e.g., "JournalName42" with NO space):
+   - In translation, find the name's equivalent and any adjacent number
+   - Wrap them together: <span id="X">《期刊名》42</span> or <span id="X">《期刊名》第42期</span>
+   - Key: If template treats them as one span, keep them in one span in translation
+
+3. Translation merges adjacent spans:
+   Template: "<span id="A">Word1</span> & <span id="B">Word2</span>"
+   Translation: "复合词" (one inseparable term)
+
+   Solution: You MUST output BOTH spans even if translation merged them
+   - Try to split translation if possible
+   - If truly inseparable: Keep translation for one span, use source text for the other
+   - Example: <span id="A">复合词</span>与<span id="B">Word2</span>
+
+4. Missing semantic match:
+   - Exhaust all possibilities first (synonyms, paraphrases, context)
+   - Last resort: Use source text as fallback
+   - Mixed language is acceptable to preserve structure
+
+WRONG fallback approaches:
+❌ Empty: <span id="2"></span>
+❌ Placeholder: <span id="2">内容</span>
+❌ Duplicate: <span id="2">中文名称</span> (when id="1" has this)
+
+---
+
+OUTPUT FORMAT:
+```xml
+<xml>
+  ... your filled XML here ...
+</xml>
+```
+
+CRITICAL:
+- Return ONLY the XML block, no explanations
+- Do NOT include example blocks or alternatives
+- If unsure, make best attempt based on pattern
+- System will provide detailed error messages if corrections needed
+
+Begin.

{epub_translator-0.1.1 → epub_translator-0.1.4}/epub_translator/epub/__init__.py

@@ -1,4 +1,4 @@
-from .placeholder import Placeholder, is_placeholder_tag
+from .metadata import read_metadata, write_metadata
 from .spines import search_spine_paths
 from .toc import read_toc, write_toc
 from .zip import Zip