epub-translator 0.1.0__tar.gz → 0.1.3__tar.gz

{epub_translator-0.1.0 → epub_translator-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: epub-translator
-Version: 0.1.0
+Version: 0.1.3
 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
@@ -91,10 +91,10 @@ llm = LLM(
 
 # Translate EPUB file using language constants
 translate(
-    llm=llm,
     source_path=Path("source.epub"),
     target_path=Path("translated.epub"),
     target_language=language.ENGLISH,
+    llm=llm,
 )
 ```
 
@@ -113,10 +113,10 @@ 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"),
         target_language="English",
+        llm=llm,
         on_progress=on_progress,
     )
 ```
@@ -149,17 +149,22 @@ 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")
     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.
+
 #### Language Constants
 
 EPUB Translator provides predefined language constants for convenience. You can use these constants instead of writing language names as strings:
@@ -169,18 +174,76 @@ from epub_translator import language
 
 # Usage example:
 translate(
-    llm=llm,
     source_path=Path("source.epub"),
     target_path=Path("translated.epub"),
     target_language=language.ENGLISH,
+    llm=llm,
 )
 
 # You can also use custom language strings:
 translate(
-    llm=llm,
     source_path=Path("source.epub"),
     target_path=Path("translated.epub"),
     target_language="Icelandic",  # For languages not in the constants
+    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=Path("source.epub"),
+    target_path=Path("translated.epub"),
+    target_language=language.ENGLISH,
+    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=Path("source.epub"),
+    target_path=Path("translated.epub"),
+    target_language=language.ENGLISH,
+    translation_llm=translation_llm,
+    fill_llm=fill_llm,
 )
 ```
 
@@ -236,10 +299,10 @@ Provide specific translation instructions:
 
 ```python
 translate(
-    llm=llm,
     source_path=Path("source.epub"),
     target_path=Path("translated.epub"),
     target_language="English",
+    llm=llm,
     user_prompt="Use formal language and preserve technical terminology",
 )
 ```

{epub_translator-0.1.0 → epub_translator-0.1.3}/README.md

@@ -58,10 +58,10 @@ llm = LLM(
 
 # Translate EPUB file using language constants
 translate(
-    llm=llm,
     source_path=Path("source.epub"),
     target_path=Path("translated.epub"),
     target_language=language.ENGLISH,
+    llm=llm,
 )
 ```
 
@@ -80,10 +80,10 @@ 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"),
         target_language="English",
+        llm=llm,
         on_progress=on_progress,
     )
 ```
@@ -116,17 +116,22 @@ 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")
     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.
+
 #### Language Constants
 
 EPUB Translator provides predefined language constants for convenience. You can use these constants instead of writing language names as strings:
@@ -136,18 +141,76 @@ from epub_translator import language
 
 # Usage example:
 translate(
-    llm=llm,
     source_path=Path("source.epub"),
     target_path=Path("translated.epub"),
     target_language=language.ENGLISH,
+    llm=llm,
 )
 
 # You can also use custom language strings:
 translate(
-    llm=llm,
     source_path=Path("source.epub"),
     target_path=Path("translated.epub"),
     target_language="Icelandic",  # For languages not in the constants
+    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=Path("source.epub"),
+    target_path=Path("translated.epub"),
+    target_language=language.ENGLISH,
+    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=Path("source.epub"),
+    target_path=Path("translated.epub"),
+    target_language=language.ENGLISH,
+    translation_llm=translation_llm,
+    fill_llm=fill_llm,
 )
 ```
 
@@ -203,10 +266,10 @@ Provide specific translation instructions:
 
 ```python
 translate(
-    llm=llm,
     source_path=Path("source.epub"),
     target_path=Path("translated.epub"),
     target_language="English",
+    llm=llm,
     user_prompt="Use formal language and preserve technical terminology",
 )
 ```

epub_translator-0.1.3/epub_translator/__init__.py

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

epub_translator-0.1.3/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.0 → epub_translator-0.1.3}/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

epub_translator-0.1.3/epub_translator/epub/metadata.py

@@ -0,0 +1,122 @@
+from dataclasses import dataclass
+
+from .common import find_opf_path
+from .zip import Zip
+
+
+@dataclass
+class MetadataField:
+    """
+    表示 EPUB OPF 文件中的元数据字段
+
+    - tag_name: 标签名（不带命名空间）
+    - text: 文本内容
+    """
+
+    tag_name: str
+    text: str
+
+
+# 不应该被翻译的元数据字段
+SKIP_FIELDS = {
+    "language",
+    "identifier",
+    "date",
+    "meta",
+    "contributor",  # Usually technical information
+}
+
+
+def read_metadata(zip: Zip) -> list[MetadataField]:
+    """
+    从 EPUB 的 OPF 文件中读取所有可翻译的元数据字段。
+
+    返回包含标签名和文本内容的列表。
+    自动过滤掉不应该翻译的字段（language, identifier, date, meta, contributor 等）。
+    """
+    opf_path = find_opf_path(zip)
+
+    with zip.read(opf_path) as f:
+        content = f.read()
+
+    from xml.etree import ElementTree as ET
+
+    root = ET.fromstring(content)
+
+    # Find metadata element
+    metadata_elem = None
+    for child in root:
+        if child.tag.endswith("metadata"):
+            metadata_elem = child
+            break
+
+    if metadata_elem is None:
+        return []
+
+    # Collect metadata fields to translate
+    fields: list[MetadataField] = []
+
+    for elem in metadata_elem:
+        # Get tag name without namespace
+        tag_name = elem.tag.split("}")[-1] if "}" in elem.tag else elem.tag
+
+        # Check if element has text content and should be translated
+        if elem.text and elem.text.strip() and tag_name not in SKIP_FIELDS:
+            fields.append(MetadataField(tag_name=tag_name, text=elem.text.strip()))
+
+    return fields
+
+
+def write_metadata(zip: Zip, fields: list[MetadataField]) -> None:
+    """
+    将翻译后的元数据字段写回 EPUB 的 OPF 文件。
+
+    根据 tag_name 匹配对应的元素，并更新其文本内容。
+    匹配策略：按照 tag_name 和在文件中出现的顺序依次匹配。
+    """
+    opf_path = find_opf_path(zip)
+
+    with zip.read(opf_path) as f:
+        content = f.read()
+
+    from xml.etree import ElementTree as ET
+
+    root = ET.fromstring(content)
+
+    # Find metadata element
+    metadata_elem = None
+    for child in root:
+        if child.tag.endswith("metadata"):
+            metadata_elem = child
+            break
+
+    if metadata_elem is None:
+        return
+
+    # Build a mapping: tag_name -> list of fields with that tag_name
+    fields_by_tag: dict[str, list[str]] = {}
+    for field in fields:
+        if field.tag_name not in fields_by_tag:
+            fields_by_tag[field.tag_name] = []
+        fields_by_tag[field.tag_name].append(field.text)
+
+    # Create a counter for each tag to track which occurrence we're at
+    tag_counters: dict[str, int] = {tag: 0 for tag in fields_by_tag}
+
+    # Update elements in metadata
+    for elem in metadata_elem:
+        # Get tag name without namespace
+        tag_name = elem.tag.split("}")[-1] if "}" in elem.tag else elem.tag
+
+        # Check if this tag has translated text
+        if tag_name in fields_by_tag and elem.text and elem.text.strip():
+            counter = tag_counters[tag_name]
+            if counter < len(fields_by_tag[tag_name]):
+                # Update the text with translated version
+                elem.text = fields_by_tag[tag_name][counter]
+                tag_counters[tag_name] += 1
+
+    # Write back the modified OPF file
+    tree = ET.ElementTree(root)
+    with zip.replace(opf_path) as f:
+        tree.write(f, encoding="utf-8", xml_declaration=True)

{epub_translator-0.1.0 → epub_translator-0.1.3}/epub_translator/epub/spines.py

@@ -6,7 +6,8 @@ from .common import find_opf_path, strip_namespace
 from .zip import Zip
 
 
-def search_spine_paths(zip: Zip) -> Generator[Path, None, None]:
+# yield file_path, media_type
+def search_spine_paths(zip: Zip) -> Generator[tuple[Path, str], None, None]:
     opf_path = find_opf_path(zip)
     opf_dir = opf_path.parent
 
@@ -39,4 +40,4 @@ def search_spine_paths(zip: Zip) -> Generator[Path, None, None]:
             if idref in manifest_items:
                 href, media_type = manifest_items[idref]
                 if media_type in ("application/xhtml+xml", "text/html"):
-                    yield opf_dir / href
+                    yield opf_dir / href, media_type

{epub_translator-0.1.0 → epub_translator-0.1.3}/epub_translator/epub/zip.py

@@ -44,24 +44,26 @@ class Zip:
         all_files = self._source_zip.namelist()
         if prefix_path is None:
             return [Path(f) for f in all_files]
-        prefix = str(prefix_path)
+        prefix = prefix_path.as_posix()
         if not prefix.endswith("/"):
             prefix += "/"
         return [Path(f) for f in all_files if f.startswith(prefix)]
 
     def migrate(self, path: Path):
+        path_str = path.as_posix()
+        source_info = self._source_zip.getinfo(path_str)
         with self.read(path) as source_file:
-            with self._target_zip.open(str(path), "w") as target_file:
-                while True:
-                    chunk = source_file.read(_BUFFER_SIZE)
-                    if not chunk:
-                        break
-                    target_file.write(chunk)
+            content = source_file.read()
+        self._target_zip.writestr(
+            zinfo_or_arcname=source_info,
+            data=content,
+            compress_type=source_info.compress_type,
+        )
         self._processed_files.add(path)
 
     def read(self, path: Path) -> IO[bytes]:
-        return self._source_zip.open(str(path), "r")
+        return self._source_zip.open(path.as_posix(), "r")
 
     def replace(self, path: Path) -> IO[bytes]:
         self._processed_files.add(path)
-        return self._target_zip.open(str(path), "w")
+        return self._target_zip.open(path.as_posix(), "w")