Skip to content
kiencangPublic

About

AI Agent dịch file PDF. Phù hợp dịch cho các file *PDF tiêu chuẩn* hoặc trên máy cấu hình thấp. Dung lượng ứng dụng nhẹ, file .zip chưa đến 30MB.

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

Luka-Loop

Công cụ AI Agent tự động dịch tài liệu PDF từ tiếng Anh sang tiếng Việt. Không yêu cầu cài thêm bất cứ phần mềm (ngoài công cụ này và phần mềm desktop Agent mà bạn hay dùng) hỗ trợ nào. Chỉ cần mở thư mục trên các agent như Antigravity, Claude Code là bắt đầu dùng được ngay. Một số agent khác mà bạn có thể thử là Cursor và Goose.

  • Định dạng đầu vào: PDF, và nên là PDF tiêu chuẩn dưới 50 trang, với PDF scan ứng dụng vẫn dùng bình thường nhưng tốn thời gian hơn khá nhiều (nếu file scan nhiều ảnh chụp lồng bên trong, file tiêu chuẩn thì tách ảnh rất nhanh).
  • Định dạng đầu ra mặc định: Bản dịch tiếng Việt trả về ở cả 2 định dạng đồng thời là HTML và PDF. Định dạng HTML thường có kết quả hiển thị tốt hơn.

PS: Nếu file PDF của bạn chủ yếu là các file scan, hoặc có các hình phức tạp hơn mà phiên bản này không xử lý được, bạn có thể tham khảo bản Max Luka Loop sử dụng công nghệ tách hình mạnh hơn: https://github.com/kiencang/Max-Luka-Loop

Cách dùng

Rất đơn giản, bạn tải trực tiếp gói dựng sẵn mới nhất tại đây:

  • Tải bản mới nhất: luka-loop-win-x64.zip
  • (Nếu mở trang GitHub Releases, hãy chọn tệp luka-loop-win-x64.zip trong mục Assets — không tải Source code (zip) vì gói mã nguồn thô từ Git không kèm sẵn extract_assets.exe).

Sau đó giải nén file zip đó ở bất kỳ thư mục làm việc nào mà bạn muốn. Khi giải nén, nhớ chọn tùy chọn Extract Here, mở thư mục luka-loop vừa giải nén thấy ngay file có tên AGENTS.md nghĩa là bạn đã giải nén thành công (nếu thích, bạn có thể đổi tên thư mục luka-loop sang tên khác cũng không vấn đề gì). PS: Nếu giải nén theo kiểu Etract to sẽ tạo thành 2 thư mục lồng nhau và sẽ không dùng được, nên bạn nhớ dùng Extract Here nhé!

Phần khó nhất đã xong! Giờ để dùng công cụ dịch, bạn chỉ việc vào Antigravity, chọn Workspace > Create Project > Add Folder, rồi bạn thêm thư mục vừa giải nén xong là OK.

Giờ thì bạn chỉ việc tải file PDF vào khung chat rồi gõ câu lệnh kiểu như Dịch tài liệu sang tiếng Việt. là agent Gemini sẽ tiến hành dịch, và gửi kết quả về ở cả 2 định dạng HTML và PDF.

Nếu muốn bản dịch giữ sát bố cục/thiết kế gốc của từng trang của PDF (sách, tạp chí, tài liệu nhiều cột...), hãy nêu rõ trong yêu cầu (ví dụ: Dịch tài liệu sang tiếng Việt và bảo toàn thiết kế/layout.). Lưu ý là với cách dịch yêu cầu bố cục giống bản gốc sẽ tiêu tốn token hơn đáng kể, khoảng gần gấp đôi so với kiểu mặc định, vì thế bạn chỉ nên dùng khi cần thiết.

Dung lượng file: Nếu bạn tải file lên từ khung chat, giới hạn của Antigravity là 10MB, trường hợp bạn có file lớn hơn, bạn nên đặt vào thư mục input của chương trình này.

Lưu ý:

  • Khi làm việc với Antigravity, bạn có thể chọn chế độ Turbo (thay vì mặc định Request Review) để tránh phải xác nhận lặp lại các lệnh đóng gói; tuy nhiên chỉ nên dùng Turbo với tài liệu PDF từ nguồn tin cậy (với PDF lạ, nên giữ Request Review để kiểm soát lệnh thực thi).
  • Nếu đặt thư mục luka-loop bên trong vùng đồng bộ đám mây (OneDrive, Google Drive, Dropbox...), hãy bật tùy chọn giữ tệp ngoại tuyến trên máy (Always keep on this device / Mirror files / Available offline) để extract_assets.exe nạp đủ các thư viện đi kèm và tránh lồng đường dẫn quá sâu vượt giới hạn ký tự trên Windows.

Dùng với Claude Code

Ngoài Antigravity, bạn có thể dùng công cụ với Claude Code (tab Code trong ứng dụng Claude desktop) trên Windows:

  • Mở thư mục max-luka-loop trong Claude Code. Lần đầu mở, hãy chấp nhận hộp thoại tin cậy thư mục (workspace trust) để các quyền chạy sẵn trong .claude/settings.json có hiệu lực.
  • Gõ yêu cầu kèm đường dẫn tệp PDF, ví dụ Dịch input/bao-cao.pdf sang tiếng Việt. (hoặc thêm và bảo toàn thiết kế/layout.).
  • Với PDF trên 10 trang, agent dựng ảnh từng cụm trang bằng extract_assets.exe có sẵn (PyMuPDF) để đọc, nên không cần cài thêm chương trình pdftoppm (poppler) mà công cụ đọc PDF của Claude Code đòi hỏi khi đọc theo cụm trang.
  • .claude/settings.json cho phép Claude Code chạy 3 script công cụ trong tools\ mà không hỏi lại mỗi lần. Nếu muốn được hỏi trước mỗi lệnh, xóa các dòng trong permissions.allow.

Yêu cầu hệ thống

  • Hệ điều hành: Windows 10 hoặc Windows 11 64-bit (x64) (bộ công cụ extract_assets.exe hiện biên dịch ở kiến trúc x64, chưa hỗ trợ Windows 32-bit), hầu hết các máy tính hiện nay trên thị trường đều là bản 64-bit.
  • PowerShell: Hỗ trợ cả Windows PowerShell 5.1 (có sẵn mặc định trên Windows 10/11) lẫn PowerShell 7+ (pwsh.exe), không yêu cầu cấu hình thêm.
  • Trình duyệt (tùy chọn để tự động xuất PDF): Công cụ dùng Microsoft Edge (ưu tiên) hoặc Google Chrome để xuất tệp PDF. Nếu không có, quy trình vẫn xuất hoàn chỉnh tệp *_vi.html.

Lý do tồn tại

Tôi đã có sản phẩm https://github.com/kiencang/PDF-silaTranslator có chức năng tương đương, nhưng hiện tại chỉ API Key trả phí mới sử dụng được. Mặc dù ngưỡng miễn phí của Antigavity không lớn, nhưng nếu dịch tài liệu nhỏ vẫn được, còn với tài liệu dài, dịch nhiều vẫn cần các tài khoản có phí (nhưng tính trên trung bình, vẫn rẻ hơn khá nhiều so với việc dịch bằng cách mua API Key).

Ngoài ra, việc sử dụng các thư viện python chất lượng cao như PyMuPDF giúp công cụ có sự cải tiến tốt hơn trong khả năng tách ảnh, khi bạn thử, bạn sẽ thấy đa số các file PDF nó có khả năng bảo toàn định dạng rất tốt.

Cấu trúc dự án

  • AGENTS.md — Quy tắc điều phối dành cho AI Agent trong workspace.
  • .agents/skills/pdf-to-html-vi/ — Skill mặc định pdf-to-html-vi (giao diện 1 cột) gồm quy trình 4 bước (SKILL.md) và bộ dịch thuật học thuật / dàn trang (si_academic_html.md).
  • .agents/skills/pdf-to-html-vi-layout/ — Skill tùy chọn pdf-to-html-vi-layout (kích hoạt khi yêu cầu bảo toàn thiết kế/layout) gồm quy trình tách pha tiết kiệm token (SKILL.md), bộ quy chuẩn chuyên dịch (si_translation.md) và bộ quy chuẩn thiết kế từng trang (si_layout.md).
  • CLAUDE.md, .claude/ và .agents/adapters/claude-code.md — Hỗ trợ Claude Code: CLAUDE.md nạp AGENTS.md cùng bộ chuyển đổi riêng; .claude/skills/ chỉ là lối vào trỏ tới skill gốc trong .agents/skills/ (không sao chép quy trình); .claude/settings.json cho phép sẵn đúng 3 lệnh công cụ.
  • .agents/adapters/antigravity.md — Bộ chuyển đổi riêng cho Antigravity: gom mọi chi tiết phụ thuộc vào Antigravity (lấy PDF kéo-thả vào khung chat, tên tệp tạm, ánh xạ sang công cụ read_file...). AGENTS.md và các SKILL.md viết trung lập để có thể dùng với agent khác (Codex, Cursor...); khi Antigravity thay đổi cách vận hành, chỉ cần sửa tệp này.
  • tools/ — Bộ công cụ thực thi portable (extract_assets.exe) cùng các script PowerShell bọc CLI mỏng:
    • extract_pdf_assets.ps1 gọi tools/extract_assets/extract_assets.exe để phân giải tệp PDF (qua -PdfPath hoặc -TranscriptPath), tách ảnh/sơ đồ, xuất manifest.json và thu gọn tóm tắt trên stdout.
    • pdf_fallback_tools.ps1 gọi tools/extract_assets/extract_assets.exe (PyMuPDF) để render trang PDF scan và cắt khung ảnh theo JSON kèm auto-trim và kiểm tra giới hạn thư mục.
    • html_packager.ps1 chuyển tiếp sang tools/extract_assets/extract_assets.exe để tối ưu & nhúng ảnh Base64 trong bộ nhớ (không tạo ảnh tạm trên đĩa), bơm lớp vỏ đọc reader_shell.html (hoặc bỏ qua khi bật -PreserveLayout), kiểm định Auto-QA, tự động đánh số chống ghi đè (_2, _3...), xuất PDF và dọn sạch work/.
    • _path_guards.ps1 — Tiện ích PowerShell kiểm tra an toàn đường dẫn và gọi extract_assets.exe (kèm phát hiện tệp đám mây offline).
    • src/ (extract_assets.py, figure_detector/, image_ops.py, packager.py, reader_shell.py, html_qa.py, pdf_export.py, output_paths.py, transcript.py, manifest.py, path_guards.py) & src/requirements-build.txt — Mã nguồn Python gốc và danh sách gói ghim phiên bản dùng trên GitHub Actions (hoặc chạy build_extractor.ps1 khi phát triển ở máy cá nhân) để biên dịch ra extract_assets.exe (khi chạy dịch thuật, ứng dụng này tuyệt đối không gọi Python hệ thống).
  • input/ — Thư mục chứa tệp tin đầu vào, quan trọng khi file PDF hơn 10MB thì cần đặt vào đó, nếu không đến giới hạn ấy, người dùng có thể tải lên ngay từ khung chat mà không cần đặt vào thư mục input;
  • output/ — Thư mục chứa tệp đầu ra (*_vi.html/*_vi.pdf cho bản đọc mượt mặc định; *_layout_vi.html/*_layout_vi.pdf cho bản bảo toàn thiết kế; tự động thêm _2, _3... nếu dịch lại nhiều lần cùng một file), tự động được tạo khi đóng gói và được bỏ qua bởi .gitignore.

Tuyên bố từ chối trách nhiệm

Công cụ này có thể được sử dụng cho mục đích nghiên cứu và học tập cá nhân.

Luka-Loop cũng như người phát triển nó không đưa ra bất kỳ bảo đảm rõ ràng hay ngụ ý nào, cũng như không tuyên bố rằng công cụ sẽ vận hành hoàn hảo, chính xác hoặc cập nhật. Người phát triển sẽ không chịu trách nhiệm cho bất kỳ tổn thất hay thiệt hại nào phát sinh trực tiếp hoặc gián tiếp liên quan đến hoặc phát sinh từ việc sử dụng công cụ này.

Giấy phép & Thành phần Bên thứ ba (License & Third-Party Notices)

  • Mã nguồn gốc của Luka-Loop: Phần kịch bản điều phối Agent, Skill, script PowerShell, lớp vỏ tools/reader_shell.html và bộ mã nguồn tự viết trong tools/src/ (extract_assets.py, figure_detector/, image_ops.py, packager.py, reader_shell.py, html_qa.py, pdf_export.py, output_paths.py, transcript.py, manifest.py, path_guards.py) được cấp phép theo MIT License — xem chi tiết tại LICENSE.
  • Bộ công cụ thực thi dựng sẵn (tools/extract_assets/): Bản đóng gói portable phân phối kèm trong gói phát hành Release (luka-loop-win-x64.zip, biên dịch tự động qua GitHub Actions từ tools/build_extractor.ps1) có tích hợp các thành phần phần mềm bên thứ ba và chịu sự điều chỉnh của giấy phép tương ứng từng thành phần:
    • PyMuPDF / MuPDF: Cấp phép theo AGPL-3.0; toàn bộ mã nguồn tương ứng của công cụ thực thi được công khai đầy đủ tại tools/src/.
    • Python 3.12.7: Cấp phép theo PSF License v2.
    • OpenSSL 3.0.15 (libcrypto-3.dll): Cấp phép theo Apache License 2.0.
    • PyInstaller: Bootloader theo GPL-2.0-or-later (kèm Bootloader Exception) và runtime hooks theo Apache License 2.0.
    • Microsoft Visual C++ Runtime / Universal CRT: Thuộc bản quyền của Microsoft Corporation.

Vui lòng xem đầy đủ thông báo bản quyền và toàn văn các giấy phép bên thứ ba tại THIRD_PARTY_LICENSES.md và thư mục licenses/.

About

AI Agent dịch file PDF. Phù hợp dịch cho các file *PDF tiêu chuẩn* hoặc trên máy cấu hình thấp. Dung lượng ứng dụng nhẹ, file .zip chưa đến 30MB.

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages