Aio Epub Quality

EPUB Quality — Translation Quality Report

Check translation quality across a book or specific chapter to find issues.

Khi nào dùng: Sau khi dịch xong bằng aio-epub-translate, chạy quality check trước khi xuất bằng aio-epub-export.

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. Run Quality Report

# Check a specific chapter
report = api("GetTranslationQualityReport", {
    "bookId": BOOK_ID,
    "filePath": FILE_PATH  # leave empty to check entire book
})

print(f"Quality Score: {report['qualityScore']:.1f}%")
print(f"Total Items: {report['totalItems']}")
print(f"Issues Found: {report['issuesCount']}")

for issue in report.get("issues", []):
    print(f"\n  [{issue['issueType']}] {issue['contentId'][:12]}")
    print(f"  Detail: {issue['detail']}")
    if issue.get("originalText"):
        print(f"  Original: {issue['originalText'][:100]}")
    if issue.get("translatedText"):
        print(f"  Translated: {issue['translatedText'][:100]}")

2. Issue Types

2b. Literary Quality Evaluation (Đánh giá văn học sâu)

Dùng khi mechanical score cao (>90%) nhưng bản dịch "nghe như dịch máy" hoặc "đọc không tự nhiên".

Nạp kiến thức đánh giá — resolve path đến references của aio-epub-vn-style:

REFS="${CLAUDE_PLUGIN_ROOT}/skills/aio-epub-vn-style/references"
echo "$REFS"

Dùng Read tool đọc $REFS/quality-rubric.md (khung đánh giá MQM/ATA) và $REFS/common-errors.md (6 loại lỗi phải tránh). Đọc thêm $REFS/word-choice.md nếu cần tra đại từ.

Tiêu chí đánh giá (MQM + Tín-Đạt-Nhã):

Red flags — dấu hiệu chất lượng kém (chi tiết trong $REFS/quality-rubric.md):

3. Re-translate Bad Items

For chapters with issues, use aio-epub-translate to re-translate:

# Get the problematic items
page = api("GetPageJson", {
    "bookId": BOOK_ID,
    "filePath": FILE_PATH,
    "size": 0,
    "offset": 0
})

# Filter only items with quality issues
issue_ids = {issue["contentId"] for issue in report.get("issues", [])}
bad_items = [item for item in page["contents"] if item["contentId"] in issue_ids]

# Re-translate and submit via batch
batch_items = []
for item in bad_items:
    translated = translate(item["contentText"])  # Claude re-translates
    batch_items.append({
        "contentId": item["contentId"],
        "translatedContent": translated,
        "targetLanguage": "Vietnamese"
    })

result = api("BatchCreateManualTranslation", {
    "bookId": BOOK_ID,
    "filePath": FILE_PATH,
    "items": batch_items
})
print(f"Re-translated: {result['createdCount']} items")

4. Full Book Scan

# Scan entire book (no filePath = all chapters)
report = api("GetTranslationQualityReport", {
    "bookId": BOOK_ID,
    "filePath": ""
})

# Group issues by file
from collections import defaultdict
by_file = defaultdict(list)
for issue in report.get("issues", []):
    by_file[issue.get("filePath", "unknown")].append(issue)

for file_path, issues in sorted(by_file.items()):
    print(f"\n{file_path}: {len(issues)} issues")
    for issue in issues:
        print(f"  [{issue['issueType']}] {issue['detail'][:80]}")

Quality Thresholds

Bước tiếp theo

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