⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

pdf-translate

breslee1707@breslee1707⭐ 747 stars· last commit 25d ago· 5 open issues

Translate local PDFs, including safe prose on image-only scans, into Vietnamese or another supported Latin-script language while preserving layout, formulas, tables, and figures. Use for PDF translation, OCR-assisted scan translation, batch translation, terminology-sensitive handoff translation, or diagnosing incomplete output. Do not use for targets requiring CJK, right-to-left, or complex-script shaping.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐⭐ 747 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README


PDF Translate là ứng dụng mã nguồn mở dành cho Windows, macOS và Android. Công cụ phân tích bố cục từng trang, bảo vệ công thức và code, dịch phần văn xuôi rồi đặt nội dung trở lại đúng vị trí trong tài liệu gốc — không biến PDF của bạn thành một trang chữ trắng đơn giản.

Đây không phải bản dịch giao diện của một công cụ có sẵn. Dự án mượn ý tưởng và phần nhân đọc/ghi PDF từ hai dự án mã nguồn mở, rồi tự xây phần quyết định chất lượng đầu ra: ứng dụng desktop, bộ quy tắc bảo toàn bố cục, lớp xử lý tiếng Việt và hàng loạt bản sửa lỗi ngay trong nhân. Chi tiết ở mục Được phát triển ở đây.

Điểm nổi bật

  • Giữ nguyên bố cục: bảo toàn vị trí của đoạn văn, công thức, bảng, hình, mục lục và tài liệu tham khảo.
  • Bản song ngữ (tùy chọn): tạo thêm một file -dual.pdf để đối chiếu — hai trang cạnh nhau, xen kẽ từng trang, hoặc bản dịch kèm bản gốc nằm trong lớp ẩn Original để bật/tắt trong trình xem PDF. File bản dịch chính không thay đổi.
  • Giao diện Tiếng Việt hoặc English: đổi ngay ở góc trên cửa sổ. Ứng dụng nhớ ngôn ngữ giao diện, ngôn ngữ đích và kiểu bản song ngữ cho lần mở sau.
  • Sẵn sàng để dùng: tải về, giải nén và chạy; không cần cài Python hay model riêng.
  • Xử lý hàng loạt: kéo thả nhiều file PDF hoặc cả thư mục vào ứng dụng. Hàng đợi cho biết số trang của từng file, tiến độ theo trang của file đang dịch, và có nút mở bản dịch ngay khi xong.
  • OCR cục bộ cho trang scan (bật khi cần): chế độ Tự động đọc và dịch vùng văn bản an toàn; bảng, công thức và hình phức tạp được giữ nguyên thay vì bị phá bố cục.
  • 36 ngôn ngữ đích: mặc định là tiếng Việt, cùng nhiều ngôn ngữ sử dụng chữ Latin.
  • Không dừng cả hàng đợi: một file lỗi không làm gián đoạn các file còn lại.
  • Tự cập nhật (Windows): có bản mới thì ứng dụng tự tải ngầm, bạn chỉ cần bấm một lần để khởi động lại. Trên macOS vẫn là dòng nhắc mở trang tải.
  • Có chế độ dành cho AI agent: dùng model trong Codex, Claude Code hoặc Copilot để dịch tài liệu chuyên ngành tốt hơn.

Bắt đầu trong 1 phút

Windows

  1. Tải PDF Translate cho Windows (.zip, khoảng 336 MB; đã gồm model OCR chạy cục bộ, không cần mạng).
  2. Giải nén toàn bộ file vừa tải.
  3. Mở PDFTranslate.exe.

macOS

  1. Tải bản phù hợp: Apple Silicon cho Mac M1/M2/M3/M4/M5 hoặc Intel cho Mac Intel.
  2. Mở file .dmg, kéo PDF Translate vào thư mục Applications.
  3. Trong lần chạy đầu, bấm chuột phải vào ứng dụng → Open → Open.

Android

  1. Tải APK từ bản phát hành Android mới nhất (PDFTranslate-android-*.apk). Bản Android được đánh tag riêng theo dạng android-v*.
  2. Trên điện thoại, cho phép trình duyệt hoặc trình quản lý file cài ứng dụng từ nguồn không xác định, rồi mở file APK.
  3. Ứng dụng cần Android 8.0 trở lên.

Muốn tự biên dịch:

cd android
./gradlew assembleDebug

[!NOTE] Bản macOS yêu cầu macOS 14 Sonoma trở lên. Tất cả bản desktop đều không cần cài Python và không phải tải thêm model ở lần chạy đầu. Quá trình dịch bằng Google vẫn cần kết nối Internet.

[!IMPORTANT] Bản Android là một bản viết lại trên PDFBox-Android, không phải bản desktop biên dịch lại. Nó chỉ đọc PDF dạng văn bản (chưa có OCR) và dùng heuristic thay cho model bố cục BabelDOC/YOLOv8, nên PDF nhiều công thức có thể còn sai chỉ số trên/dưới hoặc phân số. Chi tiết build và phát hành nằm ở docs/android-release.md.

[!WARNING] Windows SmartScreen có thể cảnh báo vì ứng dụng chưa được ký số. Chọn More info → Run anyway nếu bạn tải file từ trang Releases chính thức của repo này.

[!WARNING] Nếu máy bạn bật Smart App Control (mặc định trên các máy Windows 11 cài mới), ứng dụng sẽ bị chặn hẳn với thông báo "An Application Control policy has blocked this file" — không có nút Run anyway. Kiểm tra tại Windows Security → App & browser control → Smart App Control. Đây là hệ quả của việc ứng dụng chưa có chữ ký số, không phải lỗi của ứng dụng. Microsoft chỉ cho bật lại Smart App Control bằng cách cài lại Windows, nên hãy cân nhắc kỹ trước khi tắt nó; giải pháp đúng là ký số ứng dụng, và việc đó đang được xử lý.

[!WARNING] Bản macOS hiện dùng chữ ký ad-hoc, chưa được Apple notarize. Gatekeeper có thể chặn thao tác mở thông thường; hãy dùng cách bấm chuột phải → Open ở trên nếu bạn tải từ trang Releases chính thức.

Bạn cũng có thể mở trang Releases để xem ghi chú thay đổi và các tệp của phiên bản mới nhất.

Ứng dụng cũng tự kiểm tra phiên bản mới mỗi lần mở. Máy không có mạng thì bỏ qua, không báo lỗi.

Trên Windows, bản mới được tải ngầm ngay trong lúc bạn vẫn dịch bình thường; góc trên bên phải hiện ↓ Đang tải vX.Y.Z, tải xong đổi thành ● Cài vX.Y.Z & khởi động lại. Bấm vào đó, ứng dụng đóng lại, thay thư mục cài đặt rồi tự mở lại — khoảng mười giây, không phải giải nén gì. Đang dịch dở thì nút chờ đến khi xong. Tải xong mà bạn tắt ứng dụng luôn cũng không mất: lần mở sau vẫn là nút khởi động lại, không tải lại từ đầu. Nếu bước thay thư mục hỏng giữa chừng, bản cũ được đưa lại nguyên vẹn và bạn tải thủ công như trước.

Trên macOS, và khi ứng dụng nằm ở thư mục không có quyền ghi, dòng đó vẫn là ● Có bản mới vX.Y.Z và bấm vào sẽ mở

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • SKILL.md7.8 KBupstream ↗
    ---
    name: pdf-translate
    description: Translate local PDFs, including safe prose on image-only scans, into Vietnamese or another supported Latin-script language while preserving layout, formulas, tables, and figures. Use for PDF translation, OCR-assisted scan translation, batch translation, terminology-sensitive handoff translation, or diagnosing incomplete output. Do not use for targets requiring CJK, right-to-left, or complex-script shaping.
    license: AGPL-3.0-only
    ---
    
    # PDF Translate
    
    Translate a PDF with the bundled Code4Life engine. Keep the source file unchanged and produce a separate PDF with the same page structure.
    
    When this skill runs inside the repository, first read
    [`agent-knowledge/index.md`](agent-knowledge/index.md). For preservation or
    layout work, load its PDF engine, regression, and validation routes. These are
    the shared project instructions for Codex and Claude; do not duplicate them in
    this entrypoint.
    
    ## Resolve the skill root
    
    This skill may be installed globally while the user's files live elsewhere. Resolve the absolute directory containing this `SKILL.md` before running anything. Call its scripts and dependency files by absolute path; do not assume the current working directory is the skill directory.
    
    Use the interpreter inside `<skill-root>/.venv`:
    
    - Windows: `<skill-root>\.venv\Scripts\python.exe`
    - macOS/Linux: `<skill-root>/.venv/bin/python`
    
    ## Choose a mode
    
    | Mode | Translator | Use when |
    | --- | --- | --- |
    | Google (default) | `translate.google.com` | Books, batches, first drafts, or low token use |
    | Handoff | The active agent | Terminology, context, or translation quality matters |
    
    Default to Google. Offer handoff when the user asks for higher quality, rejects the Google result, or provides a short technical document.
    
    ## Boundaries
    
    - Use the bundled `pdf2zh/` core. Never substitute the PyPI `pdf2zh` package; the runner checks version `1.9.11` and preservation ruleset `code4life-preservation-v1` and refuses an external core.
    - Google mode sends extracted document text to Google. Tell the user before processing sensitive material and obtain explicit confirmation unless their request already authorizes that disclosure. Handoff mode does not contact Google.
    - Supported targets are the Latin-script codes enforced by `scripts/translate_pdf.py`. CJK, right-to-left, Thai, Devanagari, and other complex-shaping targets are rejected because the bundled font and layout engine cannot render them reliably.
    - OCR is opt-in with `--ocr standard|enhanced`. It fails closed on unsafe tables,
      formulas, figures, code and ambiguous reading order; report every preserved
      region as partial instead of claiming the whole scan was translated.
    - Text inside detected tables, figures, contents pages, indexes, symbol lists, or references may intentionally remain in the source language. Report material untranslated regions as partial translation.
    - Preserve the source. Write results to a separate output directory. Do not pass `--overwrite` without explicit replacement authorization.
    
    Read [the preservation contract](references/preservation-rules.md) before changing layout behavior, diagnosing preserved pages, or investigating untranslated regions.
    
    ## Set up the runtime
    
    Use Python 3.11 or 3.12. Create `<skill-root>/.venv` and install `<skill-root>/requirements.txt` if the environment is absent or stale. Keep this environment separate from the user's project.
    
    The source distribution downloads layout and font assets on its first translation, so the first run needs network access and takes longer. The packaged Windows app already contains these assets.
    
    Windows:
    
    ```powershell
    python -m venv "<skill-root>\.venv"
    & "<skill-root>\.venv\Scripts\python.exe" -m pip install -r "<skill-root>\requirements.txt"
    ```
    
    macOS/Linux:
    
    ```bash
    python3 -m venv "<skill-root>/.venv"
    "<skill-root>/.venv/bin/python" -m pip install -r "<skill-root>/requirements.txt"
    ```
    
    Shared runner options include `--target-language` (default `vi`), `--source-language auto`, one-based `--pages 1,3-5`, `--threads 1..8` (default `4`; Google mode still sends one request at a time), `--ignore-cache`, and `--overwrite`.
    
    ## Google mode
    
    Run one command per file. Use absolute paths for the input and output directory.
    
    Windows:
    
    ```powershell
    & "<skill-root>\.venv\Scripts\python.exe" "<skill-root>\scripts\translate_pdf.py" "<input.pdf>" --output-dir "<output-dir>"
    ```
    
    macOS/Linux:
    
    ```bash
    "<skill-root>/.venv/bin/python" "<skill-root>/scripts/translate_pdf.py" "<input.pdf>" --output-dir "<output-dir>"
    ```
    
    For a batch, process files individually and report progress. A file-specific
    failure must not stop the remaining files. A Google block or exhausted service
    outage pauses the whole queue; successful translations remain cached for a
    later retry, and no incomplete PDF is published for that interrupted file.
    
    Google mode sends a page's segments in one request, one request at a time, because the free endpoint blocks a network that floods it. Never run several Google jobs in parallel.
    
    If a run encounters HTTP 429 or a CAPTCHA, the runner stops the document and
    pauses the queue. For the next 10 minutes it refuses further Google runs before
    OCR/model work. This is the app's cooldown, not a prediction of Google's
    recovery time. Do not rerun it in a loop or try to get past the CAPTCHA. Report
    it, then offer a later rerun (finished segments are cached) or handoff mode.
    
    ## Handoff mode
    
    Handoff extracts translatable segments to JSONL, lets the active agent translate them, then rebuilds the PDF. Warn about token and time cost before starting a large document. For long documents, suggest a representative sample such as `--pages 1-5` first.
    
    ### 1. Extract
    
    An output directory is not required during extraction because the pass-one PDF is discarded.
    
    ```text
    <python> <skill-root>/scripts/translate_pdf.py <input.pdf> --engine handoff --emit-segments <segments.jsonl>
    ```
    
    ### 2. Translate
    
    Read `segments.jsonl` in manageable batches. Write one JSON object per line to `translations.jsonl`:
    
    ```json
    {"src":"exact source text","dst":"translated text"}
    ```
    
    Copy each `src` value exactly. Preserve URLs, paths, identifiers, citation markers, and numbers.
    
    Formula and code placeholders such as `<b0></b0>` are immutable. Every opening and closing tag must retain the same identifier, count, and order as the source. The loader rejects a record whose placeholders differ, leaving that segment untranslated.
    
    Inline emphasis markers are immutable as balanced pairs: `<s1>...</s1>` is
    bold, `<s2>...</s2>` is italic, and `<s3>...</s3>` is bold italic. Complete
    style pairs may move with the translated phrase, but none may be dropped,
    duplicated, or cross-nested. Invalid style markup leaves the segment
    untranslated instead of silently losing emphasis.
    
    ### 3. Rebuild
    
    ```text
    <python> <skill-root>/scripts/translate_pdf.py <input.pdf> --engine handoff --segments <translations.jsonl> --output-dir <output-dir> --emit-segments <still-missing.jsonl>
    ```
    
    The command prints the remaining untranslated segment count. If it is nonzero, translate `still-missing.jsonl`, append valid records to `translations.jsonl`, and rebuild again. Stop only at zero or when a segment cannot be translated safely; then report the exact remaining limitation.
    
    Extraction and rebuild each run the layout pass, so handoff uses roughly twice the local PDF processing of Google mode in addition to the agent's translation work.
    
    ## Verify before delivery
    
    1. Confirm the output exists and the source still exists unchanged.
    2. Confirm source and output page counts match.
    3. Extract text page by page and check for substantial untranslated passages, missing formulas, damaged URLs, or lost identifiers.
    4. When page rendering or image inspection is available, render every output page and inspect for blank pages, missing glyphs, clipping, overlap, and displaced tables or figures.
    5. If full visual inspection is unavailable, say which checks were com
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/breslee1707-vi-translate.md

// REPO STATS

747 stars
5 open issues
Last commit: 25d ago