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

epub_translator/translator.py

@@ -1,214 +1,178 @@
 from collections.abc import Callable
+from dataclasses import dataclass
+from enum import Enum, auto
+from importlib.metadata import version as get_package_version
+from os import PathLike
 from pathlib import Path
-from xml.etree.ElementTree import Element
 
-from .epub import Placeholder, Zip, is_placeholder_tag, read_toc, search_spine_paths, write_toc
-from .epub.common import find_opf_path
+from .epub import (
+    Zip,
+    read_metadata,
+    read_toc,
+    search_spine_paths,
+    write_metadata,
+    write_toc,
+)
+from .epub_transcode import decode_metadata, decode_toc_list, encode_metadata, encode_toc_list
 from .llm import LLM
-from .xml import XMLLikeNode, deduplicate_ids_in_element, find_first, plain_text
-from .xml_translator import XMLGroupContext, XMLTranslator, submit_text_segments
+from .xml import XMLLikeNode, deduplicate_ids_in_element, find_first
+from .xml_interrupter import XMLInterrupter
+from .xml_translator import FillFailedEvent, XMLTranslator
+
+
+class _ElementType(Enum):
+    TOC = auto()
+    METADATA = auto()
+    CHAPTER = auto()
+
+
+@dataclass
+class _ElementContext:
+    element_type: _ElementType
+    chapter_data: tuple[Path, XMLLikeNode] | None = None
 
 
 def translate(
-    llm: LLM,
-    source_path: Path,
-    target_path: Path,
+    source_path: PathLike | str,
+    target_path: PathLike | str,
     target_language: str,
     user_prompt: str | None = None,
     max_retries: int = 5,
     max_group_tokens: int = 1200,
+    llm: LLM | None = None,
+    translation_llm: LLM | None = None,
+    fill_llm: LLM | None = None,
     on_progress: Callable[[float], None] | None = None,
+    on_fill_failed: Callable[[FillFailedEvent], None] | None = None,
 ) -> None:
+    translation_llm = translation_llm or llm
+    fill_llm = fill_llm or llm
+    if translation_llm is None:
+        raise ValueError("Either translation_llm or llm must be provided")
+    if fill_llm is None:
+        raise ValueError("Either fill_llm or llm must be provided")
+
     translator = XMLTranslator(
-        llm=llm,
+        translation_llm=translation_llm,
+        fill_llm=fill_llm,
         target_language=target_language,
         user_prompt=user_prompt,
         ignore_translated_error=False,
         max_retries=max_retries,
         max_fill_displaying_errors=10,
-        group_context=XMLGroupContext(
-            encoding=llm.encoding,
-            max_group_tokens=max_group_tokens,
-        ),
+        max_group_tokens=max_group_tokens,
+        cache_seed_content=f"{_get_version()}:{target_language}",
     )
-    with Zip(source_path, target_path) as zip:
-        # Progress distribution: TOC 3%, metadata 2%, chapters 95%
-        TOC_PROGRESS = 0.03
-        METADATA_PROGRESS = 0.02
-        CHAPTERS_PROGRESS = 0.95
-
-        # Count total chapters for progress calculation (lightweight, no content loading)
-        total_chapters = _count_chapters(zip)
-        chapter_progress_step = CHAPTERS_PROGRESS / total_chapters if total_chapters > 0 else 0
-
+    with Zip(
+        source_path=Path(source_path).resolve(),
+        target_path=Path(target_path).resolve(),
+    ) as zip:
+        # mimetype should be the first file in the EPUB ZIP
+        zip.migrate(Path("mimetype"))
+
+        total_chapters = sum(1 for _, _ in search_spine_paths(zip))
+        toc_list = read_toc(zip)
+        metadata_fields = read_metadata(zip)
+
+        # Calculate weights: TOC (5%), Metadata (5%), Chapters (90%)
+        toc_has_items = len(toc_list) > 0
+        metadata_has_items = len(metadata_fields) > 0
+        total_items = (1 if toc_has_items else 0) + (1 if metadata_has_items else 0) + total_chapters
+
+        if total_items == 0:
+            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
 
-        # Translate TOC
-        _translate_toc(translator, zip)
-        current_progress += TOC_PROGRESS
-        if on_progress:
-            on_progress(current_progress)
-
-        # Translate metadata
-        _translate_metadata(translator, zip)
-        current_progress += METADATA_PROGRESS
-        if on_progress:
-            on_progress(current_progress)
-
-        # Translate chapters
-        processed_chapters = 0
-        for element, text_segments, (chapter_path, xml, placeholder) in translator.translate_to_text_segments(
-            items=_search_chapter_items(zip),
+        for translated_elem 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(
+                zip=zip,
+                toc_list=toc_list,
+                metadata_fields=metadata_fields,
+                element_contexts=element_contexts,
+            ),
         ):
-            submit_text_segments(
-                element=element,
-                text_segments=(
-                    segment
-                    for segment in text_segments
-                    if not any(is_placeholder_tag(e.tag) for e in segment.parent_stack)
-                ),
-            )
-            placeholder.recover()
-            deduplicate_ids_in_element(xml.element)
-            with zip.replace(chapter_path) as target_file:
-                xml.save(target_file)
-
-            # Update progress after each chapter
-            processed_chapters += 1
-            current_progress = TOC_PROGRESS + METADATA_PROGRESS + (processed_chapters * chapter_progress_step)
-            if on_progress:
-                on_progress(current_progress)
-
-
-def _translate_toc(translator: XMLTranslator, zip: Zip):
-    """Translate TOC (Table of Contents) titles."""
-    toc_list = read_toc(zip)
-    if not toc_list:
-        return
-
-    # Collect all titles recursively
-    titles_to_translate: list[str] = []
-
-    def collect_titles(items):
-        for item in items:
-            titles_to_translate.append(item.title)
-            if item.children:
-                collect_titles(item.children)
-
-    collect_titles(toc_list)
-
-    # Create XML elements for translation
-    elements_to_translate = Element("toc")
-    elements_to_translate.extend(_create_text_element(title) for title in titles_to_translate)
-
-    # Translate all titles at once
-    translated_element = translator.translate_to_element(elements_to_translate)
-
-    # Extract translated texts
-    from builtins import zip as builtin_zip
-
-    translated_titles = [
-        plain_text(elem) if elem is not None else original
-        for elem, original in builtin_zip(translated_element, titles_to_translate)
-    ]
-
-    # Fill back translated titles
-    title_index = 0
-
-    def fill_titles(items):
-        nonlocal title_index
-        for item in items:
-            item.title = translated_titles[title_index]
-            title_index += 1
-            if item.children:
-                fill_titles(item.children)
-
-    fill_titles(toc_list)
-
-    # Write back the translated TOC
-    write_toc(zip, toc_list)
-
-
-def _translate_metadata(translator: XMLTranslator, zip: Zip):
-    """Translate metadata fields in OPF file."""
-    opf_path = find_opf_path(zip)
-
-    with zip.read(opf_path) as f:
-        xml = XMLLikeNode(f)
-
-    # Find metadata element
-    metadata_elem = None
-    for child in xml.element:
-        if child.tag.endswith("metadata"):
-            metadata_elem = child
-            break
-
-    if metadata_elem is None:
-        return
-
-    # Collect metadata fields to translate
-    # Skip fields that should not be translated
-    skip_fields = {
-        "language",
-        "identifier",
-        "date",
-        "meta",
-        "contributor",  # Usually technical information
-    }
-
-    fields_to_translate: list[tuple[Element, str]] = []
-
-    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_to_translate.append((elem, elem.text.strip()))
-
-    if not fields_to_translate:
-        return
-
-    # Create XML elements for translation
-    elements_to_translate = Element("metadata")
-    elements_to_translate.extend(_create_text_element(text) for _, text in fields_to_translate)
-
-    # Translate all metadata at once
-    translated_element = translator.translate_to_element(elements_to_translate)
-
-    # Fill back translated texts
-    from builtins import zip as builtin_zip
-
-    for (elem, _), translated_elem in builtin_zip(fields_to_translate, translated_element, strict=True):
-        if translated_elem is not None:
-            translated_text = plain_text(translated_elem)
-            if translated_text:
-                elem.text = translated_text
-
-    # Write back the modified OPF file
-    with zip.replace(opf_path) as f:
-        xml.save(f)
-
-
-def _count_chapters(zip: Zip) -> int:
-    """Count total chapters without loading content (lightweight)."""
-    return sum(1 for _ in search_spine_paths(zip))
-
-
-def _search_chapter_items(zip: Zip):
-    for chapter_path in search_spine_paths(zip):
+            elem_id = id(translated_elem)
+            context = element_contexts.pop(elem_id, None)
+
+            if context is None:
+                continue
+
+            if context.element_type == _ElementType.TOC:
+                decoded_toc = decode_toc_list(translated_elem)
+                write_toc(zip, decoded_toc)
+
+                current_progress += toc_weight
+                if on_progress:
+                    on_progress(current_progress)
+
+            elif context.element_type == _ElementType.METADATA:
+                decoded_metadata = decode_metadata(translated_elem)
+                write_metadata(zip, decoded_metadata)
+
+                current_progress += metadata_weight
+                if on_progress:
+                    on_progress(current_progress)
+
+            elif context.element_type == _ElementType.CHAPTER:
+                if context.chapter_data is not None:
+                    chapter_path, xml = context.chapter_data
+                    deduplicate_ids_in_element(xml.element)
+                    with zip.replace(chapter_path) as target_file:
+                        xml.save(target_file)
+
+                current_progress += progress_per_chapter
+                if on_progress:
+                    on_progress(current_progress)
+
+
+def _generate_elements_from_book(
+    zip: Zip,
+    toc_list: list,
+    metadata_fields: list,
+    element_contexts: dict[int, _ElementContext],
+):
+    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
+
+    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
+
+    for chapter_path, media_type in search_spine_paths(zip):
         with zip.read(chapter_path) as chapter_file:
             xml = XMLLikeNode(
                 file=chapter_file,
-                is_html_like=chapter_path.suffix.lower() in (".html", ".htm"),
+                is_html_like=(media_type == "text/html"),
             )
         body_element = find_first(xml.element, "body")
         if body_element is not None:
-            placeholder = Placeholder(body_element)
-            yield body_element, (chapter_path, xml, placeholder)
+            elem_id = id(body_element)
+            element_contexts[elem_id] = _ElementContext(
+                element_type=_ElementType.CHAPTER,
+                chapter_data=(chapter_path, xml),
+            )
+            yield body_element
 
 
-def _create_text_element(text: str) -> Element:
-    elem = Element("text")
-    elem.text = text
-    return elem
+def _get_version() -> str:
+    try:
+        return get_package_version("epub-translator")
+    except Exception:
+        return "development"

epub_translator/utils.py

@@ -1,7 +1,40 @@
 import re
+from collections.abc import Iterable
+from typing import TypeVar
+
+K = TypeVar("K")
+T = TypeVar("T")
 
 _WHITESPACE_PATTERN = re.compile(r"\s+")
 
 
 def normalize_whitespace(text: str) -> str:
     return _WHITESPACE_PATTERN.sub(" ", text)
+
+
+def is_the_same(elements: Iterable[T]) -> bool:
+    iterator = iter(elements)
+    try:
+        first_element = next(iterator)
+    except StopIteration:
+        return True
+
+    for element in iterator:
+        if element != first_element:
+            return False
+    return True
+
+
+def nest(items: Iterable[tuple[K, T]]) -> dict[K, list[T]]:
+    nested_dict: dict[K, list[T]] = {}
+    for key, value in items:
+        ensure_list(nested_dict, key).append(value)
+    return nested_dict
+
+
+def ensure_list(target: dict[K, list[T]], key: K) -> list[T]:
+    value = target.get(key, None)
+    if value is None:
+        value = []
+        target[key] = value
+    return value

epub_translator/xml/__init__.py

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

epub_translator/xml/const.py

@@ -0,0 +1 @@
+ID_KEY: str = "id"

epub_translator/xml/deduplication.py

@@ -1,8 +1,8 @@
 from xml.etree.ElementTree import Element
 
+from .const import ID_KEY
 from .xml import iter_with_stack
 
-_ID_KEY = "id"
 _SUFFIX = "__translated"
 
 
@@ -11,9 +11,9 @@ def deduplicate_ids_in_element(element: Element) -> Element:
     original_id_count: dict[str, int] = {}
 
     for _, sub_element in iter_with_stack(element):
-        if _ID_KEY not in sub_element.attrib:
+        if ID_KEY not in sub_element.attrib:
             continue
-        original_id = sub_element.attrib[_ID_KEY]
+        original_id = sub_element.attrib[ID_KEY]
 
         if original_id not in seen_ids:
             seen_ids.add(original_id)

epub_translator/xml/self_closing.py

@@ -0,0 +1,182 @@
+import re
+
+# Some non-standard EPUB generators use HTML-style tags without self-closing syntax
+# We need to convert them to XML-compatible format before parsing
+# These are HTML5 void elements that must be self-closing in XHTML
+_VOID_TAGS = (
+    "area",
+    "base",
+    "br",
+    "col",
+    "embed",
+    "hr",
+    "img",
+    "input",
+    "link",
+    "meta",
+    "param",
+    "source",
+    "track",
+    "wbr",
+)
+
+
+def self_close_void_elements(xml_content: str) -> str:
+    """
+    Convert void HTML elements to self-closing format for XML parsing.
+
+    This function handles non-standard HTML where void elements are not self-closed.
+    For illegal cases like <meta>content</meta>, the content is removed.
+
+    Args:
+        xml_content: HTML/XHTML content string
+
+    Returns:
+        Content with void elements in self-closing format
+
+    Example:
+        <meta charset="utf-8"> → <meta charset="utf-8" />
+        <br> → <br />
+        <meta>illegal</meta> → <meta />
+    """
+    for tag in _VOID_TAGS:
+        xml_content = _fix_void_element(xml_content, tag)
+    return xml_content
+
+
+def _fix_void_element(content: str, tag_name: str) -> str:
+    """
+    Fix a specific void element in the content.
+
+    Strategy:
+    1. Find <tag ...> (not already self-closed)
+    2. Check if there's a matching </tag>
+    3. If yes, remove everything between them and make it self-closing
+    4. If no, just make the opening tag self-closing
+    """
+    result = []
+    pos = 0
+
+    while pos < len(content):
+        tag_start = content.find(f"<{tag_name}", pos)
+        if tag_start == -1:
+            result.append(content[pos:])
+            break
+
+        # Verify it's a complete tag match (not a prefix like <br matching <brain>)
+        # The character after tag_name must be >, /, or whitespace
+        check_pos = tag_start + len(f"<{tag_name}")
+        if check_pos < len(content):
+            next_char = content[check_pos]
+            if next_char not in (">", "/", " ", "\t", "\n", "\r"):
+                result.append(content[pos:check_pos])
+                pos = check_pos
+                continue
+
+        result.append(content[pos:tag_start])
+        tag_end = _find_tag_end(content, tag_start)
+        if tag_end == -1:
+            result.append(content[tag_start:])
+            break
+
+        opening_tag = content[tag_start : tag_end + 1]
+
+        if opening_tag.rstrip().endswith("/>"):
+            result.append(opening_tag)
+            pos = tag_end + 1
+            continue
+
+        if not opening_tag.endswith(">"):
+            result.append(opening_tag)
+            pos = tag_end + 1
+            continue
+
+        closing_tag = f"</{tag_name}>"
+        closing_pos = content.find(closing_tag, tag_end + 1)
+
+        if closing_pos != -1:
+            attrs_part = opening_tag[len(f"<{tag_name}") : -1].rstrip()
+            if attrs_part:
+                result.append(f"<{tag_name}{attrs_part} />")
+            else:
+                result.append(f"<{tag_name} />")
+            pos = closing_pos + len(closing_tag)
+        else:
+            attrs_part = opening_tag[len(f"<{tag_name}") : -1].rstrip()
+            if attrs_part:
+                result.append(f"<{tag_name}{attrs_part} />")
+            else:
+                result.append(f"<{tag_name} />")
+            pos = tag_end + 1
+
+    return "".join(result)
+
+
+def _find_tag_end(content: str, start_pos: int) -> int:
+    """
+    Find the end of an HTML tag (the position of >).
+
+    Handles quotes: ignores > inside quoted attribute values.
+    """
+    pos = start_pos
+    in_quote = None  # None, '"', or "'"
+
+    while pos < len(content):
+        char = content[pos]
+
+        if in_quote:
+            if char == in_quote:
+                if pos > 0 and content[pos - 1] == "\\":
+                    pos += 1
+                    continue
+                else:
+                    in_quote = None
+        else:
+            if char in ('"', "'"):
+                in_quote = char
+            elif char == ">":
+                return pos
+
+        pos += 1
+
+    return -1  # Not found
+
+
+# For saving: match self-closing tags like <br /> or <br/>
+# Capture tag name and everything between tag name and />
+_VOID_TAG_CLOSE_PATTERN = re.compile(r"<(" + "|".join(_VOID_TAGS) + r")([^>]*?)\s*/>")
+
+
+def unclose_void_elements(xml_content: str) -> str:
+    """
+    Convert void elements from self-closing to unclosed format for HTML compatibility.
+
+    Transforms self-closed void elements like <br /> back to <br> for
+    compatibility with HTML parsers that don't support XHTML syntax.
+    Used only for text/html media type files.
+
+    Args:
+        xml_content: HTML/XHTML content string
+
+    Returns:
+        Content with void elements in unclosed format
+
+    Example:
+        <meta charset="utf-8" /> → <meta charset="utf-8">
+        <br /> → <br>
+        <img src="test.png" /> → <img src="test.png">
+    """
+
+    def replacer(m: re.Match):
+        tag_name = m.group(1)
+        attrs = m.group(2).rstrip()  # Remove trailing whitespace
+        if attrs:
+            return f"<{tag_name}{attrs}>"
+        else:
+            return f"<{tag_name}>"
+
+    return re.sub(
+        pattern=_VOID_TAG_CLOSE_PATTERN,
+        repl=replacer,
+        string=xml_content,
+    )

epub_translator/xml/utils.py

@@ -0,0 +1,42 @@
+from collections.abc import Generator
+from xml.etree.ElementTree import Element
+
+from ..utils import normalize_whitespace
+from .const import ID_KEY
+
+
+def normalize_text_in_element(text: str | None) -> str | None:
+    if text is None:
+        return None
+    text = normalize_whitespace(text)
+    if not text.strip():
+        return None
+    return text
+
+
+def append_text_in_element(origin_text: str | None, append_text: str) -> str:
+    if origin_text is None:
+        return append_text
+    else:
+        return origin_text + append_text
+
+
+def index_of_parent(parent: Element, checked_element: Element) -> int:
+    for i, child in enumerate(parent):
+        if child == checked_element:
+            return i
+    raise ValueError("Element not found in parent.")
+
+
+def expand_left_element_texts(element: Element) -> Generator[str, None, None]:
+    yield "<"
+    yield element.tag
+    yield " "
+    yield ID_KEY
+    yield '="99">'
+
+
+def expand_right_element_texts(element: Element) -> Generator[str, None, None]:
+    yield "</"
+    yield element.tag
+    yield ">"

epub_translator/xml/xml.py

@@ -12,6 +12,13 @@ def find_first(element: Element, tag: str) -> Element | None:
     return None
 
 
+def index_in_parent(parent: Element, element: Element) -> int | None:
+    for i, child in enumerate(parent):
+        if child is element:
+            return i
+    return None
+
+
 def iter_with_stack(element: Element) -> Generator[tuple[list[Element], Element], None, None]:
     """先序遍历：yield parent_path, element"""
     stack: list[list[Element]] = [[element]]