Popup Lookup - Definition & Translation (Anki Add-on)

Add-on tra cứu từ và dịch nhanh trong Anki Desktop bằng popover khi bạn bôi đen 1 từ hoặc 1 đoạn văn bản.
Mục tiêu
- Tra cứu từ điển tiếng Anh ngay trên card.
- Dịch nhanh đoạn văn (EN -> VI mặc định).
- Phát âm từ bằng biểu tượng audio.
- UI popover/subpanel tối ưu để đọc nhanh trong quá trình học.
Tính năng chính
- Lookup 1 từ: hiển thị word, phiên âm, audio, part-of-speech, definitions, examples.
- Translate 1 đoạn: dịch online qua API.
- Sub panel hiển thị chi tiết meanings và definitions, có phân tách để dễ phân biệt.
- CSS đã được scope/reset để giảm ảnh hưởng global style từ Anki.
Yêu cầu
- Anki Desktop (không hỗ trợ chạy add-on trên AnkiWeb).
- Python 3 (để chạy script dev/build).
- Kết nối internet cho dictionary API và translation API.
Cài đặt local (developer)
- Clone repo vào máy.
- Chạy deploy local vào thư mục add-on của Anki:
python scripts/deploy_to_anki.py
Script sẽ copy source vào addons21, restart Anki nếu đang mở.
Cấu hình
File cấu hình chính: config.json
Các khóa quan trọng:
source_language: ngôn ngữ nguồn (mặc định en)
target_language: ngôn ngữ đích (mặc định vi)
show_example: hiện/ẩn ví dụ trong definitions
max_definitions: giới hạn số definition mỗi meaning
enable_lookup, enable_translate, enable_audio: bật/tắt tính năng runtime
Kiến trúc thư mục
__init__.py: entrypoint Anki hooks + JS bridge.
features/lookup/: xử lý lookup flow.
features/translate/: xử lý translate flow.
services/dictionary_api.py: gọi dictionary API.
services/translation_service.py: gọi translation API (online).
web/popup.js, web/popup.css: giao diện và tương tác popover.
scripts/deploy_to_anki.py: deploy local vào Anki.
scripts/build_release.py: đóng gói release artifacts.
Build release artifacts
Từ root repo:
python scripts/build_release.py
Mặc định sinh 2 file trong dist/:
anki_popup_lookup.zip
anki_popup_lookup.ankiaddon
Nếu cần version suffix:
python scripts/build_release.py --version 1.2.0
Publish lên GitHub Releases tự động
Repo đã có workflow:
.github/workflows/release-addon.yml
Cách dùng:
- Push code.
- Tạo tag release:
git tag v1.2.0
git push origin v1.2.0
- GitHub Actions sẽ tự động build và upload 2 artifacts vào tab Releases.
Chia sẻ cho người dùng Anki
- Upload artifact lên AnkiWeb Shared Add-ons để nhận add-on code.
- Người dùng Anki Desktop cài bằng:
Tools -> Add-ons -> Get Add-ons...
- Nhập code add-on.
Ghi chú
- Add-on không chạy trực tiếp trên website AnkiWeb.
- Nếu chạy script từ thư mục
scripts/, dùng lệnh:
python build_release.py
Nếu chạy từ root repo, dùng:
python scripts/build_release.py