epub-translator

When using the translation API, you can provide a user_prompt to guide the LLM. In version 0.1.7 and later, this prompt is automatically wrapped in <rules> tags within the translation template to ensure the LLM follows your instructions.

{% if user_prompt -%}
<rules>
{{ user_prompt }}
</rules>
{% endif -%}

The Fill Stage relies on specific identifiers and metadata to map translated text back to the XML structure:

• Elements with IDs: Used for elements that require disambiguation when multiple similar structures exist (e.g., multiple <span id="5">Principia</span> tags).
• Elements without IDs: Matched based on position and tag name.
• data-orig-len attribute: Represents the token count of the original text. This serves as a positioning hint for the LLM, helping it understand the scale of the translation (e.g., identifying when a short source word expands into a long target phrase).

If you use separate LLM instances for translation and filling (via translation_llm and fill_llm parameters in translate), each instance tracks its own independent statistics. This allows you to monitor the cost and usage of each specific role separately.

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}")

Version 0.1.2 introduces a Dual-LLM architecture that allows you to provide separate LLM instances for different stages of the translation process. This optimizes quality by using different settings for creative translation versus structural XML filling:

• translation_llm: Used for the actual text translation. It is recommended to use a higher temperature (e.g., 0.8) for more natural, creative output.
• fill_llm: Used for filling the XML structure. It is recommended to use a lower temperature (e.g., 0.3) for deterministic, structure-preserving results.

By providing both, you can leverage the strengths of different models or configurations for each specific task.

translate(
    source_path,
    target_path,
    "English",
    translation_llm=translation_llm,
    fill_llm=fill_llm,
)

If you provide separate LLM instances for translation and filling, each instance tracks its own statistics independently. You can access translation_llm.total_tokens and fill_llm.total_tokens to see the breakdown.

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.CHINESE,
    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"Total: {translation_llm.total_tokens + fill_llm.total_tokens}")

The EPUB Translator uses a two-stage translation process to ensure both high translation quality and structural integrity:

1. Translate Stage (translate_llm, temperature=0.8):

   • Converts the source text into pure text in the target language.
   • Does not preserve XML structures, focusing entirely on translation quality.

2. Fill Stage (fill_llm, temperature=0.3):

   • Fills the translated text back into the original XML template.
   • Ensures the XML structure (tags, nesting, IDs) remains identical to the source.
   • Uses a Hill Climbing algorithm to verify structural correctness.

This separation allows the LLM to focus on linguistic nuances in the first stage and structural precision in the second.

The submit parameter determines how the translated text is integrated into the EPUB structure. Use the SubmitKind enum to choose a mode:

• SubmitKind.REPLACE: Replaces original content with translation. Results in a single-language book.
• SubmitKind.APPEND_TEXT: Appends translation as inline text immediately after the original content. Both languages appear in the same paragraph.
• SubmitKind.APPEND_BLOCK (Recommended): Appends translations as separate block elements (paragraphs) after the original. This is ideal for side-by-side bilingual reading.

from epub_translator import SubmitKind

# For bilingual books (recommended)
translate(..., submit=SubmitKind.APPEND_BLOCK, ...)

# For single-language translation
translate(..., submit=SubmitKind.REPLACE, ...)

The submit parameter determines how the translated text is integrated into the EPUB document. Use the SubmitKind enum to choose a mode:

• SubmitKind.REPLACE: Replaces the original text with the translation. This produces a monolingual output.
• SubmitKind.APPEND_TEXT: Appends the translation as inline text immediately following the original. This produces a bilingual output where both languages appear in the same paragraph.
• SubmitKind.APPEND_BLOCK: Appends the translation as a separate block element (e.g., a new paragraph) after the original. This is the recommended mode for clear bilingual reading.

from epub_translator import SubmitKind

# Recommended for bilingual reading
translate(..., submit=SubmitKind.APPEND_BLOCK, ...)

# For a single-language version
translate(..., submit=SubmitKind.REPLACE, ...)

To help the AI escape infinite retry loops (deadlocks), the system uses a temperature increment mechanism.

Mechanism:

• The initial attempt uses a low temperature (e.g., 0.2) for high determinism.
• For every subsequent retry, the temperature increases exponentially (e.g., 0.2 → 0.5 → 0.65 → 0.725...).

Note: Temperature increment is a safety measure, not a primary solution. If the prompt's cognitive framework (like Error Type 7) is incorrect, increasing temperature will not solve the underlying logic error.

temperature=(0.2, 0.9)