VietTelex (ViệtTelex / ViếtTelex) là bộ gõ tiếng Việt Telex (và VNI) cho macOS, được xây dựng trên InputMethodKit của Apple để tích hợp sâu. Không gạch chân từ đang gõ, con trỏ luôn ở cuối, dấu bỏ trực tiếp vào chữ, và gõ được cả trong Terminal mà không phá autocomplete của shell.
Triết lý: tối giản, nhanh, ổn định, mã nguồn mở — cài xong là gõ, hầu như không phải chỉnh gì thêm.
Dự án của Phil Trịnh, viết lại từ đầu sau gần 20 năm dùng macOS mà chưa thấy bộ gõ tiếng Việt nào thật sự ngon, chuẩn, mượt.
VietTelex-gioi-thieu.mp4
VietTelex trong 33 giây — Telex/VNI, không gạch chân, tự giữ tiếng Anh, gõ vuốt trên điện thoại, có mặt trên mọi nền tảng.
- Chuẩn IMKit — là input method thật của hệ thống (không phải app chặn phím), nên thừa hưởng miễn phí: tự đổi kiểu gõ theo từng app, chính tả/dự đoán/viết hoa của macOS, con trỏ/undo/VoiceOver đều đúng.
- Nhanh — luật chính tả compile thành trie + bitmap, incremental parse, SIMD, zero-alloc: ~130 ns/phím, gõ nhanh cỡ nào cũng mượt.
- Gõ được ở nơi bộ gõ khác hay vỡ — Terminal/iTerm (giữ autocomplete shell), address bar Chrome, ô Excel, Spotlight; tự học theo từng app.
- Thông minh với English/code — tự khôi phục
google/github, nhận token camelCase (OmS,JavaScript) để không bỏ dấu nhầm, có Telex nghiêm ngặt. - Đúng, có số đo — bộ regression 9.091 ca: 100% từ tiếng Việt ra đúng dấu, 98,9% từ tiếng Anh bị biến dạng được khôi phục. Chi tiết + phần chưa phủ:
docs/REGRESSION.md. - Nhẹ & riêng tư — không chạy nền, không thu thập dữ liệu; chỉ gọi mạng khi bạn bấm Kiểm tra cập nhật.
| Menu trên thanh menu | Cửa sổ Cài đặt |
|---|---|
Tải cho mọi nền tảng: viettelex.com/download (iPhone/iPad · Android · macOS · Windows · Linux) · Homebrew: brew install --cask ptrinh/viettelex/viettelex
Chọn một cách cài: Homebrew hoặc .pkg. Cả hai cài cùng app đã ký vào
~/Library/Input Methods/VietTelex.app; không cài song song vì hai bộ quản lý sẽ
cùng ghi/xoá một app. Khi đổi từ Homebrew sang .pkg, chạy
brew uninstall --cask viettelex trước. Khi đổi từ .pkg sang Homebrew, chuyển
sang ABC, thoát VietTelex, xoá app ở đường dẫn trên rồi mới chạy lệnh Homebrew.
- Nếu chọn
.pkg, tảiVietTelex-x.y.z.pkgở trang tải hoặc Releases (đã ký + notarized). - Double-click → làm theo hướng dẫn (tự cài vào thư mục user, đăng ký bộ gõ, mở sẵn System Settings → Keyboard).
- Input Sources → Edit… / + → Vietnamese → ViệtTelex → Add.
| ① Input Sources → Edit… | ② + → Vietnamese → ViệtTelex → Add |
|---|---|
Để gõ trong Terminal, iTerm, Chrome/Edge/Brave: bật quyền Accessibility cho VietTelex (Privacy & Security → Accessibility). Chuyển Việt/Anh bằng phím 🌐 hoặc ⌃Space (macOS nhớ theo từng app).
s f r x j = sắc huyền hỏi ngã nặng · aa ee oo = â ê ô · aw ow uw = ă ơ ư · dd = đ · z xóa dấu.
Ví dụ: vieejt → việt · truowngf → trường · hoas → hóa.
Tùy chọn (Simple Telex, bỏ dấu tự do, kiểu cũ/mới, kiểm tra chính tả, gõ tắt) ở menu bộ gõ → Cài đặt…
Gõ kiểu VNI: menu bộ gõ → Cài đặt… → tab Tùy chỉnh → bật Gõ kiểu VNI. Dấu gõ bằng số: 1-5 = sắc/huyền/hỏi/ngã/nặng, 6 = â/ê/ô, 7 = ơ/ư, 8 = ă, 9 = đ, 0 = bỏ dấu (ví dụ Vie6t5 → Việt). Nên giữ Kiểm tra chính tả khi gõ bật để số như mp3 không bị biến thành dấu.
Cài xong gõ vẫn bị gạch chân?
Do VietTelex chưa được cấp quyền Trợ năng: System Settings → Privacy & Security → Accessibility → tick VietTelex (đã tick mà vẫn lỗi thì bỏ tick rồi tick lại). Có thể cần khởi động lại máy một lần để quyền có tác dụng.
Nếu đã bật quyền mà VietTelex vẫn báo thiếu, hãy kiểm tra bản đang chạy. Bản Debug
trong Xcode có định danh riêng và không dùng quyền của bản cài trong
~/Library/Input Methods; thoát bản Debug rồi mở lại bản đã cài. Nếu bản đã cài
vẫn báo thiếu, xoá mục VietTelex khỏi Accessibility rồi thêm lại chính app trong
~/Library/Input Methods.
Không thấy ViệtTelex trong Input Sources?
Đăng xuất/đăng nhập lại một lần rồi thêm lại.
< 7100 /details>Một app cụ thể gõ lỗi?
Menu bộ gõ → Cài đặt… → tab Bảng cơ chế gõ → thêm app (có sẵn danh sách app mở gần đây) → ép tay thử lần lượt: Tap (backspace), Gõ trực tiếp, Marked text. Cách nào gõ đúng thì báo về GitHub để bản sau thành mặc định cho mọi người.
Có hỗ trợ VNI không?
Có: Cài đặt… → tab Tùy chỉnh → bật Gõ kiểu VNI.
Ô mật khẩu không gõ được tiếng Việt?
VietTelex tự tắt trong secure field — đúng hành vi bảo mật, không phải lỗi.
Mở máy từ sleep, đang mở 1Password thì không gõ được Telex?
Không riêng VietTelex: EVKey, OpenKey, GoTiengViet cũng chết. 1Password giữ Secure Input của macOS sau khi ngủ (ô khoá vault vẫn “focus” dù bạn đang ở app khác) — macOS lúc đó vô hiệu mọi bộ gõ bên thứ ba.
Gỡ nhanh: bấm vào cửa sổ 1Password rồi bấm ra, hoặc Quit 1Password. Icon Vᵀ⃠ trên menu bar (khi đang bị chặn) sẽ chỉ đúng hướng đó. Bộ gõ có sẵn của Apple (Simple Telex) thường vẫn dùng được vì không bị disable theo lớp IME bên thứ ba.
Chi tiết: ghi chú kỹ thuật.
Gõ comment trên TikTok (Safari) bị mất chữ cuối khi ấn Enter?
Bấm một dấu cách trước khi ấn Enter là đủ chữ. Hoặc dùng Chrome cho TikTok.
Lý do: ô comment của TikTok chỉ ghi nhận từ đang gõ khi có một phím thật đi sau nó — Enter thì không đủ. Bộ gõ đã thử sáu cách xử lý hộ và không cách nào giữ được từ cuối (chi tiết trong ghi chú kỹ thuật), nên đây là giới hạn đã biết chứ không phải lỗi chưa sửa.
Gỡ cài đặt thế nào cho sạch?
Gỡ khỏi Input Sources chỉ tắt bộ gõ, chưa xoá app. Gỡ hẳn: xoá ~/Library/Input Methods/VietTelex.app (Finder → Go → Go to Folder…) rồi đăng xuất/đăng nhập. Muốn xoá luôn cài đặt cá nhân (gõ tắt, tuỳ chỉnh): xoá thêm ~/Library/Preferences/com.viettelex.settings.plist. Cài bằng Homebrew thì chỉ cần brew uninstall --cask viettelex.
Gõ Remote Desktop (Chrome Remote Desktop) bị nhảy dấu?
Khi cả hai máy đều cài VietTelex, bộ gõ local và bộ gõ remote cùng sửa một chuỗi phím — dấu Backspace của tap đua với Telex bên kia, con trỏ nhảy loạn.
Cách đúng: để VietTelex bật trên máy đang bị điều khiển (máy remote). Máy đang ngồi gõ tự tắt IME trong phiên remote (cùng cách với Windows App / Screen Sharing). Tab remotedesktop.google.com được nhận ra theo URL; các app RDP native đã passthrough sẵn.
Muốn gõ tiếng Việt vào ô tên máy / PIN trên trang Chrome Remote Desktop: chuyển sang ABC, hoặc gõ không dấu.
Cần quyền Trợ năng để bộ gõ đọc được URL tab (Chrome vốn đã cần quyền này).
Phím tắt trong app chụp màn hình (Flameshot…) không ăn?
Lỗi của framework Qt (Flameshot, OBS, VLC… dùng): shortcut trong overlay bị nuốt khi có bất kỳ bộ gõ nào đang active — bộ gõ Simple Telex có sẵn của Apple cũng dính y hệt, không riêng VietTelex (chi tiết). Khắc phục: System Settings → Keyboard → bật "Automatically switch to a document's input source", rồi một lần chuyển sang ABC khi đang ở app đó — macOS sẽ tự nhớ, các app khác vẫn gõ tiếng Việt bình thường.
Gặp lỗi? Xem hướng dẫn báo lỗi kèm cách lấy nhật ký gỡ lỗi rồi mở issue.
Build, kiến trúc, benchmark: xem docs/CONTRIBUTE.md · độ chính xác: docs/REGRESSION.md · latency: docs/BENCHMARKS.md.
MIT License — © 2026 Phil Trinh. Tự do dùng/sửa/tích hợp (kể cả thương mại), miễn giữ lại thông báo bản quyền.