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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: epub-translator
-Version: 0.1.3
+Version: 0.1.5
 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,9 +90,10 @@ llm = LLM(
 
 # Translate EPUB file using language constants
 translate(
-    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,9 +113,10 @@ with tqdm(total=100, desc="Translating", unit="%") as pbar:
         last_progress = progress
 
     translate(
-        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,
     )
@@ -152,6 +153,7 @@ translate(
     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
@@ -165,6 +167,49 @@ translate(
 
 **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,
+)
+```
+
 #### Language Constants
 
 EPUB Translator provides predefined language constants for convenience. You can use these constants instead of writing language names as strings:
@@ -174,47 +219,73 @@ from epub_translator import language
 
 # Usage example:
 translate(
-    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(
-    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:
+Monitor translation errors using the `on_fill_failed` callback. The system automatically retries failed translations up to `max_retries` times (default: 5). Most errors are recovered during retries and don't affect the final output.
 
 ```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}")
+    # Only log critical errors that will affect the final EPUB
     if event.over_maximum_retries:
-        print("  Maximum retries exceeded!")
+        print(f"Critical error after {event.retried_count} attempts:")
+        print(f"  {event.error_message}")
+        print("  This error will be present in the final EPUB file!")
 
 translate(
-    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,
     on_fill_failed=handle_fill_error,
 )
 ```
 
+**Understanding Error Severity:**
+
 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
+- `retried_count: int` - Current retry attempt number (1 to max_retries)
+- `over_maximum_retries: bool` - Whether the error is critical
+
+**Error Categories:**
+
+- **Recoverable errors** (`over_maximum_retries=False`): Errors during retry attempts. The system will continue retrying and may resolve these automatically. Safe to ignore in most cases.
+
+- **Critical errors** (`over_maximum_retries=True`): Errors that persist after all retry attempts. These will appear in the final EPUB file and should be investigated.
+
+**Advanced Usage:**
+
+For verbose logging during translation debugging:
+
+```python
+def handle_fill_error(event: FillFailedEvent):
+    if event.over_maximum_retries:
+        # Critical: affects final output
+        print(f"❌ CRITICAL: {event.error_message}")
+    else:
+        # Informational: system is retrying
+        print(f"⚠️  Retry {event.retried_count}: {event.error_message}")
+```
 
 ### Dual-LLM Architecture
 
@@ -239,9 +310,10 @@ fill_llm = LLM(
 )
 
 translate(
-    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,
     translation_llm=translation_llm,
     fill_llm=fill_llm,
 )
@@ -299,9 +371,10 @@ Provide specific translation instructions:
 
 ```python
 translate(
-    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.3 → epub_translator-0.1.5}/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,9 +57,10 @@ llm = LLM(
 
 # Translate EPUB file using language constants
 translate(
-    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,9 +80,10 @@ with tqdm(total=100, desc="Translating", unit="%") as pbar:
         last_progress = progress
 
     translate(
-        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,
     )
@@ -119,6 +120,7 @@ translate(
     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
@@ -132,6 +134,49 @@ translate(
 
 **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,
+)
+```
+
 #### Language Constants
 
 EPUB Translator provides predefined language constants for convenience. You can use these constants instead of writing language names as strings:
@@ -141,47 +186,73 @@ from epub_translator import language
 
 # Usage example:
 translate(
-    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(
-    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:
+Monitor translation errors using the `on_fill_failed` callback. The system automatically retries failed translations up to `max_retries` times (default: 5). Most errors are recovered during retries and don't affect the final output.
 
 ```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}")
+    # Only log critical errors that will affect the final EPUB
     if event.over_maximum_retries:
-        print("  Maximum retries exceeded!")
+        print(f"Critical error after {event.retried_count} attempts:")
+        print(f"  {event.error_message}")
+        print("  This error will be present in the final EPUB file!")
 
 translate(
-    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,
     on_fill_failed=handle_fill_error,
 )
 ```
 
+**Understanding Error Severity:**
+
 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
+- `retried_count: int` - Current retry attempt number (1 to max_retries)
+- `over_maximum_retries: bool` - Whether the error is critical
+
+**Error Categories:**
+
+- **Recoverable errors** (`over_maximum_retries=False`): Errors during retry attempts. The system will continue retrying and may resolve these automatically. Safe to ignore in most cases.
+
+- **Critical errors** (`over_maximum_retries=True`): Errors that persist after all retry attempts. These will appear in the final EPUB file and should be investigated.
+
+**Advanced Usage:**
+
+For verbose logging during translation debugging:
+
+```python
+def handle_fill_error(event: FillFailedEvent):
+    if event.over_maximum_retries:
+        # Critical: affects final output
+        print(f"❌ CRITICAL: {event.error_message}")
+    else:
+        # Informational: system is retrying
+        print(f"⚠️  Retry {event.retried_count}: {event.error_message}")
+```
 
 ### Dual-LLM Architecture
 
@@ -206,9 +277,10 @@ fill_llm = LLM(
 )
 
 translate(
-    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,
     translation_llm=translation_llm,
     fill_llm=fill_llm,
 )
@@ -266,9 +338,10 @@ Provide specific translation instructions:
 
 ```python
 translate(
-    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.5/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.5/epub_translator/punctuation.py

@@ -0,0 +1,34 @@
+from xml.etree.ElementTree import Element
+
+from .xml import iter_with_stack
+
+_QUOTE_MAPPING = {
+    # 法语引号
+    "«": "",
+    "»": "",
+    "‹": "«",
+    "›": "»",
+    # 中文书书名号
+    "《": "",
+    "》": "",
+    "〈": "《",
+    "〉": "》",
+}
+
+
+def _strip_quotes(text: str):
+    for char in text:
+        mapped = _QUOTE_MAPPING.get(char, None)
+        if mapped is None:
+            yield char
+        elif mapped:
+            yield mapped
+
+
+def unwrap_french_quotes(element: Element) -> Element:
+    for _, child_element in iter_with_stack(element):
+        if child_element.text:
+            child_element.text = "".join(_strip_quotes(child_element.text))
+        if child_element.tail:
+            child_element.tail = "".join(_strip_quotes(child_element.tail))
+    return element

{epub_translator-0.1.3 → epub_translator-0.1.5}/epub_translator/segment/text_segment.py

@@ -4,71 +4,7 @@ from enum import Enum, auto
 from typing import Self
 from xml.etree.ElementTree import Element
 
-from ..xml import expand_left_element_texts, expand_right_element_texts, normalize_text_in_element
-
-# HTML inline-level elements
-# Reference: https://developer.mozilla.org/en-US/docs/Web/HTML/Inline_elements
-# Reference: https://developer.mozilla.org/en-US/docs/Glossary/Inline-level_content
-_HTML_INLINE_TAGS = frozenset(
-    (
-        # Inline text semantics
-        "a",
-        "abbr",
-        "b",
-        "bdi",
-        "bdo",
-        "br",
-        "cite",
-        "code",
-        "data",
-        "dfn",
-        "em",
-        "i",
-        "kbd",
-        "mark",
-        "q",
-        "rp",
-        "rt",
-        "ruby",
-        "s",
-        "samp",
-        "small",
-        "span",
-        "strong",
-        "sub",
-        "sup",
-        "time",
-        "u",
-        "var",
-        "wbr",
-        # Image and multimedia
-        "img",
-        "svg",
-        "canvas",
-        "audio",
-        "video",
-        "map",
-        "area",
-        # Form elements
-        "input",
-        "button",
-        "select",
-        "textarea",
-        "label",
-        "output",
-        "progress",
-        "meter",
-        # Embedded content
-        "iframe",
-        "embed",
-        "object",
-        # Other inline elements
-        "script",
-        "del",
-        "ins",
-        "slot",
-    )
-)
+from ..xml import expand_left_element_texts, expand_right_element_texts, is_inline_tag, normalize_text_in_element
 
 
 class TextPosition(Enum):
@@ -196,8 +132,7 @@ def _search_text_segments(stack: list[Element], element: Element) -> Generator[T
 def _find_block_depth(parent_stack: list[Element]) -> int:
     index: int = 0
     for i in range(len(parent_stack) - 1, -1, -1):
-        checked_tag = parent_stack[i].tag.lower()
-        if checked_tag not in _HTML_INLINE_TAGS:
+        if not is_inline_tag(parent_stack[i].tag):
             index = i
             break
     return index + 1  # depth is a count not index

{epub_translator-0.1.3 → epub_translator-0.1.5}/epub_translator/translator.py

@@ -1,4 +1,4 @@
-from collections.abc import Callable
+from collections.abc import Callable, Generator
 from dataclasses import dataclass
 from enum import Enum, auto
 from importlib.metadata import version as get_package_version
@@ -15,9 +15,10 @@ from .epub import (
 )
 from .epub_transcode import decode_metadata, decode_toc_list, encode_metadata, encode_toc_list
 from .llm import LLM
+from .punctuation import unwrap_french_quotes
 from .xml import XMLLikeNode, deduplicate_ids_in_element, find_first
 from .xml_interrupter import XMLInterrupter
-from .xml_translator import FillFailedEvent, XMLTranslator
+from .xml_translator import FillFailedEvent, SubmitKind, TranslationTask, XMLTranslator
 
 
 class _ElementType(Enum):
@@ -36,6 +37,7 @@ def translate(
     source_path: PathLike | str,
     target_path: PathLike | str,
     target_language: str,
+    submit: SubmitKind,
     user_prompt: str | None = None,
     max_retries: int = 5,
     max_group_tokens: int = 1200,
@@ -83,33 +85,26 @@ def translate(
             return
 
         interrupter = XMLInterrupter()
-        element_contexts: dict[int, _ElementContext] = {}
-
         toc_weight = 0.05 if toc_has_items else 0
         metadata_weight = 0.05 if metadata_has_items else 0
         chapters_weight = 1.0 - toc_weight - metadata_weight
         progress_per_chapter = chapters_weight / total_chapters if total_chapters > 0 else 0
         current_progress = 0.0
 
-        for translated_elem in translator.translate_elements(
+        for translated_elem, context in translator.translate_elements(
             interrupt_source_text_segments=interrupter.interrupt_source_text_segments,
             interrupt_translated_text_segments=interrupter.interrupt_translated_text_segments,
             interrupt_block_element=interrupter.interrupt_block_element,
             on_fill_failed=on_fill_failed,
-            elements=_generate_elements_from_book(
+            tasks=_generate_tasks_from_book(
                 zip=zip,
                 toc_list=toc_list,
                 metadata_fields=metadata_fields,
-                element_contexts=element_contexts,
+                submit=submit,
             ),
         ):
-            elem_id = id(translated_elem)
-            context = element_contexts.pop(elem_id, None)
-
-            if context is None:
-                continue
-
             if context.element_type == _ElementType.TOC:
+                translated_elem = unwrap_french_quotes(translated_elem)
                 decoded_toc = decode_toc_list(translated_elem)
                 write_toc(zip, decoded_toc)
 
@@ -118,6 +113,7 @@ def translate(
                     on_progress(current_progress)
 
             elif context.element_type == _ElementType.METADATA:
+                translated_elem = unwrap_french_quotes(translated_elem)
                 decoded_metadata = decode_metadata(translated_elem)
                 write_metadata(zip, decoded_metadata)
 
@@ -137,23 +133,29 @@ def translate(
                     on_progress(current_progress)
 
 
-def _generate_elements_from_book(
+def _generate_tasks_from_book(
     zip: Zip,
     toc_list: list,
     metadata_fields: list,
-    element_contexts: dict[int, _ElementContext],
-):
+    submit: SubmitKind,
+) -> Generator[TranslationTask[_ElementContext], None, None]:
+    head_submit = submit
+    if head_submit == SubmitKind.APPEND_BLOCK:
+        head_submit = SubmitKind.APPEND_TEXT
+
     if toc_list:
-        toc_elem = encode_toc_list(toc_list)
-        elem_id = id(toc_elem)
-        element_contexts[elem_id] = _ElementContext(element_type=_ElementType.TOC)
-        yield toc_elem
+        yield TranslationTask(
+            element=encode_toc_list(toc_list),
+            action=head_submit,
+            payload=_ElementContext(element_type=_ElementType.TOC),
+        )
 
     if metadata_fields:
-        metadata_elem = encode_metadata(metadata_fields)
-        elem_id = id(metadata_elem)
-        element_contexts[elem_id] = _ElementContext(element_type=_ElementType.METADATA)
-        yield metadata_elem
+        yield TranslationTask(
+            element=encode_metadata(metadata_fields),
+            action=head_submit,
+            payload=_ElementContext(element_type=_ElementType.METADATA),
+        )
 
     for chapter_path, media_type in search_spine_paths(zip):
         with zip.read(chapter_path) as chapter_file:
@@ -163,12 +165,14 @@ def _generate_elements_from_book(
             )
         body_element = find_first(xml.element, "body")
         if body_element is not None:
-            elem_id = id(body_element)
-            element_contexts[elem_id] = _ElementContext(
-                element_type=_ElementType.CHAPTER,
-                chapter_data=(chapter_path, xml),
+            yield TranslationTask(
+                element=body_element,
+                action=submit,
+                payload=_ElementContext(
+                    element_type=_ElementType.CHAPTER,
+                    chapter_data=(chapter_path, xml),
+                ),
             )
-            yield body_element
 
 
 def _get_version() -> str:

{epub_translator-0.1.3 → epub_translator-0.1.5}/epub_translator/xml/__init__.py

@@ -1,6 +1,7 @@
 from .const import *
 from .deduplication import *
 from .firendly import *
+from .inline import *
 from .utils import *
 from .xml import *
 from .xml_like import *