epub-translator 0.1.7__py3-none-any.whl → 0.1.9__py3-none-any.whl

epub_translator/epub/__init__.py

@@ -1,4 +1,4 @@
-from .metadata import read_metadata, write_metadata
+from .metadata import MetadataContext, read_metadata, write_metadata
 from .spines import search_spine_paths
-from .toc import Toc, read_toc, write_toc
+from .toc import Toc, TocContext, read_toc, write_toc
 from .zip import Zip

epub_translator/epub/metadata.py

@@ -1,91 +1,63 @@
 from dataclasses import dataclass
+from pathlib import Path
 
+from ..xml import XMLLikeNode
 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
-}
+@dataclass
+class MetadataContext:
+    opf_path: Path  # OPF 文件路径
+    xml_node: XMLLikeNode  # XMLLikeNode 对象，保留原始文件信息
+
 
+SKIP_FIELDS = frozenset(
+    (
+        "language",
+        "identifier",
+        "date",
+        "meta",
+        "contributor",  # Usually technical information
+    )
+)
 
-def read_metadata(zip: Zip) -> list[MetadataField]:
-    """
-    从 EPUB 的 OPF 文件中读取所有可翻译的元数据字段。
 
-    返回包含标签名和文本内容的列表。
-    自动过滤掉不应该翻译的字段（language, identifier, date, meta, contributor 等）。
-    """
+def read_metadata(zip: Zip) -> tuple[list[MetadataField], MetadataContext]:
     opf_path = find_opf_path(zip)
 
     with zip.read(opf_path) as f:
-        content = f.read()
+        xml_node = XMLLikeNode(f, is_html_like=False)
 
-    from xml.etree import ElementTree as ET
-
-    root = ET.fromstring(content)
-
-    # Find metadata element
     metadata_elem = None
-    for child in root:
+    for child in xml_node.element:
         if child.tag.endswith("metadata"):
             metadata_elem = child
             break
 
     if metadata_elem is None:
-        return []
+        context = MetadataContext(opf_path=opf_path, xml_node=xml_node)
+        return [], context
 
-    # 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
+        tag_name = elem.tag
         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
+    context = MetadataContext(opf_path=opf_path, xml_node=xml_node)
+    return fields, context
 
 
-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
+def write_metadata(zip: Zip, fields: list[MetadataField], context: MetadataContext) -> None:
     metadata_elem = None
-    for child in root:
+    for child in context.xml_node.element:
         if child.tag.endswith("metadata"):
             metadata_elem = child
             break
@@ -93,30 +65,21 @@ def write_metadata(zip: Zip, fields: list[MetadataField]) -> None:
     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
+        tag_name = elem.tag
         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)
+    with zip.replace(context.opf_path) as f:
+        context.xml_node.save(f)

epub_translator/epub/toc.py

@@ -3,8 +3,8 @@ from pathlib import Path
 from xml.etree import ElementTree as ET
 from xml.etree.ElementTree import Element
 
-from ..xml.xml import plain_text
-from .common import extract_namespace, find_opf_path, strip_namespace
+from ..xml import XMLLikeNode, plain_text
+from .common import find_opf_path, strip_namespace
 from .zip import Zip
 
 
@@ -41,30 +41,40 @@ class Toc:
         return self.href
 
 
-def read_toc(zip: Zip) -> list[Toc]:
+@dataclass
+class TocContext:
+    version: int
+    toc_path: Path
+    xml_node: XMLLikeNode
+
+
+def read_toc(zip: Zip) -> tuple[list[Toc], TocContext]:
     version = _detect_epub_version(zip)
     toc_path = _find_toc_path(zip, version)
 
     if toc_path is None:
-        return []
+        raise ValueError("Cannot find TOC file in EPUB")
 
-    if version == 2:
-        return _read_ncx_toc(zip, toc_path)
-    else:
-        return _read_nav_toc(zip, toc_path)
+    with zip.read(toc_path) as f:
+        xml_node = XMLLikeNode(f, is_html_like=False)
 
+    if version == 3:
+        toc_list = _read_nav_toc(xml_node.element)
+    else:
+        toc_list = _read_ncx_toc(xml_node.element)
 
-def write_toc(zip: Zip, toc: list[Toc]) -> None:
-    version = _detect_epub_version(zip)
-    toc_path = _find_toc_path(zip, version)
+    context = TocContext(version=version, toc_path=toc_path, xml_node=xml_node)
+    return toc_list, context
 
-    if toc_path is None:
-        raise ValueError("Cannot find TOC file in EPUB")
 
-    if version == 2:
-        _write_ncx_toc(zip, toc_path, toc)
+def write_toc(zip: Zip, toc: list[Toc], context: TocContext) -> None:
+    if context.version == 2:
+        _update_ncx_toc(context.xml_node.element, toc)
     else:
-        _write_nav_toc(zip, toc_path, toc)
+        _update_nav_toc(context.xml_node.element, toc)
+
+    with zip.replace(context.toc_path) as f:
+        context.xml_node.save(f)
 
 
 def _detect_epub_version(zip: Zip) -> int:
@@ -72,8 +82,6 @@ def _detect_epub_version(zip: Zip) -> int:
     with zip.read(opf_path) as f:
         content = f.read()
         root = ET.fromstring(content)
-
-        # 检查 package 元素的 version 属性
         version_str = root.get("version", "2.0")
 
         if version_str.startswith("3"):
@@ -89,7 +97,7 @@ def _find_toc_path(zip: Zip, version: int) -> Path | None:
     with zip.read(opf_path) as f:
         content = f.read()
         root = ET.fromstring(content)
-        strip_namespace(root)  # 移除命名空间前缀以简化 XPath
+        strip_namespace(root)
 
         manifest = root.find(".//manifest")
         if manifest is None:
@@ -115,23 +123,18 @@ def _find_toc_path(zip: Zip, version: int) -> Path | None:
         return None
 
 
-def _read_ncx_toc(zip: Zip, ncx_path: Path) -> list[Toc]:
-    with zip.read(ncx_path) as f:
-        content = f.read()
-        root = ET.fromstring(content)
-        strip_namespace(root)  # 移除命名空间前缀以简化 XPath
-
-        nav_map = root.find(".//navMap")
-        if nav_map is None:
-            return []
+def _read_ncx_toc(root: Element) -> list[Toc]:
+    nav_map = root.find(".//navMap")
+    if nav_map is None:
+        return []
 
-        result = []
-        for nav_point in nav_map.findall("navPoint"):
-            toc_item = _parse_nav_point(nav_point)
-            if toc_item:
-                result.append(toc_item)
+    result = []
+    for nav_point in nav_map.findall("navPoint"):
+        toc_item = _parse_nav_point(nav_point)
+        if toc_item:
+            result.append(toc_item)
 
-        return result
+    return result
 
 
 def _parse_nav_point(nav_point: Element) -> Toc | None:
@@ -172,18 +175,11 @@ def _parse_nav_point(nav_point: Element) -> Toc | None:
     )
 
 
-def _write_ncx_toc(zip: Zip, ncx_path: Path, toc_list: list[Toc]) -> None:
-    with zip.read(ncx_path) as f:
-        content = f.read()
-        root = ET.fromstring(content)
-        ns = extract_namespace(root.tag)
-        nav_map = root.find(f".//{{{ns}}}navMap" if ns else ".//navMap")
-        if nav_map is None:
-            raise ValueError("Cannot find navMap in NCX file")
-        _update_nav_points(nav_map, toc_list, ns)
-        tree = ET.ElementTree(root)
-        with zip.replace(ncx_path) as out:
-            tree.write(out, encoding="utf-8", xml_declaration=True)
+def _update_ncx_toc(root: Element, toc_list: list[Toc]) -> None:
+    nav_map = root.find(".//navMap")
+    if nav_map is None:
+        raise ValueError("Cannot find navMap in NCX file")
+    _update_nav_points(nav_map, toc_list, None)
 
 
 def _update_nav_points(parent: Element, toc_list: list[Toc], ns: str | None, start_play_order: int = 1) -> int:
@@ -255,34 +251,28 @@ def _create_nav_point(toc: Toc, ns: str | None, play_order: int) -> Element:
     return nav_point
 
 
-def _read_nav_toc(zip: Zip, nav_path: Path) -> list[Toc]:
-    with zip.read(nav_path) as f:
-        content = f.read()
-        root = ET.fromstring(content)
-
-        strip_namespace(root)
-
-        nav_elem = None
-        for nav in root.findall(".//nav"):
-            epub_type = nav.get("{http://www.idpf.org/2007/ops}type") or nav.get("type")
-            if epub_type == "toc":
-                nav_elem = nav
-                break
+def _read_nav_toc(root: Element) -> list[Toc]:
+    nav_elem = None
+    for nav in root.findall(".//nav"):
+        epub_type = nav.get("type")
+        if epub_type == "toc":
+            nav_elem = nav
+            break
 
-        if nav_elem is None:
-            return []
+    if nav_elem is None:
+        return []
 
-        ol = nav_elem.find(".//ol")
-        if ol is None:
-            return []
+    ol = nav_elem.find(".//ol")
+    if ol is None:
+        return []
 
-        result = []
-        for li in ol.findall("li"):
-            toc_item = _parse_nav_li(li)
-            if toc_item:
-                result.append(toc_item)
+    result = []
+    for li in ol.findall("li"):
+        toc_item = _parse_nav_li(li)
+        if toc_item:
+            result.append(toc_item)
 
-        return result
+    return result
 
 
 def _parse_nav_li(li: Element) -> Toc | None:
@@ -331,30 +321,22 @@ def _parse_nav_li(li: Element) -> Toc | None:
     )
 
 
-def _write_nav_toc(zip: Zip, nav_path: Path, toc_list: list[Toc]) -> None:
-    with zip.read(nav_path) as f:
-        content = f.read()
-        root = ET.fromstring(content)
-        ns = extract_namespace(root.tag)
-        nav_elem = None
-        for nav in root.findall(f".//{{{ns}}}nav" if ns else ".//nav"):
-            epub_type = nav.get("{http://www.idpf.org/2007/ops}type") or nav.get("type") or nav.get(f"{{{ns}}}type")
-            if epub_type == "toc":
-                nav_elem = nav
-                break
-
-        if nav_elem is None:
-            raise ValueError("Cannot find nav element with type='toc'")
-
-        ol = nav_elem.find(f".//{{{ns}}}ol" if ns else ".//ol")
-        if ol is None:
-            raise ValueError("Cannot find ol in nav element")
-
-        _update_nav_lis(ol, toc_list, ns)
-
-        tree = ET.ElementTree(root)
-        with zip.replace(nav_path) as out:
-            tree.write(out, encoding="utf-8", xml_declaration=True)
+def _update_nav_toc(root: Element, toc_list: list[Toc]) -> None:
+    nav_elem = None
+    for nav in root.findall(".//nav"):
+        epub_type = nav.get("type")
+        if epub_type == "toc":
+            nav_elem = nav
+            break
+
+    if nav_elem is None:
+        raise ValueError("Cannot find nav element with type='toc'")
+
+    ol = nav_elem.find(".//ol")
+    if ol is None:
+        raise ValueError("Cannot find ol in nav element")
+
+    _update_nav_lis(ol, toc_list, None)
 
 
 def _update_nav_lis(ol: Element, toc_list: list[Toc], ns: str | None) -> None:

epub_translator/llm/core.py

@@ -13,6 +13,7 @@ from ..template import create_env
 from .context import LLMContext
 from .executor import LLMExecutor
 from .increasable import Increasable
+from .statistics import Statistics
 from .types import Message
 
 # Global state for logger filename generation
@@ -44,7 +45,7 @@ class LLM:
         self._temperature: Increasable = Increasable(temperature)
         self._cache_path: Path | None = self._ensure_dir_path(cache_path)
         self._logger_save_path: Path | None = self._ensure_dir_path(log_dir_path)
-
+        self._statistics = Statistics()
         self._executor = LLMExecutor(
             url=url,
             model=model,
@@ -53,12 +54,29 @@ class LLM:
             retry_times=retry_times,
             retry_interval_seconds=retry_interval_seconds,
             create_logger=self._create_logger,
+            statistics=self._statistics,
         )
 
     @property
     def encoding(self) -> Encoding:
         return self._encoding
 
+    @property
+    def total_tokens(self) -> int:
+        return self._statistics.total_tokens
+
+    @property
+    def input_tokens(self) -> int:
+        return self._statistics.input_tokens
+
+    @property
+    def input_cache_tokens(self) -> int:
+        return self._statistics.input_cache_tokens
+
+    @property
+    def output_tokens(self) -> int:
+        return self._statistics.output_tokens
+
     def context(self, cache_seed_content: str | None = None) -> LLMContext:
         return LLMContext(
             executor=self._executor,

epub_translator/llm/executor.py

@@ -7,6 +7,7 @@ from openai import OpenAI
 from openai.types.chat import ChatCompletionMessageParam
 
 from .error import is_retry_error
+from .statistics import Statistics
 from .types import Message, MessageRole
 
 
@@ -20,12 +21,14 @@ class LLMExecutor:
         retry_times: int,
         retry_interval_seconds: float,
         create_logger: Callable[[], Logger | None],
+        statistics: Statistics,
     ) -> None:
         self._model_name: str = model
         self._timeout: float | None = timeout
         self._retry_times: int = retry_times
         self._retry_interval_seconds: float = retry_interval_seconds
         self._create_logger: Callable[[], Logger | None] = create_logger
+        self._statistics = statistics
         self._client = OpenAI(
             api_key=api_key,
             base_url=url,
@@ -156,6 +159,7 @@ class LLMExecutor:
             model=self._model_name,
             messages=messages,
             stream=True,
+            stream_options={"include_usage": True},
             top_p=top_p,
             temperature=temperature,
             max_tokens=max_tokens,
@@ -164,4 +168,5 @@ class LLMExecutor:
         for chunk in stream:
             if chunk.choices and chunk.choices[0].delta.content:
                 buffer.write(chunk.choices[0].delta.content)
+            self._statistics.submit_usage(chunk.usage)
         return buffer.getvalue()

epub_translator/llm/statistics.py

@@ -0,0 +1,25 @@
+from threading import Lock
+
+from openai.types import CompletionUsage
+
+
+class Statistics:
+    def __init__(self) -> None:
+        self._lock = Lock()
+        self.total_tokens = 0
+        self.input_tokens = 0
+        self.input_cache_tokens = 0
+        self.output_tokens = 0
+
+    def submit_usage(self, usage: CompletionUsage | None) -> None:
+        if usage is None:
+            return
+        with self._lock:
+            if usage.total_tokens:
+                self.total_tokens += usage.total_tokens
+            if usage.prompt_tokens:
+                self.input_tokens += usage.prompt_tokens
+            if usage.prompt_tokens_details and usage.prompt_tokens_details.cached_tokens:
+                self.input_cache_tokens += usage.prompt_tokens_details.cached_tokens
+            if usage.completion_tokens:
+                self.output_tokens += usage.completion_tokens

epub_translator/segment/text_segment.py

@@ -4,7 +4,12 @@ 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, is_inline_element, normalize_text_in_element
+from ..xml import (
+    expand_left_element_texts,
+    expand_right_element_texts,
+    is_inline_element,
+    normalize_text_in_element,
+)
 
 
 class TextPosition(Enum):

epub_translator/translation/translator.py

@@ -6,6 +6,8 @@ from os import PathLike
 from pathlib import Path
 
 from ..epub import (
+    MetadataContext,
+    TocContext,
     Zip,
     read_metadata,
     read_toc,
@@ -31,6 +33,8 @@ class _ElementType(Enum):
 class _ElementContext:
     element_type: _ElementType
     chapter_data: tuple[Path, XMLLikeNode] | None = None
+    toc_context: TocContext | None = None
+    metadata_context: MetadataContext | None = None
 
 
 def translate(
@@ -74,8 +78,8 @@ def translate(
         zip.migrate(Path("mimetype"))
 
         total_chapters = sum(1 for _, _ in search_spine_paths(zip))
-        toc_list = read_toc(zip)
-        metadata_fields = read_metadata(zip)
+        toc_list, toc_context = read_toc(zip)
+        metadata_fields, metadata_context = read_metadata(zip)
 
         # Calculate weights: TOC (5%), Metadata (5%), Chapters (90%)
         toc_has_items = len(toc_list) > 0
@@ -101,14 +105,17 @@ def translate(
             tasks=_generate_tasks_from_book(
                 zip=zip,
                 toc_list=toc_list,
+                toc_context=toc_context,
                 metadata_fields=metadata_fields,
+                metadata_context=metadata_context,
                 submit=submit,
             ),
         ):
             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)
+                if context.toc_context is not None:
+                    write_toc(zip, decoded_toc, context.toc_context)
 
                 current_progress += toc_weight
                 if on_progress:
@@ -117,7 +124,8 @@ def translate(
             elif context.element_type == _ElementType.METADATA:
                 translated_elem = unwrap_french_quotes(translated_elem)
                 decoded_metadata = decode_metadata(translated_elem)
-                write_metadata(zip, decoded_metadata)
+                if context.metadata_context is not None:
+                    write_metadata(zip, decoded_metadata, context.metadata_context)
 
                 current_progress += metadata_weight
                 if on_progress:
@@ -138,7 +146,9 @@ def translate(
 def _generate_tasks_from_book(
     zip: Zip,
     toc_list: list,
+    toc_context: TocContext,
     metadata_fields: list,
+    metadata_context: MetadataContext,
     submit: SubmitKind,
 ) -> Generator[TranslationTask[_ElementContext], None, None]:
     head_submit = submit
@@ -149,14 +159,14 @@ def _generate_tasks_from_book(
         yield TranslationTask(
             element=encode_toc_list(toc_list),
             action=head_submit,
-            payload=_ElementContext(element_type=_ElementType.TOC),
+            payload=_ElementContext(element_type=_ElementType.TOC, toc_context=toc_context),
         )
 
     if metadata_fields:
         yield TranslationTask(
             element=encode_metadata(metadata_fields),
             action=head_submit,
-            payload=_ElementContext(element_type=_ElementType.METADATA),
+            payload=_ElementContext(element_type=_ElementType.METADATA, metadata_context=metadata_context),
         )
 
     for chapter_path, media_type in search_spine_paths(zip):

epub_translator/translation/xml_interrupter.py

@@ -6,8 +6,8 @@ from bs4 import BeautifulSoup
 from mathml2latex.mathml import process_mathml
 
 from ..segment import TextSegment, combine_text_segments, find_block_depth
-from ..utils import ensure_list
-from ..xml import clone_element
+from ..utils import ensure_list, normalize_whitespace
+from ..xml import DISPLAY_ATTRIBUTE, clone_element, is_inline_element
 
 _ID_KEY = "__XML_INTERRUPTER_ID"
 _MATH_TAG = "math"
@@ -87,9 +87,9 @@ class XMLInterrupter:
                     _ID_KEY: cast(str, interrupted_element.get(_ID_KEY)),
                 },
             )
-            interrupted_display = interrupted_element.get("display", None)
+            interrupted_display = interrupted_element.get(DISPLAY_ATTRIBUTE, None)
             if interrupted_display is not None:
-                placeholder_element.set("display", interrupted_display)
+                placeholder_element.set(DISPLAY_ATTRIBUTE, interrupted_display)
 
             raw_parent_stack = text_segment.parent_stack[:interrupted_index]
             parent_stack = raw_parent_stack + [placeholder_element]
@@ -159,10 +159,13 @@ class XMLInterrupter:
 
         if latex is None:
             latex = "".join(t.text for t in text_segments)
-        elif math_element.get("display", None) == "inline":
-            latex = f"${latex}$"
+            latex = normalize_whitespace(latex).strip()
         else:
-            latex = f"$${latex}$$"
+            latex = normalize_whitespace(latex).strip()
+            if is_inline_element(math_element):
+                latex = f"${latex}$"
+            else:
+                latex = f"$${latex}$$"
 
         return f" {latex} "
 

epub_translator/xml/const.py

@@ -1 +1,2 @@
 ID_KEY: str = "id"
+DISPLAY_ATTRIBUTE: str = "display"

epub_translator/xml/inline.py

@@ -1,5 +1,7 @@
 from xml.etree.ElementTree import Element
 
+from .const import DISPLAY_ATTRIBUTE
+
 # 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
@@ -105,9 +107,14 @@ _HTML_INLINE_TAGS = frozenset(
 
 
 def is_inline_element(element: Element) -> bool:
-    if element.tag.lower() in _HTML_INLINE_TAGS:
+    tag = element.tag.lower()
+    if tag in _HTML_INLINE_TAGS:
         return True
-    display = element.get("display", None)
-    if display is not None and display.lower() == "inline":
+    display = element.get(DISPLAY_ATTRIBUTE, None)
+    if display is not None:
+        display = display.lower()
+        if display == "inline":
+            return True
+    if tag == "math" and display != "block":
         return True
     return False

epub_translator/xml/self_closing.py

@@ -3,6 +3,8 @@ 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
+# Note: "meta" is excluded because OPF files have <meta property="...">content</meta>
+# which is NOT a void element (different namespace, different rules)
 _VOID_TAGS = (
     "area",
     "base",
@@ -13,7 +15,6 @@ _VOID_TAGS = (
     "img",
     "input",
     "link",
-    "meta",
     "param",
     "source",
     "track",
@@ -26,7 +27,8 @@ 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.
+    Note: "meta" is excluded from processing because EPUB OPF files have
+    <meta property="...">content</meta> which is NOT a void element.
 
     Args:
         xml_content: HTML/XHTML content string
@@ -35,9 +37,8 @@ def self_close_void_elements(xml_content: str) -> str:
         Content with void elements in self-closing format
 
     Example:
-        <meta charset="utf-8"> → <meta charset="utf-8" />
         <br> → <br />
-        <meta>illegal</meta> → <meta />
+        <link rel="stylesheet" href="style.css"> → <link rel="stylesheet" href="style.css" />
     """
     for tag in _VOID_TAGS:
         xml_content = _fix_void_element(xml_content, tag)

epub_translator/xml/xml_like.py

@@ -32,6 +32,25 @@ _ENCODING_PATTERN = re.compile(r'encoding\s*=\s*["\']([^"\']+)["\']', re.IGNOREC
 _FIRST_ELEMENT_PATTERN = re.compile(r"<(?![?!])[a-zA-Z]")
 _NAMESPACE_IN_TAG = re.compile(r"\{([^}]+)\}")
 
+# When an attribute name exists in multiple namespaces (e.g., 'type' in XHTML and EPUB ops),
+# _attr_to_namespace only records ONE namespace per attribute name. During serialization,
+# the global string replacement wrongly adds namespace prefixes to ALL occurrences of that
+# attribute, including ones that should remain unprefixed (e.g., <link type="text/css">).
+#
+# Example problem:
+#   Original file has:
+#     - <link type="text/css">           (no namespace, standard HTML attribute)
+#     - <nav epub:type="toc">             (EPUB ops namespace)
+#   After parsing, _attr_to_namespace records: {'type': 'http://www.idpf.org/2007/ops'}
+#   During serialization, ALL ' type="' get replaced to ' epub:type="', breaking <link>
+#
+# This workaround fixes specific known cases where HTML standard attributes should not
+# be prefixed, even if the same attribute name appears with a namespace elsewhere.
+_STANDARD_HTML_ATTRS = (
+    (re.compile(r'<link([^>]*?) epub:type="'), r'<link\1 type="'),  # <link type="...">
+    (re.compile(r'<link([^>]*?) epub:rel="'), r'<link\1 rel="'),  # <link rel="...">
+)
+
 
 class XMLLikeNode:
     def __init__(self, file: IO[bytes], is_html_like: bool = False) -> None:
@@ -197,10 +216,13 @@ class XMLLikeNode:
                 xml_string = xml_string.replace(f"</{tag_name}>", f"</{prefix}:{tag_name}>")
                 xml_string = xml_string.replace(f"<{tag_name}/>", f"<{prefix}:{tag_name}/>")
 
-        # Similarly for attributes (though less common in EPUB)
         for attr_name, namespace_uri in self._attr_to_namespace.items():
             if namespace_uri not in _ROOT_NAMESPACES:
                 prefix = self._namespaces[namespace_uri]
                 xml_string = xml_string.replace(f' {attr_name}="', f' {prefix}:{attr_name}="')
 
+        # Apply workaround to fix standard HTML attributes (see _STANDARD_HTML_ATTRS comment)
+        for pattern, replacement in _STANDARD_HTML_ATTRS:
+            xml_string = pattern.sub(replacement, xml_string)
+
         return xml_string

{epub_translator-0.1.7.dist-info → epub_translator-0.1.9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: epub-translator
-Version: 0.1.7
+Version: 0.1.9
 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
@@ -46,26 +46,17 @@ Description-Content-Type: text/markdown
 </div>
 
 
-Translate EPUB books using Large Language Models while preserving the original text. The translated content is displayed side-by-side with the original, creating bilingual books perfect for language learning and cross-reference reading.
+Want to read a book in a foreign language without losing the original context? EPUB Translator transforms any EPUB into a bilingual edition with AI-powered translations displayed side-by-side with the original text.
 
-![Translation Effect](./docs/images/translation.png)
+Whether you're learning a new language, conducting academic research, or simply enjoying foreign literature, you get both versions in one book - preserving all formatting, images, and structure.
 
-## Features
+![Translation Effect](./docs/images/translation.png)
 
-- **Bilingual Output**: Preserves original text alongside translations for easy comparison
-- **LLM-Powered**: Leverages large language models for high-quality, context-aware translations
-- **Format Preservation**: Maintains EPUB structure, styles, images, and formatting
-- **Complete Translation**: Translates chapter content, table of contents, and metadata
-- **Progress Tracking**: Monitor translation progress with built-in callbacks
-- **Flexible LLM Support**: Works with any OpenAI-compatible API endpoint
-- **Caching**: Built-in caching for progress recovery when translation fails
+### Online Demo
 
-## Use Cases
+We provide an [online demo platform](https://hub.oomol.com/package/books-translator) where you can try EPUB Translator's bilingual translation capabilities without any installation. Simply upload your EPUB file and get a translated bilingual edition.
 
-- **Language Learning**: Read books in their original language with side-by-side translations
-- **Academic Research**: Access foreign literature with bilingual references
-- **Content Localization**: Prepare books for international audiences
-- **Cross-Cultural Reading**: Enjoy literature while understanding cultural nuances
+[![EPUB Translator Online Demo](docs/images/online-en.png)](https://hub.oomol.com/package/books-translator)
 
 ## Installation
 
@@ -422,6 +413,105 @@ translate(
 
 When using `concurrency > 1`, ensure that any custom callback functions (`on_progress`, `on_fill_failed`) are thread-safe. Built-in callbacks are thread-safe by default.
 
+### Token Usage Monitoring
+
+Track token consumption during translation to monitor API costs and usage:
+
+```python
+from epub_translator import LLM, translate, language, SubmitKind
+
+llm = LLM(
+    key="your-api-key",
+    url="https://api.openai.com/v1",
+    model="gpt-4",
+    token_encoding="o200k_base",
+)
+
+translate(
+    source_path="source.epub",
+    target_path="translated.epub",
+    target_language=language.ENGLISH,
+    submit=SubmitKind.APPEND_BLOCK,
+    llm=llm,
+)
+
+# Access token statistics after translation
+print(f"Total tokens: {llm.total_tokens}")
+print(f"Input tokens: {llm.input_tokens}")
+print(f"Input cache tokens: {llm.input_cache_tokens}")
+print(f"Output tokens: {llm.output_tokens}")
+```
+
+**Available Statistics:**
+
+- `total_tokens` - Total number of tokens used (input + output)
+- `input_tokens` - Number of prompt/input tokens
+- `input_cache_tokens` - Number of cached input tokens (when using prompt caching)
+- `output_tokens` - Number of generated/completion tokens
+
+**Real-time Monitoring:**
+
+You can also monitor token usage in real-time during translation:
+
+```python
+from tqdm import tqdm
+import time
+
+with tqdm(total=100, desc="Translating", unit="%") as pbar:
+    last_progress = 0.0
+    start_time = time.time()
+
+    def on_progress(progress: float):
+        nonlocal last_progress
+        increment = (progress - last_progress) * 100
+        pbar.update(increment)
+        last_progress = progress
+
+        # Update token stats in progress bar
+        pbar.set_postfix({
+            'tokens': llm.total_tokens,
+            'cost_est': f'${llm.total_tokens * 0.00001:.4f}'  # Estimate based on your pricing
+        })
+
+    translate(
+        source_path="source.epub",
+        target_path="translated.epub",
+        target_language=language.ENGLISH,
+        submit=SubmitKind.APPEND_BLOCK,
+        llm=llm,
+        on_progress=on_progress,
+    )
+
+    elapsed = time.time() - start_time
+    print(f"\nTranslation completed in {elapsed:.1f}s")
+    print(f"Total tokens used: {llm.total_tokens:,}")
+    print(f"Average tokens/second: {llm.total_tokens/elapsed:.1f}")
+```
+
+**Dual-LLM Token Tracking:**
+
+When using separate LLMs for translation and filling, each LLM tracks its own statistics:
+
+```python
+translation_llm = LLM(key="...", url="...", model="gpt-4", token_encoding="o200k_base")
+fill_llm = LLM(key="...", url="...", model="gpt-4", token_encoding="o200k_base")
+
+translate(
+    source_path="source.epub",
+    target_path="translated.epub",
+    target_language=language.ENGLISH,
+    submit=SubmitKind.APPEND_BLOCK,
+    translation_llm=translation_llm,
+    fill_llm=fill_llm,
+)
+
+print(f"Translation tokens: {translation_llm.total_tokens}")
+print(f"Fill tokens: {fill_llm.total_tokens}")
+print(f"Combined total: {translation_llm.total_tokens + fill_llm.total_tokens}")
+```
+
+**Note:** Token statistics are cumulative across all API calls made by the LLM instance. The counts only increase and are thread-safe when using concurrent translation.
+
 ## Related Projects
 
 ### PDF Craft

{epub_translator-0.1.7.dist-info → epub_translator-0.1.9.dist-info}/RECORD

@@ -1,25 +1,26 @@
 epub_translator/__init__.py,sha256=JsiOUPpk5k7q8mXIgnRQWdVVnkJww_KDTg7jXsP7_C4,222
 epub_translator/data/fill.jinja,sha256=zSytA8Vhp2i6YBZ09F1z9iPJq1-jUaiphoXqTNZwnvo,6964
 epub_translator/data/translate.jinja,sha256=MVAWvgO9kybEFi0zMiZLEWwuRUL3l8PrwJdsoueQeCs,855
-epub_translator/epub/__init__.py,sha256=aZawPakdkEquL4kRRpyCTdoSQ82l7FGqY4Uw6-ndoGA,154
+epub_translator/epub/__init__.py,sha256=4kIHrFUvFBemqg4lpjOpa9mmvWZGycgWdiQUaJ4JmL4,183
 epub_translator/epub/common.py,sha256=4-SpTe8iot9hMfyXILmlUFvYVNYqPAHL5hn1fr2wgis,1180
 epub_translator/epub/math.py,sha256=-Q2LJQxxjgQZQUe_WlJA9tjzLqgqtw2ZmbGbHsPRp2U,5422
-epub_translator/epub/metadata.py,sha256=DXSimY2iZNBA2juIaKtB-4CHHSYJiDK7PPhfenV4dto,3511
+epub_translator/epub/metadata.py,sha256=Ddhq-kDtYz2yy41ayXtFxEL-_Lsvn-_vf8hm76HUbRE,2387
 epub_translator/epub/spines.py,sha256=bP2IsobZm7zs4z10iXGc9SmgAFSIq9pJc8HE-V0aW9Y,1331
-epub_translator/epub/toc.py,sha256=TKJfyDT4svFkXd6JCNZk2ZEYc9q-5DXnV3zY2UKo8nE,14891
+epub_translator/epub/toc.py,sha256=N-tBR9Pv0FyCWq8swtSI93mCywN7mIXqweDBBmcDYJ8,13815
 epub_translator/epub/zip.py,sha256=-3LI8f-ksgU8xCy28NjBOKyQPE8PhPEUPqIKZE1p8dw,2364
 epub_translator/llm/__init__.py,sha256=YcFYYnXmXyX0RUyC-PDbj5k7Woygp_XOpTI3vDiNSPM,75
 epub_translator/llm/context.py,sha256=8-0UnrZIaNshR_imy_ed_UpOK7H1a6dOsG-boaYOX8k,4186
-epub_translator/llm/core.py,sha256=wQwt6oG68ZN_iQOaytBiPXOC7sI62XII_A4dOHdAt_s,5979
+epub_translator/llm/core.py,sha256=MnToX8Zhr_r4sj9B3s54bclesojQEFarzl0VqHGDKlo,6488
 epub_translator/llm/error.py,sha256=4efAIQL14DFSvAnSTUfgdAbZRqaWBqOfUGsSfvxa5zM,1503
-epub_translator/llm/executor.py,sha256=A0IjQ-s9wBJuhAZAAydneb9zBXWnu2J9inR2Q8F-GDE,5533
+epub_translator/llm/executor.py,sha256=wxgFwWaLmuqAvctO3lcQX4U52aiw7EdaFw9Ut0v-ZzU,5745
 epub_translator/llm/increasable.py,sha256=8XkKeI1hiHlpMHj8dQ4fW0BkViSx4hH8QfbQsy-5SDw,1297
+epub_translator/llm/statistics.py,sha256=BX75qVWJ9aWbMoFtaQzoE8oVCLh7wiHoR06dX-AAl3E,875
 epub_translator/llm/types.py,sha256=c-dMAIvlG4R3la3mUTWEw5xei-sIYKmQeBja7mirxcI,219
 epub_translator/segment/__init__.py,sha256=nCHNaHASElKTbC8HEAQkI1Y12m6kEdX5uJVvVvHKtFg,595
 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=nrRKoJ-vblsNITJeixrCgIOkVQyUXrchMg0XYU_8pLo,14563
-epub_translator/segment/text_segment.py,sha256=DHv8bkBpVYVUI01hOIf9Jdc7D3v7SdbLD1MeL4MUh4U,6267
+epub_translator/segment/text_segment.py,sha256=E_qgPI09sCV_-PsJtgwcloTa0tpOP3wl0pw5gV9dDNY,6288
 epub_translator/segment/utils.py,sha256=_tlIA1I7rYz9_q-oQ5cPZWPmhTObCXjksQzRtX3beXY,636
 epub_translator/serial/__init__.py,sha256=b3IMVmWcUwEqHKcGmey88b057pyz5ct946CaUZi4LB4,67
 epub_translator/serial/chunk.py,sha256=FrTaHikVOd6bLYumnEriTaAQ_DIDLjHm16gh-wBVR9k,1495
@@ -30,11 +31,11 @@ epub_translator/translation/__init__.py,sha256=R0c0ZngocOC-Qczs0a8JYAdAcCu2gv3FL
 epub_translator/translation/epub_transcode.py,sha256=_pRzmQgDrlfsibalkUogVi0F0Qy_uuYfKhZk3nP5pkA,2747
 epub_translator/translation/language.py,sha256=88osG0JNYxOkxBjg5Pm-P0Mhiyxf6GqdxoPW12HW0PE,493
 epub_translator/translation/punctuation.py,sha256=TPCGjEmlAyN3G11VuXdHn-pvUkuWDwWqbTNzw-ij60E,813
-epub_translator/translation/translator.py,sha256=WC4Yqx-ffhxBhqzMAujE_NQG7BsDwgn95UMNG7OkUSo,6487
-epub_translator/translation/xml_interrupter.py,sha256=c0wwfZzGpOkfKJ5v5p-lNgYlcqD0B6i2e6cQq-Tl0lI,8426
+epub_translator/translation/translator.py,sha256=rly6hXwZ0bylV0-5LVeEEHrZSJ6xKaZlEbrjnG4kkOE,7033
+epub_translator/translation/xml_interrupter.py,sha256=7TRGskn_OxRZT5mvKfjL0VMtU2VCgl1d9ElmfhFG0pM,8628
 epub_translator/utils.py,sha256=BfZWrYjzDNQ4cFrgvRNzd4i1CKLtPxS8Z4LBHhqEV78,914
 epub_translator/xml/__init__.py,sha256=qluFTfZYlPmOie8nR2C5O0tZ3UbCQEoEoR-Fq-__79c,160
-epub_translator/xml/const.py,sha256=Re2TYmpwG7-jVVgSq3R_K-uYhvAYzcXcRmLFkwCPD9Y,19
+epub_translator/xml/const.py,sha256=tCdeJfGwH5xgS4uOmR-pXSfyWXGxOHMJyZKE46BVkJU,54
 epub_translator/xml/deduplication.py,sha256=TaMbzeA70VvUQV0X1wcQFVbuMEPJUtj9Hq6iWlUmtAQ,1152
 epub_translator/xml/friendly/__init__.py,sha256=I5jhnhFWoHvojLsYXH4jfR4Gi8lKFZ3yQ56ze5hEe1M,74
 epub_translator/xml/friendly/decoder.py,sha256=xRQ5LnSunmYbba_0oT39oUr86-sLYAHYMUGmlseIu2U,2467
@@ -42,11 +43,11 @@ epub_translator/xml/friendly/encoder.py,sha256=evjvw6oE-oCud44IsJ-YZVHn6dtUzjNYX
 epub_translator/xml/friendly/parser.py,sha256=QlMHA0nfPJbNyx6IwRFrYVw7okuvzDB42NXCauIFV-o,6560
 epub_translator/xml/friendly/tag.py,sha256=ahaGoYttuAlnFxLFFgTV51KUZSpUiHho-COZX14nxN8,3308
 epub_translator/xml/friendly/transform.py,sha256=5tG1MJmzrXIR_Z5gmRxwcoKvXBzJBVH0ELeaRsG-8w0,1201
-epub_translator/xml/inline.py,sha256=fT_zm2NqHraJEwYXBHyqo9XjBFQUWRJO7YHB1rerkAc,2945
-epub_translator/xml/self_closing.py,sha256=41ofGUdss9yU51IVwI4It6hKfzh8YcxIR_j-ohD19LE,5240
+epub_translator/xml/inline.py,sha256=VcaNEF2ebVl2fogVk2yV3f4vOP4rePsPTV_qU3fJCE0,3108
+epub_translator/xml/self_closing.py,sha256=gA3wI4axhx281iMnK7Eu81mSXfOhaGsHAVYCYKTXAoQ,5446
 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/xml_like.py,sha256=oW8JhpdihlayOxDLFlM29uA2HTjpHk7r85jxTcqajME,10142
 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
@@ -57,7 +58,7 @@ epub_translator/xml_translator/stream_mapper.py,sha256=nk8iRUHAUQA2B35_y-JOCo6il
 epub_translator/xml_translator/submitter.py,sha256=_ic2_JBPdEd2nMSu2mtQ5OzqpGv0zGrvYaicVUXAiUQ,14159
 epub_translator/xml_translator/translator.py,sha256=7Ja1jFbmjIgHcmI9V6gg_K0t7qb6in9mhRn54a7qhZ8,9497
 epub_translator/xml_translator/validation.py,sha256=-OKlSZuD__sjAiEpGAO93YQme4ZDSPmoPjRsAMOCEjc,16668
-epub_translator-0.1.7.dist-info/LICENSE,sha256=5RF32sL3LtMOJIErdDKp1ZEYPGXS8WPpsiSz_jMBnGI,1066
-epub_translator-0.1.7.dist-info/METADATA,sha256=-ySr_REjXY7qG5dZslElcQeIQ_U8r-ggkVtKytZBYMI,15684
-epub_translator-0.1.7.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-epub_translator-0.1.7.dist-info/RECORD,,
+epub_translator-0.1.9.dist-info/LICENSE,sha256=5RF32sL3LtMOJIErdDKp1ZEYPGXS8WPpsiSz_jMBnGI,1066
+epub_translator-0.1.9.dist-info/METADATA,sha256=0Av_UtT49b-yCrurxxzXxMS-KGnraqPLzQCOdxzLh9U,18274
+epub_translator-0.1.9.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+epub_translator-0.1.9.dist-info/RECORD,,