---
name: epub-translate
description: A skill for creating bilingual EPUB books by adding translated text alongside the original content while preserving the original formatting and structure.
---

# EPUB Bilingual Translate Skill

## Overview
This skill creates bilingual EPUB files by adding translated text alongside the original content while preserving the original formatting and structure. It follows a 4-step workflow: extract, translate, update metadata, and reassemble.

## Functionality
- Extracts content from EPUB archives
- Creates bilingual text content in HTML/XHTML files by adding translations alongside original text
- Updates metadata to reflect the bilingual nature of the content
- Reassembles bilingual content into a valid EPUB archive
- Preserves original formatting, structure, and non-text content
- Unzips and parses EPUB files to identify navigation and content files
- Supports multiple target languages for bilingual output

## Workflow
1. **Extract**: Unzip the EPUB file to access its contents (HTML files, metadata, etc.)
2. **Translate**: Identify text content in HTML/XHTML files and add translations alongside original text
3. **Update Metadata**: Modify language settings in content.opf and other relevant files to reflect bilingual content
4. **Reassemble**: Zip the bilingual files back into a valid EPUB archive

## Implementation Details
- Reads EPUB as a zip archive (mimetype, META-INF/, EPUB/ folder structure)
- Parses HTML/XHTML files to extract translatable text while preserving tags
- Updates DC metadata language field in content.opf to indicate bilingual content
- Maintains the original file structure and properties during reassembly
- Validates the final EPUB file to ensure it's a properly formatted archive
- Uses `unzip -d` command to extract the EPUB file to a temporary directory
- Opens each file in the extracted EPUB folder to examine its content
- Adds translated text alongside the original text in each file
- Preserves the original text while adding translations
- Compresses the bilingual files back into an EPUB file

## Usage
1. Extract the source EPUB using `unzip`
2. Add translated text alongside original content in HTML files while keeping the markup intact
3. Update language metadata in content.opf to indicate bilingual content
4. Reassemble using `zip` command with proper options to maintain EPUB format
5. Verify the result with `unzip -t` to ensure integrity

## Usage Examples
```
Create a bilingual English-Chinese book about mybook.epub, and save it to mybook_bilingual.epub.
```

## Key Considerations
- EPUB files are essentially ZIP archives with a specific structure
- The mimetype file must be the first file in the archive and stored without compression
- Language attributes in HTML files and metadata should reflect the bilingual nature
- All original file paths and structures must be preserved during reassembly
- Original text content must be preserved alongside the new translations
- No automated scripts should be created for translation; instead, create a TODO list of files that need translation
- Directly read file content and perform modifications on the files rather than using automated processes

## Bilingual Formatting Standards
To ensure optimal reading experience in bilingual EPUB files:
- Use paragraph-by-paragraph comparison format, with translated text immediately following the corresponding original paragraph
- Maintain consistent formatting for both languages throughout the document
- Preserve the original document structure while integrating translated content
- Use appropriate language tags (lang attributes) for both original and translated text
- Clearly separate original and translated content with visual indicators (e.g., different text colors, spacing, or containers)
- Ensure proper text direction and typography for both languages
- Maintain consistent font sizes and styles that work well for both languages
- Follow a structured approach: original paragraph, then translated paragraph, maintaining the logical flow of content