epub-translator 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

epub_translator/__init__.py

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

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/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/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/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 *

epub_translator/xml/inline.py

@@ -0,0 +1,67 @@
+# 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",
+    )
+)
+
+
+def is_inline_tag(tag: str) -> bool:
+    return tag.lower() in _HTML_INLINE_TAGS

epub_translator/xml_translator/__init__.py

@@ -1,2 +1,3 @@
 from .callbacks import FillFailedEvent
-from .translator import XMLTranslator
+from .submitter import SubmitKind
+from .translator import TranslationTask, XMLTranslator

epub_translator/xml_translator/submitter.py

@@ -1,56 +1,381 @@
+from collections.abc import Generator
+from dataclasses import dataclass
+from enum import Enum, auto
 from xml.etree.ElementTree import Element
 
 from ..segment import TextSegment, combine_text_segments
-from ..xml import index_of_parent, iter_with_stack
+from ..xml import index_of_parent, is_inline_tag, iter_with_stack
 from .stream_mapper import InlineSegmentMapping
 
 
-def submit_text_segments(element: Element, mappings: list[InlineSegmentMapping]) -> Element:
-    grouped_map = _group_text_segments(mappings)
-    _append_text_segments(element, grouped_map)
+class SubmitKind(Enum):
+    REPLACE = auto()
+    APPEND_TEXT = auto()
+    APPEND_BLOCK = auto()
+
+
+def submit(element: Element, action: SubmitKind, mappings: list[InlineSegmentMapping]) -> Element:
+    submitter = _Submitter(
+        element=element,
+        action=action,
+        mappings=mappings,
+    )
+    replaced_root = submitter.do()
+    if replaced_root is not None:
+        return replaced_root
+
     return element
 
 
-def _group_text_segments(mappings: list[InlineSegmentMapping]):
-    grouped_map: dict[int, list[TextSegment]] = {}
-    for block_element, text_segments in mappings:
-        parent_id = id(block_element)
-        grouped_map[parent_id] = text_segments
-
-    # TODO: 如下是为了清除嵌入文字的 Block，当前版本忽略了嵌入文字的 Block 概念。
-    #       这是书籍中可能出现的一种情况，虽然不多见。
-    #       例如，作为非叶子的块元素，它的子块元素之间会夹杂文本，当前 collect_next_inline_segment 会忽略这些文字：
-    #       <div>
-    #         Some text before.
-    #         <!-- 只有下一行作为叶子节点的块元素内的文字会被处理 -->
-    #         <div>Paragraph 1.</div>
-    #         Some text in between.
-    #       </div>
-    for _, text_segments in mappings:
-        for text_segment in text_segments:
-            for parent_block in text_segment.parent_stack[: text_segment.block_depth - 1]:
-                grouped_map.pop(id(parent_block), None)
-
-    return grouped_map
-
-
-def _append_text_segments(element: Element, grouped_map: dict[int, list[TextSegment]]):
-    for parents, child_element in iter_with_stack(element):
-        if not parents:
-            continue
-        grouped = grouped_map.get(id(child_element))
-        if not grouped:
-            continue
-        parent = parents[-1]
-        index = index_of_parent(parents[-1], child_element)
-        combined = next(
-            combine_text_segments(
-                segments=(t.strip_block_parents() for t in grouped),
-            ),
-            None,
-        )
+@dataclass
+class _Node:
+    raw_element: Element
+    items: list[tuple[list[TextSegment], "_Node"]]  # empty for peak, non-empty for platform
+    tail_text_segments: list[TextSegment]
+
+
+class _Submitter:
+    def __init__(
+        self,
+        element: Element,
+        action: SubmitKind,
+        mappings: list[InlineSegmentMapping],
+    ) -> None:
+        self._action: SubmitKind = action
+        self._nodes: list[_Node] = list(_nest_nodes(mappings))
+        self._parents: dict[int, Element] = self._collect_parents(element, mappings)
+
+    def _collect_parents(self, element: Element, mappings: list[InlineSegmentMapping]):
+        ids: set[int] = set(id(e) for e, _ in mappings)
+        parents_dict: dict[int, Element] = {}
+        for parents, child in iter_with_stack(element):
+            if parents and id(child) in ids:
+                parents_dict[id(child)] = parents[-1]
+        return parents_dict
+
+    def do(self):
+        replaced_root: Element | None = None
+
+        for node in self._nodes:
+            submitted = self._submit_node(node)
+            if replaced_root is None:
+                replaced_root = submitted
+
+        return replaced_root
+
+    # @return replaced root element, or None if appended to parent
+    def _submit_node(self, node: _Node) -> Element | None:
+        if node.items or self._action == SubmitKind.APPEND_TEXT:
+            return self._submit_by_text(node)
+        else:
+            return self._submit_by_block(node)
+
+    def _submit_by_block(self, node: _Node) -> Element | None:
+        parent = self._parents.get(id(node.raw_element), None)
+        if parent is None:
+            return node.raw_element
+
+        preserved_elements: list[Element] = []
+        if self._action == SubmitKind.REPLACE:
+            for child in list(node.raw_element):
+                if not is_inline_tag(child.tag):
+                    child.tail = None
+                    preserved_elements.append(child)
+
+        index = index_of_parent(parent, node.raw_element)
+        combined = self._combine_text_segments(node.tail_text_segments)
+
         if combined is not None:
-            combined_element, _ = combined
-            parent.insert(index + 1, combined_element)
-            combined_element.tail = child_element.tail
-            child_element.tail = None
+            # 在 APPEND_BLOCK 模式下，如果是 inline tag，则在文本前面加空格
+            if self._action == SubmitKind.APPEND_BLOCK and is_inline_tag(combined.tag) and combined.text:
+                combined.text = " " + combined.text
+            parent.insert(index + 1, combined)
+            index += 1
+
+        for elem in preserved_elements:
+            parent.insert(index + 1, elem)
+            index += 1
+
+        if combined is not None or preserved_elements:
+            if preserved_elements:
+                preserved_elements[-1].tail = node.raw_element.tail
+            elif combined is not None:
+                combined.tail = node.raw_element.tail
+            node.raw_element.tail = None
+
+            if self._action == SubmitKind.REPLACE:
+                parent.remove(node.raw_element)
+
+        return None
+
+    def _submit_by_text(self, node: _Node) -> Element | None:
+        replaced_root: Element | None = None
+        child_nodes = dict((id(node), node) for _, node in node.items)
+        last_tail_element: Element | None = None
+        tail_elements: dict[int, Element] = {}
+
+        for child_element in node.raw_element:
+            child_node = child_nodes.get(id(child_element), None)
+            if child_node is not None:
+                if last_tail_element is not None:
+                    tail_elements[id(child_element)] = last_tail_element
+                last_tail_element = child_element
+
+        for text_segments, child_node in node.items:
+            anchor_element = _find_anchor_in_parent(node.raw_element, child_node.raw_element)
+            if anchor_element is None:
+                # 防御性编程：理论上 anchor_element 不应该为 None，
+                #           因为 _nest_nodes 已经通过 _check_includes 验证了包含关系。
+                continue
+
+            tail_element = tail_elements.get(id(anchor_element), None)
+            items_preserved_elements: list[Element] = []
+
+            if self._action == SubmitKind.REPLACE:
+                end_index = index_of_parent(node.raw_element, anchor_element)
+                items_preserved_elements = self._remove_elements_after_tail(
+                    node_element=node.raw_element,
+                    tail_element=tail_element,
+                    end_index=end_index,
+                )
+
+            self._append_combined_after_tail(
+                node_element=node.raw_element,
+                text_segments=text_segments,
+                tail_element=tail_element,
+                anchor_element=anchor_element,
+                append_to_end=False,
+            )
+            if items_preserved_elements:
+                insert_position = index_of_parent(node.raw_element, anchor_element)
+                for i, elem in enumerate(items_preserved_elements):
+                    node.raw_element.insert(insert_position + i, elem)
+
+        for _, child_node in node.items:
+            submitted = self._submit_node(child_node)
+            if replaced_root is None:
+                replaced_root = submitted
+
+        if node.raw_element:
+            last_tail_element = node.raw_element[-1]
+        else:
+            last_tail_element = None
+
+        tail_preserved_elements: list[Element] = []
+        if self._action == SubmitKind.REPLACE:
+            tail_preserved_elements = self._remove_elements_after_tail(
+                node_element=node.raw_element,
+                tail_element=last_tail_element,
+                end_index=None,  # None 表示删除到末尾
+            )
+        self._append_combined_after_tail(
+            node_element=node.raw_element,
+            text_segments=node.tail_text_segments,
+            tail_element=last_tail_element,
+            anchor_element=None,
+            append_to_end=True,
+        )
+        if tail_preserved_elements:
+            for elem in tail_preserved_elements:
+                node.raw_element.append(elem)
+
+        return replaced_root
+
+    def _remove_elements_after_tail(
+        self,
+        node_element: Element,
+        tail_element: Element | None,
+        end_index: int | None = None,
+    ) -> list[Element]:
+        if tail_element is None:
+            start_index = 0
+            node_element.text = None
+        else:
+            start_index = index_of_parent(node_element, tail_element) + 1
+            tail_element.tail = None
+
+        if end_index is None:
+            end_index = len(node_element)
+
+        preserved_elements: list[Element] = []
+        for i in range(start_index, end_index):
+            elem = node_element[i]
+            if not is_inline_tag(elem.tag):
+                elem.tail = None
+                preserved_elements.append(elem)
+
+        for i in range(end_index - 1, start_index - 1, -1):
+            node_element.remove(node_element[i])
+
+        return preserved_elements
+
+    def _append_combined_after_tail(
+        self,
+        node_element: Element,
+        text_segments: list[TextSegment],
+        tail_element: Element | None,
+        anchor_element: Element | None,
+        append_to_end: bool,
+    ) -> None:
+        combined = self._combine_text_segments(text_segments)
+        if combined is None:
+            return
+
+        if combined.text:
+            will_inject_space = self._action == SubmitKind.APPEND_TEXT or (
+                is_inline_tag(combined.tag) and self._action == SubmitKind.APPEND_BLOCK
+            )
+            if tail_element is not None:
+                tail_element.tail = self._append_text_in_element(
+                    origin_text=tail_element.tail,
+                    append_text=combined.text,
+                    will_inject_space=will_inject_space,
+                )
+            elif anchor_element is None:
+                node_element.text = self._append_text_in_element(
+                    origin_text=node_element.text,
+                    append_text=combined.text,
+                    will_inject_space=will_inject_space,
+                )
+            else:
+                ref_index = index_of_parent(node_element, anchor_element)
+                if ref_index > 0:
+                    # 添加到前一个元素的 tail
+                    prev_element = node_element[ref_index - 1]
+                    prev_element.tail = self._append_text_in_element(
+                        origin_text=prev_element.tail,
+                        append_text=combined.text,
+                        will_inject_space=will_inject_space,
+                    )
+                else:
+                    # ref_element 是第一个元素，添加到 node_element.text
+                    node_element.text = self._append_text_in_element(
+                        origin_text=node_element.text,
+                        append_text=combined.text,
+                        will_inject_space=will_inject_space,
+                    )
+
+        if tail_element is not None:
+            insert_position = index_of_parent(node_element, tail_element) + 1
+        elif append_to_end:
+            insert_position = len(node_element)
+        elif anchor_element is not None:
+            # 使用 ref_element 来定位插入位置
+            # 如果文本被添加到前一个元素的 tail，则在前一个元素之后插入
+            ref_index = index_of_parent(node_element, anchor_element)
+            if ref_index > 0:
+                # 在前一个元素之后插入
+                insert_position = ref_index
+            else:
+                # ref_element 是第一个元素，插入到开头
+                insert_position = 0
+        else:
+            insert_position = 0
+
+        for i, child in enumerate(combined):
+            node_element.insert(insert_position + i, child)
+
+    def _combine_text_segments(self, text_segments: list[TextSegment]) -> Element | None:
+        segments = (t.strip_block_parents() for t in text_segments)
+        combined = next(combine_text_segments(segments), None)
+        if combined is None:
+            return None
+        else:
+            return combined[0]
+
+    def _append_text_in_element(
+        self,
+        origin_text: str | None,
+        append_text: str,
+        will_inject_space: bool,
+    ) -> str:
+        if origin_text is None:
+            return append_text
+        elif will_inject_space:
+            return origin_text.rstrip() + " " + append_text.lstrip()
+        else:
+            return origin_text + append_text
+
+
+def _nest_nodes(mappings: list[InlineSegmentMapping]) -> Generator[_Node, None, None]:
+    # 需要翻译的文字会被嵌套到两种不同的结构中。
+    # 最常见的的是 peak 结构，例如如下结构，没有任何子结构（inline 标签不是视为子结构）。
+    # 可直接文本替换或追加。
+    # <div>Some text <b>bold text</b> more text.</div>
+    #
+    # 但是还有一种少见的 platform 结构，它内部被其他 peak/platform 切割。
+    #   <div>
+    #     Some text before.
+    #     <!-- 如下 peak 将它的阅读流切段 -->
+    #     <div>Paragraph 1.</div>
+    #     Some text in between.
+    #   </div>
+    # 如果直接对它进行替换或追加，读者阅读流会被破坏，从而读起来怪异。
+    # 正是因为这种结构的存在，必须还原成树型结构，然后用特殊的方式来处理 platform 结构。
+    #
+    # 总之，我们假设 95% 的阅读体验由 peak 提供，但为兼顾剩下的 platform 结构，故加此步骤。
+    stack: list[_Node] = []
+
+    for block_element, text_segments in mappings:
+        keep_depth: int = 0
+        upwards: bool = False
+        for i in range(len(stack) - 1, -1, -1):
+            if stack[i].raw_element is block_element:
+                keep_depth = i + 1
+                upwards = True
+                break
+
+        if not upwards:
+            for i in range(len(stack) - 1, -1, -1):
+                if _check_includes(stack[i].raw_element, block_element):
+                    keep_depth = i + 1
+                    break
+
+        while len(stack) > keep_depth:
+            child_node = _fold_top_of_stack(stack)
+            if not upwards and child_node is not None:
+                yield child_node
+
+        if upwards:
+            stack[keep_depth - 1].tail_text_segments.extend(text_segments)
+        else:
+            stack.append(
+                _Node(
+                    raw_element=block_element,
+                    items=[],
+                    tail_text_segments=list(text_segments),
+                )
+            )
+    while stack:
+        child_node = _fold_top_of_stack(stack)
+        if child_node is not None:
+            yield child_node
+
+
+def _find_anchor_in_parent(parent: Element, descendant: Element) -> Element | None:
+    for child in parent:
+        if child is descendant:
+            return descendant
+
+    for child in parent:
+        if _check_includes(child, descendant):
+            return child
+
+    return None
+
+
+def _fold_top_of_stack(stack: list[_Node]):
+    child_node = stack.pop()
+    if not stack:
+        return child_node
+    parent_node = stack[-1]
+    parent_node.items.append((parent_node.tail_text_segments, child_node))
+    parent_node.tail_text_segments = []
+    return None
+
+
+def _check_includes(parent: Element, child: Element) -> bool:
+    for _, checked in iter_with_stack(parent):
+        if child is checked:
+            return True
+    return False

epub_translator/xml_translator/translator.py

@@ -1,5 +1,6 @@
 from collections.abc import Callable, Generator, Iterable
-from typing import TypeVar
+from dataclasses import dataclass
+from typing import Generic, TypeVar
 from xml.etree.ElementTree import Element
 
 from ..llm import LLM, Message, MessageRole
@@ -8,11 +9,18 @@ from ..xml import decode_friendly, encode_friendly
 from .callbacks import Callbacks, FillFailedEvent, warp_callbacks
 from .hill_climbing import HillClimbing
 from .stream_mapper import InlineSegmentMapping, XMLStreamMapper
-from .submitter import submit_text_segments
+from .submitter import SubmitKind, submit
 
 T = TypeVar("T")
 
 
+@dataclass
+class TranslationTask(Generic[T]):
+    element: Element
+    action: SubmitKind
+    payload: T
+
+
 class XMLTranslator:
     def __init__(
         self,
@@ -41,14 +49,14 @@ class XMLTranslator:
 
     def translate_element(
         self,
-        element: Element,
+        task: TranslationTask[T],
         interrupt_source_text_segments: Callable[[Iterable[TextSegment]], Iterable[TextSegment]] | None = None,
         interrupt_translated_text_segments: Callable[[Iterable[TextSegment]], Iterable[TextSegment]] | None = None,
         interrupt_block_element: Callable[[Element], Element] | None = None,
         on_fill_failed: Callable[[FillFailedEvent], None] | None = None,
-    ) -> Element:
+    ) -> tuple[Element, T]:
         for translated in self.translate_elements(
-            elements=((element),),
+            tasks=((task),),
             interrupt_source_text_segments=interrupt_source_text_segments,
             interrupt_translated_text_segments=interrupt_translated_text_segments,
             interrupt_block_element=interrupt_block_element,
@@ -60,30 +68,41 @@ class XMLTranslator:
 
     def translate_elements(
         self,
-        elements: Iterable[Element],
+        tasks: Iterable[TranslationTask[T]],
         interrupt_source_text_segments: Callable[[Iterable[TextSegment]], Iterable[TextSegment]] | None = None,
         interrupt_translated_text_segments: Callable[[Iterable[TextSegment]], Iterable[TextSegment]] | None = None,
         interrupt_block_element: Callable[[Element], Element] | None = None,
         on_fill_failed: Callable[[FillFailedEvent], None] | None = None,
-    ) -> Generator[Element, None, None]:
+    ) -> Generator[tuple[Element, T], None, None]:
+        element2task: dict[int, TranslationTask[T]] = {}
         callbacks = warp_callbacks(
             interrupt_source_text_segments=interrupt_source_text_segments,
             interrupt_translated_text_segments=interrupt_translated_text_segments,
             interrupt_block_element=interrupt_block_element,
             on_fill_failed=on_fill_failed,
         )
+
+        def generate_elements():
+            for task in tasks:
+                element2task[id(task.element)] = task
+                yield task.element
+
         for element, mappings in self._stream_mapper.map_stream(
-            elements=iter(elements),
+            elements=generate_elements(),
             callbacks=callbacks,
             map=lambda inline_segments: self._translate_inline_segments(
                 inline_segments=inline_segments,
                 callbacks=callbacks,
             ),
         ):
-            yield submit_text_segments(
-                element=element,
-                mappings=mappings,
-            )
+            task = element2task.get(id(element), None)
+            if task:
+                translated_element = submit(
+                    element=element,
+                    action=task.action,
+                    mappings=mappings,
+                )
+                yield translated_element, task.payload
 
     def _translate_inline_segments(
         self,

{epub_translator-0.1.3.dist-info → epub_translator-0.1.5.dist-info}/METADATA

@@ -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.dist-info → epub_translator-0.1.5.dist-info}/RECORD

@@ -1,4 +1,4 @@
-epub_translator/__init__.py,sha256=2FZPJyQdTgy_X7oOCxDpSqCZCGEcFqlulmhztLWuCIk,158
+epub_translator/__init__.py,sha256=m2uTGNmBmZhRWQjjYQ1TVrjOuFXJhzQnuuTOq5-t29U,234
 epub_translator/data/fill.jinja,sha256=zSytA8Vhp2i6YBZ09F1z9iPJq1-jUaiphoXqTNZwnvo,6964
 epub_translator/data/mmltex/README.md,sha256=wwhe5yW1U_7_YZIFKnQVnCOmUl7Mu3gsr3lNnDSJ5Qs,2953
 epub_translator/data/mmltex/cmarkup.xsl,sha256=DkhimAATM0XSCfVOfY41-qTPoddqzOHjZ00Pynr4zQE,37707
@@ -25,20 +25,21 @@ epub_translator/llm/error.py,sha256=4efAIQL14DFSvAnSTUfgdAbZRqaWBqOfUGsSfvxa5zM,
 epub_translator/llm/executor.py,sha256=A0IjQ-s9wBJuhAZAAydneb9zBXWnu2J9inR2Q8F-GDE,5533
 epub_translator/llm/increasable.py,sha256=8XkKeI1hiHlpMHj8dQ4fW0BkViSx4hH8QfbQsy-5SDw,1297
 epub_translator/llm/types.py,sha256=c-dMAIvlG4R3la3mUTWEw5xei-sIYKmQeBja7mirxcI,219
+epub_translator/punctuation.py,sha256=Yrf3b_Pl36FPBaK96LR-EBjnztlcZZTWLSNaYoWIUSc,812
 epub_translator/segment/__init__.py,sha256=UYTv_IKQbEB0DzhFeiuqCvjoJLvB-7XRwlaFS90KmIw,573
 epub_translator/segment/block_segment.py,sha256=psNKA_HMIcwZtoug8AtnAcV9_mQ2WXLnXqFsekHzt2g,4570
 epub_translator/segment/common.py,sha256=gGWYQaJ0tGnWCuF1me9TOo-Q_DrZVakCu2patyFIOs0,714
 epub_translator/segment/inline_segment.py,sha256=_ZgSlZmGxzIvaPs01hreoUfnaXz8Yq7naksT34dGfds,14221
-epub_translator/segment/text_segment.py,sha256=qKp646lAqsrI7CP7KYyXgRD2bY0dCR78i6TMBCzklrM,7614
+epub_translator/segment/text_segment.py,sha256=Fos3tTuTcpnm-NmqPftzqov1_Rwr57PBv8AIgjKNYcg,6389
 epub_translator/segment/utils.py,sha256=qMqUt33pDRN5Tnuydkodzu2gaQrwTzAnQmXpDuHen1o,1036
 epub_translator/serial/__init__.py,sha256=b3IMVmWcUwEqHKcGmey88b057pyz5ct946CaUZi4LB4,67
 epub_translator/serial/chunk.py,sha256=FrTaHikVOd6bLYumnEriTaAQ_DIDLjHm16gh-wBVR9k,1495
 epub_translator/serial/segment.py,sha256=uEz-ke1KcYrON-68FaUEzMG2CzHlMjvbC11F3ZT4yH0,446
 epub_translator/serial/splitter.py,sha256=Nq0sxPXos8ez7QBG01sOKjnYKbeBWUBHflZGtqenVm8,1726
 epub_translator/template.py,sha256=0CqRmj3nTtPshw0NmTr2ECqelops2MMyX94fMrE-HKs,1587
-epub_translator/translator.py,sha256=Uy1dRBPA9hoNh3BE40M2XukK2VvcWRCvMvGwvhQtIaA,6212
+epub_translator/translator.py,sha256=SL0Qh49QaZD3bKKkf5xM0hF2MkPqzxKO8uyo8rn9wTQ,6421
 epub_translator/utils.py,sha256=BfZWrYjzDNQ4cFrgvRNzd4i1CKLtPxS8Z4LBHhqEV78,914
-epub_translator/xml/__init__.py,sha256=pxSRKPBQ7D8BCIzXceSad_1MFgN1Dou0BZz9trK47wU,138
+epub_translator/xml/__init__.py,sha256=1sBLICHtNNw0UNMOXCZzrZ7uGfOwnPf_m4MmmMNzakY,160
 epub_translator/xml/const.py,sha256=Re2TYmpwG7-jVVgSq3R_K-uYhvAYzcXcRmLFkwCPD9Y,19
 epub_translator/xml/deduplication.py,sha256=TaMbzeA70VvUQV0X1wcQFVbuMEPJUtj9Hq6iWlUmtAQ,1152
 epub_translator/xml/firendly/__init__.py,sha256=I5jhnhFWoHvojLsYXH4jfR4Gi8lKFZ3yQ56ze5hEe1M,74
@@ -47,20 +48,21 @@ epub_translator/xml/firendly/encoder.py,sha256=evjvw6oE-oCud44IsJ-YZVHn6dtUzjNYX
 epub_translator/xml/firendly/parser.py,sha256=QlMHA0nfPJbNyx6IwRFrYVw7okuvzDB42NXCauIFV-o,6560
 epub_translator/xml/firendly/tag.py,sha256=ahaGoYttuAlnFxLFFgTV51KUZSpUiHho-COZX14nxN8,3308
 epub_translator/xml/firendly/transform.py,sha256=5tG1MJmzrXIR_Z5gmRxwcoKvXBzJBVH0ELeaRsG-8w0,1201
+epub_translator/xml/inline.py,sha256=mwFho6wq2gYWmWcg5Cw6OQeteV-a-i6X9OE63fzblpE,1274
 epub_translator/xml/self_closing.py,sha256=41ofGUdss9yU51IVwI4It6hKfzh8YcxIR_j-ohD19LE,5240
 epub_translator/xml/utils.py,sha256=7tQ6L5P0_JXhxONeG64hEeeL5mKjA6NKS1H1Q9B1Cac,1062
 epub_translator/xml/xml.py,sha256=qQ5Wk1-KVVHE4TX25zGOR7fINsGkXnoq-qyKKNl5no4,1675
 epub_translator/xml/xml_like.py,sha256=jBK4UUgXXWRYnfYlCH1MUAjGHWBQAbUj8HsYqvTTWvA,8890
 epub_translator/xml_interrupter.py,sha256=IGLATr7zTIdhE54Gnroab4Xu_vLJ7kzPiQgk7WMXKTc,7403
-epub_translator/xml_translator/__init__.py,sha256=7aswnFGtuj97l7RQd4ka976WCKC7OPs2gFnJFdS74Ug,77
+epub_translator/xml_translator/__init__.py,sha256=lqts1mJL_WfojDnMAQ5OM7TbT6u9X3H-X4C_avHzvXM,128
 epub_translator/xml_translator/callbacks.py,sha256=IoZrsaivd2W76cHFupwv6auVxgEWHcBN2MHQJYcWoJ8,1324
 epub_translator/xml_translator/common.py,sha256=hSPptgPp7j6dm47imELB5DgmEbzTEyJD6WEeELOOc50,38
 epub_translator/xml_translator/hill_climbing.py,sha256=1jvilOkTLzwljJA4Nrel8yU2XGvOXpueUJTK7RAp-XY,4272
 epub_translator/xml_translator/stream_mapper.py,sha256=tbMc2vyPUn9zEkJZ7-OVYuKaYyn2pPPwjcAdQ8HLzNs,10179
-epub_translator/xml_translator/submitter.py,sha256=Ihp6DvvVMLNZLJkRccYppt_2I2CM7wvkkSAam9B2o2s,2268
-epub_translator/xml_translator/translator.py,sha256=3Lu56vRkAbbnsWK5fOYkVoO-7b6TXCrFYSVYLOjqhw0,9169
+epub_translator/xml_translator/submitter.py,sha256=6PGQTnEcOgL3zseDpSzDmU5d9Eg3eO5OfPIGmQp2DVY,14155
+epub_translator/xml_translator/translator.py,sha256=eIvniqKtNoqFFvfvxK4oA-W02y5ZTpmPQ8wFAJlvOUU,9752
 epub_translator/xml_translator/validation.py,sha256=-OKlSZuD__sjAiEpGAO93YQme4ZDSPmoPjRsAMOCEjc,16668
-epub_translator-0.1.3.dist-info/LICENSE,sha256=5RF32sL3LtMOJIErdDKp1ZEYPGXS8WPpsiSz_jMBnGI,1066
-epub_translator-0.1.3.dist-info/METADATA,sha256=ruyJKZI669xCDIYL6YKoc8ojBsqbO_7Ebe15KkTjLS0,11699
-epub_translator-0.1.3.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-epub_translator-0.1.3.dist-info/RECORD,,
+epub_translator-0.1.5.dist-info/LICENSE,sha256=5RF32sL3LtMOJIErdDKp1ZEYPGXS8WPpsiSz_jMBnGI,1066
+epub_translator-0.1.5.dist-info/METADATA,sha256=IT5MBdl68pICDYmk5tn3CwvdnZ5QxlVoaSzw-VhKf3c,14603
+epub_translator-0.1.5.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+epub_translator-0.1.5.dist-info/RECORD,,