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

Các bộ gõ tiếng Việt hiện tại trên macOS đang gặp một số vấn đề:

• 🚫 Không tương thích với các phiên bản macOS mới nhất
• 🐛 Nhiều bug chưa được sửa, ít được tác giả cập nhật và bảo trì
• 🔧 Thiếu tính năng hiện đại, khó debug và tùy biến linh hoạt

XKey được tạo ra để giải quyết triệt để những vấn đề trên!

• ⚡ Hiệu suất vượt trội: Viết hoàn toàn bằng Swift native, tối ưu hóa tối đa cho macOS, phản hồi tức thì
• 🎯 Tương thích hoàn hảo: Chạy mượt mà trên tất cả phiên bản macOS mới nhất
• 🔧 Ổn định & Không bug: Code base hiện đại, được test kỹ lưỡng, cập nhật thường xuyên
• 🛠️ Debug Window: Cửa sổ debug chuyên nghiệp giúp developer theo dõi real-time hoạt động của bộ gõ, phát hiện và fix lỗi nhanh chóng
• 🚀 Tính năng thông minh: Smart Switch, Macro, Quick Typing, kiểm tra chính tả
• 🎨 Giao diện hiện đại: Thiết kế theo phong cách Apple với SwiftUI
• 🔒 Bảo mật: Chạy local, không thu thập dữ liệu người dùng

• Telex: Kiểu gõ phổ biến nhất (ví dụ: tiếng → tiếng)
• VNI: Kiểu gõ truyền thống (ví dụ: tie61ng → tiếng)
• VIQR: Kiểu gõ chuẩn quốc tế (ví dụ: tie^'ng → tiếng)

• Unicode (UTF-8) - Khuyến nghị
• TCVN3 (ABC)
• VNI Windows
• Unicode Compound

Tăng tốc độ gõ với các phím tắt thông minh:

• cc → ch (ví dụ: ccao → chao)
• gg → gi (ví dụ: ggio → gio)
• kk → kh (ví dụ: kkong → khong)
• nn → ng (ví dụ: nnon → ngon)
• pp → ph (ví dụ: ppo → pho)
• qq → qu (ví dụ: qqan → quan)
• tt → th (ví dụ: tthe → the)

• f → ph (ví dụ: fo → pho)
• j → gi (ví dụ: jo → gio)
• w → qu (ví dụ: wan → quan)

• g → ng (ví dụ: mog → mong)
• h → nh (ví dụ: mih → minh)
• k → ch (ví dụ: sak → sach)

Tự động thay thế văn bản với Macro:

• Tạo các từ viết tắt tùy chỉnh
• Hỗ trợ import/export danh sách macro
• Tự động viết hoa macro
• Sử dụng macro trong cả chế độ tiếng Việt và tiếng Anh

Ví dụ:

• btw → by the way
• addr → 123 Đường ABC, Quận XYZ
• email → example@email.com

Chuyển đổi văn bản nhanh chóng:

• Chữ hoa/thường: Viết hoa tất cả, viết thường tất cả, viết hoa chữ đầu, viết hoa mỗi từ
• Bảng mã: Chuyển đổi giữa Unicode, TCVN3, VNI
• Xóa dấu: Chuyển từ có dấu sang không dấu

• Tự động phát hiện và sửa lỗi chính tả
• Khôi phục nếu sai chính tả
• Sửa lỗi tự động hoàn thành

• Tự động nhớ ngôn ngữ theo từng ứng dụng
• Chuyển đổi thông minh giữa tiếng Việt và tiếng Anh

• Giữ Ctrl để tạm tắt kiểm tra chính tả
• Giữ Option (⌥) để tạm tắt bộ gõ tiếng Việt

• Kiểu gõ hiện đại (oà/uý)
• Đặt dấu tự do (Free Mark)
• Tự động viết hoa chữ đầu câu
• Cho phép phụ âm Z, F, W, J

Cửa sổ debug chuyên nghiệp giúp theo dõi hoạt động của bộ gõ:

• 📊 Real-time monitoring: Xem trực tiếp các sự kiện bàn phím
• 🔍 Input tracking: Theo dõi quá trình xử lý từng ký tự
• 🧪 Engine state: Kiểm tra trạng thái của Vietnamese engine
• 🐛 Bug detection: Phát hiện và debug lỗi nhanh chóng
• 📝 Event logging: Ghi lại toàn bộ sự kiện để phân tích

Bật Debug Window trong Cài đặt → Nâng cao → Bật chế độ Debug

• Biểu tượng trên thanh trạng thái (Menu Bar)
  • Chọn giữa chữ X hoặc chữ V làm biểu tượng
  • Tự động đổi màu khi bật/tắt tiếng Việt
• Phím tắt tùy chỉnh để bật/tắt tiếng Việt
• Khởi động cùng hệ thống
• Kiểm tra cập nhật tự động

• macOS 12.0 (Monterey) trở lên
• Quyền truy cập Accessibility (sẽ được yêu cầu khi chạy lần đầu)

1. Tải file Xkey.app.zip mới nhất từ Releases
2. Giải nén và kéo XKey.app vào thư mục Applications
3. Mở XKey từ Applications
4. Cấp quyền Accessibility khi được yêu cầu:
   • Mở System Settings → Privacy & Security → Accessibility
   • Bật quyền cho XKey

Nếu máy Mac có nhiều user accounts và bạn gặp lỗi "You can't open the application because someone else is using it", hãy cài đặt theo cách sau:

Mỗi user cài XKey vào thư mục Applications riêng của mình:

# Tạo thư mục Applications cho user (nếu chưa có)
mkdir -p ~/Applications

# Di chuyển XKey.app vào thư mục user
mv /Applications/XKey.app ~/Applications/

Hoặc kéo thả XKey.app vào ~/Applications/ (thư mục Applications trong Home folder).

Nếu muốn giữ XKey trong /Applications chung:

1. User A: Sử dụng /Applications/XKey.app
2. User B: Copy XKey.app vào ~/Applications/XKey.app

• ✅ Mỗi user cần cấp quyền Accessibility riêng trong System Settings
• ✅ Preferences (cài đặt) của mỗi user được lưu độc lập
• ✅ Macro và Smart Switch data của mỗi user cũng riêng biệt
• ✅ Nếu muốn XKey tự khởi động, mỗi user cần thêm vào Login Items riêng

# Clone repository
git clone https://github.com/xmannv/xkey.git
cd xkey

# Mở project với Xcode
open XKey.xcodeproj

# Hoặc build bằng script
./build_release.sh

• Sử dụng phím tắt (mặc định: có thể tùy chỉnh trong Settings)
• Click vào biểu tượng XKey trên Menu Bar

1. Click vào biểu tượng XKey trên Menu Bar
2. Chọn Cài đặt (Settings)
3. Tùy chỉnh theo nhu cầu:
   • Cơ bản: Kiểu gõ, bảng mã, phím tắt
   • Gõ nhanh: Bật/tắt Quick Typing
   • Nâng cao: Chính tả, Smart Switch, tạm tắt
   • Macro: Quản lý text shortcuts
   • Chuyển đổi: Công cụ chuyển đổi văn bản
   • Giao diện: Tùy chỉnh hiển thị
   • Giới thiệu: Thông tin phiên bản, kiểm tra cập nhật

XKey/
├── XKey/
│   ├── App/              # Entry point
│   ├── Core/             # Core engine
│   │   ├── Engine/       # Vietnamese input engine
│   │   └── Models/       # Data models
│   ├── EventHandling/    # Keyboard event handling
│   ├── UI/               # SwiftUI views
│   └── Utilities/        # Helper utilities
├── XKeyTests/            # Unit tests
└── Release/              # Build output

• Swift Native: 100% Swift code, tối ưu hiệu suất tối đa cho macOS
• SwiftUI: Giao diện người dùng hiện đại
• Combine: Reactive programming
• Core Graphics: Event handling
• Accessibility API: Keyboard monitoring

XKey được viết hoàn toàn bằng Swift native thay vì Objective-C hay các ngôn ngữ khác vì:

• ⚡ Hiệu suất cao hơn: Swift được tối ưu hóa cho Apple Silicon và Intel
• 🎯 Memory safety: Quản lý bộ nhớ tốt hơn, ít crash hơn
• 🔧 Modern syntax: Code dễ đọc, dễ maintain, dễ mở rộng
• 🚀 Future-proof: Được Apple hỗ trợ và phát triển tích cực

Chúng tôi hoan nghênh mọi đóng góp! Vui lòng:

1. Fork repository
2. Tạo branch mới (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add some AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Mở Pull Request

XKey được phát triển dựa trên:

• OpenKey: Bộ gõ tiếng Việt mã nguồn mở
• Unikey: Bộ gõ tiếng Việt phổ biến

Cảm ơn cộng đồng đã đóng góp và hỗ trợ!

Dự án được phát hành dưới giấy phép MIT. Xem file LICENSE để biết thêm chi tiết.

• Issues: GitHub Issues
• Discussions: GitHub Discussions