aio-epub-analyze

name: aio-epub-analyze description: | Pre-translation analysis for EPUB books — analyze writing style, characters, tone, and build glossary before translating. when_to_use: analyze book, phân tích sách, pre-translate, chuẩn bị dịch, book analysis, character list, danh sách nhân vật, glossary, thuật ngữ, writing style analysis, tone analysis, prepare translation effort: medium argument-hint: book ID or title

EPUB Analyze — Pre-translation Intelligence

Phân tích sách TRƯỚC khi dịch: nhận diện nhân vật, writing style, tone, key terms → tạo guideline + glossary chính xác.

Khi nào dùng: LUÔN chạy trước aio-epub-translate cho sách mới. Guideline từ phân tích thực tế tốt hơn hẳn template tự động.

API Setup

import json, urllib.request, os

BASE = "https://read-api.aiocean.dev/ListBooks.v1.BookService"
KEY = os.environ.get("AIO_EPUB_API_KEY", "")

def api(method, body):
    data = json.dumps(body).encode('utf-8')
    req = urllib.request.Request(f"{BASE}/{method}", data=data, headers={
        "Content-Type": "application/json",
        "X-License-Key": KEY
    })
    with urllib.request.urlopen(req) as resp:
        return json.loads(resp.read())

Workflow

1. Lấy thông tin sách, TOC, và thống kê

book = api("GetBook", {"bookId": BOOK_ID})
b = book["book"]
print(f"Title: {b['title']}")
print(f"Author: {b['author']}")
print(f"Language: {b['language']}")

# Book stats — word count, chapter sizes
stats = api("GetBookStats", {"bookId": BOOK_ID})
print(f"Chapters: {stats['totalChapters']}")
print(f"Total words: {stats['totalOriginalWords']}")
print(f"Longest: {stats['longestChapter']['filePath']} ({stats['longestChapter']['wordCount']} words)")
print(f"Shortest: {stats['shortestChapter']['filePath']} ({stats['shortestChapter']['wordCount']} words)")

toc = api("GetTableOfContent", {"bookId": BOOK_ID})
chapters = []
def collect_chapters(items):
    for item in items:
        if item.get("filePath"):
            chapters.append(item)
        if item.get("children"):
            collect_chapters(item["children"])
collect_chapters(toc["tableOfContent"]["items"])
print(f"Total chapters in TOC: {len(chapters)}")

2. Sample chapters — đầu, giữa, cuối

Đọc 3-5 chapters mẫu đại diện cho toàn bộ sách:

# Chọn chapters mẫu: đầu, 1/3, giữa, 2/3, cuối
sample_indices = [0]
if len(chapters) > 4:
    sample_indices += [len(chapters)//4, len(chapters)//2, 3*len(chapters)//4]
sample_indices.append(len(chapters) - 1)
sample_indices = sorted(set(sample_indices))

# Dùng BatchGetPageJson để lấy tất cả mẫu trong 1 call
sample_paths = [chapters[i]["filePath"] for i in sample_indices]
batch = api("BatchGetPageJson", {
    "bookId": BOOK_ID,
    "filePaths": sample_paths,
    "filter": "CONTENT_FILTER_ALL"
})

samples = {}
for ch_data in batch.get("chapters", []):
    fp = ch_data["filePath"]
    samples[fp] = {
        "contents": ch_data["contents"]
    }
    print(f"  {fp}: {ch_data['totalItems']} items")

3. Agent phân tích nội dung

Đọc nội dung các chapter mẫu và phân tích theo các tiêu chí sau:

A. Nhận diện thể loại

• Self-help / Business / Fiction / Science / Philosophy / Children's / Historical / Technical?
• Ảnh hưởng chiến lược dịch: xem aio-epub-vn-style → genre-strategies.md

B. Danh sách nhân vật + đại từ

Với mỗi nhân vật xuất hiện, xác định:

Tham khảo bảng đại từ trong aio-epub-vn-style → word-choice.md (8-cell pronoun table).

C. Writing style & tone

• Formal / Informal / Academic / Conversational / Poetic?
• Narrator voice: first-person / third-person / omniscient?
• Sentence length: short & punchy / long & complex / mixed?
• Đặc trưng riêng của tác giả (metaphors, humor, irony, rhetorical questions)?

D. Key terms & concepts

Liệt kê thuật ngữ quan trọng xuất hiện nhiều lần:

E. Độ khó dịch

• Ước tính: Dễ / Trung bình / Khó / Rất khó
• Yếu tố gây khó: wordplay, cultural references, poetry, technical jargon?
• Chapters nào khó nhất? Tại sao?

4. Tạo guideline từ phân tích

Dựa trên kết quả phân tích, tạo guideline chi tiết:

# Xem guideline hiện có trước khi ghi đè
existing = api("GetGuideline", {"bookId": BOOK_ID})
if existing.get("guideline"):
    print("=== EXISTING GUIDELINE ===")
    print(existing["guideline"])
    print("\n→ Merge với kết quả phân tích mới, KHÔNG ghi đè nếu guideline cũ có thông tin tốt.")

guideline = """
# Translation Guideline — {book_title}

## Thể loại: {genre}

## Phong cách dịch
- Tone: {tone_description}
- Giọng kể: {narrator_voice}
- Nhịp câu: {sentence_rhythm}

## Nhân vật & Đại từ
{character_table}

## Thuật ngữ cố định
{glossary_table}

## Nguyên tắc riêng cho sách này
- {principle_1}
- {principle_2}
- {principle_3}

## Lưu ý đặc biệt
- {special_notes}
"""

# Save guideline
api("UpdateGuideline", {
    "bookId": BOOK_ID,
    "guideline": guideline
})
print("Guideline saved!")

5. Lưu glossary vào server

Sau khi phân tích key terms, lưu glossary để dùng xuyên suốt quá trình dịch:

# Xem glossary hiện có
existing_glossary = api("GetGlossary", {"bookId": BOOK_ID})
print(f"Existing terms: {len(existing_glossary.get('entries', []))}")

# Thêm từng term
api("AddGlossaryTerm", {
    "bookId": BOOK_ID,
    "original": "mindfulness",
    "translated": "chánh niệm",
    "note": "Thuật ngữ Phật giáo, quen thuộc với độc giả Việt"
})

# Hoặc thay thế toàn bộ glossary
api("UpdateGlossary", {
    "bookId": BOOK_ID,
    "entries": [
        {"original": "self", "translated": "bản ngã", "note": "Tâm lý học"},
        {"original": "ego", "translated": "cái tôi", "note": "Phân biệt với self"},
        {"original": "anxiety", "translated": "lo âu", "note": "Không dùng 'sự lo lắng'"},
        {"original": "repression", "translated": "dồn nén", "note": "Thuật ngữ phân tâm học"}
    ]
})
print("Glossary saved!")

# Xóa term không cần
api("DeleteGlossaryTerm", {
    "bookId": BOOK_ID,
    "original": "term_to_remove"
})

Glossary được merge tự động: Khi dịch (GetChapterContext), server merge glossary thủ công với auto-generated glossary từ translations. Glossary thủ công được ưu tiên khi conflict.

Output mẫu

Kết quả phân tích nên có dạng:

📖 Book Analysis: "Atomic Habits" by James Clear

Genre: Self-help / Behavioral Psychology
Difficulty: Trung bình
Tone: Conversational, motivational, evidence-based

Characters: Không có nhân vật chính (non-fiction)
Narrator: First-person (tác giả), dùng "tôi"

Key Terms (15):
  habit loop → vòng lặp thói quen
  cue → tín hiệu
  craving → khao khát
  response → phản hồi
  reward → phần thưởng
  identity-based habits → thói quen dựa trên bản sắc
  ...

Translation Strategy:
  - Giữ tone conversational, tránh academic
  - Dịch ví dụ thực tế sát nghĩa, giữ tên riêng
  - Thuật ngữ khoa học: ưu tiên thuần Việt, ghi chú gốc Anh lần đầu
  - Câu ngắn, nhịp nhanh — giữ đúng style tác giả

Điều hướng

Workflow: aio-epub-setup → aio-epub-upload → aio-epub-analyze → aio-epub-translate → aio-epub-quality → aio-epub-review → aio-epub-export