PHTV — Precision Hybrid Typing Vietnamese

Bộ gõ tiếng Việt hiện đại cho macOS

Tải về | Tài liệu | Báo lỗi | FAQ | ☕ Ủng hộ

</div>

Giới thiệu

PHTV (Precision Hybrid Typing Vietnamese) là bộ gõ tiếng Việt offline, nhanh, và riêng tư cho macOS 14+. Được phát triển hoàn toàn bằng Swift/SwiftUI, mang đến trải nghiệm gõ tiếng Việt mượt mà và tích hợp sâu vào hệ thống.

✨ Tự động cập nhật - Nhận phiên bản mới ngay khi ra mắt với Sparkle framework. Không cần tải lại thủ công!

🚀 Quick Start

# Cài đặt bằng Homebrew
brew install --cask phamhungtien/tap/phtv

# Mở ứng dụng
open /Applications/PHTV.app

⚠️ Quan trọng: Trước khi sử dụng, bạn phải tắt các tính năng tự động sửa lỗi của macOS (Correct spelling, Capitalize words,...) trong System Settings → Keyboard → Edit Input Sources để tránh xung đột. Xem hướng dẫn chi tiết tại đây.

Sau khi cài:

Cho phép quyền Accessibility trong System Settings
Click icon En trên menu bar → chọn Vi để bật tiếng Việt
Nhấn Control + Shift để chuyển đổi Việt/Anh (tùy chỉnh trong Settings)
Bắt đầu gõ! 🎉

Tính năng

Cốt lõi

Hoàn toàn offline - Không cần Internet, bảo mật tuyệt đối
Telex, VNI, Simple Telex - Đầy đủ các phương pháp gõ phổ biến
Nhiều bảng mã - Unicode, TCVN3 (ABC), VNI Windows, Unicode Compound
Native macOS - Giao diện SwiftUI hiện đại, hỗ trợ Dark Mode

Gõ thông minh

Kiểm tra chính tả - Tự động phát hiện từ sai chính tả
Chính tả hiện đại - Hỗ trợ quy tắc "oà, uý" thay vì "òa, úy"
Gõ tắt nhanh (Quick Telex) - cc→ch, gg→gi, kk→kh, nn→ng, qq→qu, pp→ph, tt→th
Phụ âm đầu/cuối nhanh - f→ph, j→gi, w→qu (đầu) và g→ng, h→nh, k→ch (cuối)
Tự động viết hoa - Viết hoa chữ cái đầu câu sau dấu chấm
Tự động khôi phục - Hỗ trợ 2 chế độ: khôi phục nếu không phải tiếng Việt hoặc chỉ khôi phục nếu là tiếng Anh (VD: "tẻminal" → "terminal")
Vietnamese consonant detection - Logic thông minh phân biệt từ tiếng Việt có dấu và từ tiếng Anh (VD: "đi" vs "did", "fix" vs "fi")

Macro & Text Snippets

Gõ tắt thông minh - Định nghĩa từ viết tắt tùy ý (VD: "btw" → "by the way")
Text Snippets - Gõ tắt động với ngày, giờ, clipboard, random, counter
Tự động viết hoa macro - "Btw" → "By the way", "BTW" → "BY THE WAY"
Hoạt động ở cả 2 chế độ - Macro hoạt động cả khi gõ tiếng Việt và tiếng Anh
Import/Export - Nhập xuất danh sách macro từ file
Danh mục - Tổ chức macro theo nhóm với icon và màu sắc

Lịch sử Clipboard

Lưu nội dung đã sao chép - Tự động lưu văn bản, ảnh, đường dẫn file vào lịch sử
Dán nhanh bằng phím tắt - Mặc định ⌃V (Control + V), tuỳ chỉnh trong Settings
Tìm kiếm - Tìm nhanh trong danh sách nội dung đã sao chép
Giao diện Liquid Glass - Đồng bộ với PHTV Picker, hỗ trợ kéo di chuyển
Tuỳ chỉnh - Giới hạn số mục lưu (10–100), mặc định tắt

PHTV Picker (Emoji & GIF)

Giao diện Liquid Glass - Thiết kế hiện đại theo chuẩn Apple với hiệu ứng glass morphism
1,463 Emoji từ Unicode v17.0 - Đầy đủ emoji mới nhất với categories và tìm kiếm
GIF không giới hạn - Tích hợp Klipy API với hàng ngàn GIF miễn phí
Tìm kiếm thông minh - Tìm Emoji/GIF theo từ khóa tiếng Việt và tiếng Anh
Auto-paste - Click là gửi ngay, không cần Cmd+V
Multi-format support - Hoạt động với iMessage, Zalo, Messenger Web và các app khác
Auto cleanup - Tự động xóa file GIF đã tải sau 5 giây
Ad-supported - Miễn phí hoàn toàn nhờ quảng cáo từ Klipy
Hotkey tiện lợi - Cmd+E (tùy chỉnh được) để mở nhanh

Tương thích ứng dụng

Keyboard Layout Compatibility - Hỗ trợ Dvorak, Colemak và các bố cục bàn phím đặc biệt
Claude Code Support - Tự nhận diện session Claude Code trong Terminal/IDE và áp timing profile ổn định hơn, không cần patch riêng
Safe Mode - Tự động khôi phục khi Accessibility API gặp lỗi
Excluded Apps - Danh sách ứng dụng tự động chuyển sang tiếng Anh
Send Key Step-by-Step - Gửi từng phím riêng lẻ cho ứng dụng tương thích kém
Nhớ bảng mã theo ứng dụng - Tự động chuyển bảng mã phù hợp cho từng app

Phím tắt & Điều khiển

Phím chuyển ngôn ngữ tùy chỉnh - Control, Option, Command, Shift hoặc tổ hợp
Tạm tắt tiếng Việt - Giữ phím để tạm thời gõ tiếng Anh
Khôi phục ký tự gốc - Nhấn ESC để hoàn tác dấu (VD: "việt" → "viejet")
Smart Switch - Tự động nhớ ngôn ngữ cho từng ứng dụng

Phát hiện bàn phím non-Latin

Tự động chuyển về English - Khi dùng bàn phím Nhật, Trung, Hàn, A Rập, Thái, Hindi...
Khôi phục tự động - Chuyển lại bàn phím Latin sẽ khôi phục chế độ tiếng Việt
Hỗ trợ đa dạng - Japanese, Chinese, Korean, Arabic, Hebrew, Thai, Greek, Cyrillic, v.v.

Hệ thống

Khởi động cùng macOS - Tùy chọn chạy khi đăng nhập
Hot Reload - Thay đổi cài đặt không cần khởi động lại
Tự động cập nhật (Sparkle) - Kiểm tra và cập nhật phiên bản mới tự động từ GitHub với EdDSA signing bảo mật
Import/Export cài đặt - Sao lưu và khôi phục toàn bộ settings
Menu bar icon - Hiển thị trạng thái Vi/En trên thanh menu
Báo lỗi thông minh - Tự động thu thập log debug, thống kê lỗi, gửi qua GitHub/Email

Screenshots

Menu Bar & PHTV Picker

<table> <tr> <td width="20%" align="center"> <img src="docs/images/ui/menubar_ui.png" alt="Menu Bar UI" width="200"> Menu Bar </td> <td width="26%" align="center"> <img src="docs/images/ui/PHTV_Picker_1_Emoji.png" alt="PHTV Picker - Emoji" width="280"> Emoji Picker </td> <td width="26%" align="center"> <img src="docs/images/ui/PHTV_Picker_2_GIF.png" alt="PHTV Picker - GIF" width="280"> GIF Picker </td> <td width="26%" align="center"> <img src="docs/images/ui/PHTV_Picker_3_Sticker.png" alt="PHTV Picker - Sticker" width="280"> Sticker Picker </td> </tr> </table>

Settings

<table> <tr> <td width="25%" align="center"> <img src="docs/images/Setting_1_bogo.png" alt="Settings - Bộ gõ" width="100%"> Bộ gõ </td> <td width="25%" align="center"> <img src="docs/images/Setting_2_phimtat.png" alt="Settings - Phím tắt" width="100%"> Phím tắt </td> <td width="25%" align="center"> <img src="docs/images/Setting_3_gotat.png" alt="Settings - Gõ tắt" width="100%"> Gõ tắt </td> <td width="25%" align="center"> <img src="docs/images/Setting_4_ungdung.png" alt="Settings - Ứng dụng" width="100%"> Ứng dụng </td> </tr> <tr> <td width="25%" align="center"> <img src="docs/images/Setting_5_hethong.png" alt="Settings - Hệ thống" width="100%"> Hệ thống </td> <td width="25%" align="center"> <img src="docs/images/Setting_6_baoloi.png" alt="Settings - Báo lỗi" width="100%"> Báo lỗi </td> <td width="25%" align="center"> <img src="docs/images/Setting_7_thongtin.png" alt="Settings - Thông tin" width="100%"> Thông tin </td> <td width="25%"></td> </tr> </table> </div>

Cài đặt

Homebrew (khuyên dùng)

brew install --cask phamhungtien/tap/phtv

💡 Tự động cập nhật: Sau khi cài, PHTV sẽ tự động kiểm tra và thông báo khi có phiên bản mới. Không cần brew upgrade thủ công!

Cập nhật thủ công qua Homebrew (nếu muốn):

brew upgrade --cask phtv

Gỡ cài đặt:

# Gỡ ứng dụng
brew uninstall --cask phtv

# Gỡ sạch (bao gồm cả settings)
brew uninstall --zap --cask phtv

Tải trực tiếp

# Tải từ website
open https://phamhungtien.com/PHTV/

# Hoặc từ GitHub Releases
open https://github.com/PhamHungTien/PHTV/releases/latest

Build từ source

git clone https://github.com/PhamHungTien/PHTV.git
cd PHTV/App
open PHTV.xcodeproj
# Build với Cmd+B, chạy với Cmd+R

Lưu ý: Ứng dụng cần quyền Accessibility để hoạt động. Vào System Settings > Privacy & Security > Accessibility và thêm PHTV.

Xem chi tiết kiến trúc: docs/ARCHITECTURE.md

🤖 CI/CD & Release Automation

PHTV sử dụng GitHub Actions để tự động build, sign, và release:

✅ Tự động build trên macOS 26 với Xcode
✅ Code signing với Apple Development certificate
✅ Tạo DMG với Applications shortcut
✅ Sparkle signing cho auto-update bảo mật
✅ Auto-update Homebrew formula và appcast.xml
✅ Auto-increment build number cho mỗi release

Xem chi tiết tại .github/workflows/README.md

Sử dụng

Phím tắt mặc định

| Phím tắt | Chức năng | | --- | --- | | Control + Shift | Chuyển Việt/Anh (tùy chỉnh được) | | ESC | Khôi phục ký

PHTV

Install / Use

README