Areca IME

Fcitx5 · Wayland-first · Bamboo core

Gõ tiếng Việt trên Linux, theo đúng nhịp của bạn.

Areca là addon Fcitx5 viết bằng C++20. Mọi phím được xử lý tuần tự, Bamboo lo phần tiếng Việt, còn Areca chọn cách rewrite phù hợp với từng ô nhập liệu.

Cài đặt Areca Tải bản mới nhất Xem mã nguồn

Dự án đang trong giai đoạn thử nghiệm

areca · rewrite

PHÍM ĐẦU VÀO

dduowcj

BAMBOO + ARECA

được
FIFO tuần tự Rewrite hoàn tất

Được xây cho input trên Linux

Một pipeline nhỏ, rõ ràng và có kiểm soát.

Areca tách engine tiếng Việt, scheduler và backend rewrite thành những phần độc lập để dễ kiểm tra, cấu hình và thay thế.

01 · ĐÚNG THỨ TỰ

FIFO, single-flight

Key mới vẫn được nhận khi một rewrite đang chạy, nhưng luôn nằm chờ trong queue. Không có hai key cùng sửa nội dung một lúc.

02 · REWRITE THÍCH ỨNG

Nhiều backend, một kết quả

Tự động chọn SurroundingText, Shift+Left uinput, Native Libei/XTest hoặc Forward Backspace; hỗ trợ gán và đổi backend nhanh theo app.

03 · BAMBOO CORE

Xử lý tiếng Việt đã trưởng thành

Tận dụng trực tiếp bamboo-core cho Telex, VNI, kiểm tra chính tả, quy tắc đặt dấu và nhiều bảng mã Unicode.

04 · BA CHẾ ĐỘ

Chọn cách gõ phù hợp

RewriteSửa trực tiếp nội dung PreeditSoạn trước trong Fcitx5 Redirect (EN)Chuyển phím nguyên bản

Cùng bài toán, khác điểm xuất phát

Ít cấu hình thủ công hơn cho từng ứng dụng.

Không có một cách tích hợp phù hợp tuyệt đối với mọi môi trường. Areca chọn ở lại trong hệ sinh thái Fcitx5, dùng Bamboo cho phần tiếng Việt và tự thích ứng cách rewrite theo từng ô nhập liệu.

Đây là so sánh về triết lý kỹ thuật, không phải bảng xếp hạng dự án.

Hướng tiếp cận Điểm thuận lợi Điều người dùng cần cân nhắc
Chỉ dùng PreeditMột đường xử lý nhất quán

State composition nằm trong bộ gõ và bám sát giao thức input method, nhờ đó luồng xử lý thường đơn giản, dễ dự đoán.

Chữ đang soạn được hiển thị dưới dạng preedit; cảm giác nhập và cách app trình bày có thể khác với việc gõ trực tiếp vào văn bản.

Nhiều mode theo ứng dụngNgười dùng tự chọn backend

Cho phép đổi chiến lược tương thích khi một ứng dụng hoạt động tốt hơn với Preedit, SurroundingText hoặc cách rewrite khác.

Người dùng cần nhớ mode phù hợp cho từng app; trong cùng một app, vùng soạn thảo, terminal và ô tìm kiếm vẫn có thể hành xử khác nhau.

Lớp IME độc lậpTự quản lý đường tích hợp

Dự án có toàn quyền thiết kế vòng đời, giao diện và cách chuyển key mà không bị giới hạn hoàn toàn bởi một framework có sẵn.

Đổi lại, lớp tích hợp phải tự theo kịp desktop, compositor, toolkit và nhiều giao thức input khác nhau trên Linux.

Hướng của ArecaThích ứng theo từng input

Giữ Fcitx5 làm nền tảng, tự động đánh giá từng input context, đồng thời hỗ trợ phím tắt chọn nhanh và gán cố định backend cho từng ứng dụng.

Mặc định vận hành tự động không cần can thiệp; khi cần tương thích đặc thù, người dùng có thể chuyển đổi tức thì giữa Surrounding, Shift+Left, Native và ForwardKey.

Dựa trên Fcitx5

Tận dụng lifecycle, cấu hình và frontend đã có của hệ sinh thái Linux.

Nhìn vào từng ô nhập

Quyết định backend gắn với input context, không áp một phán đoán cho toàn bộ app.

Tự động trong sử dụng hằng ngày

Areca nhận phần phức tạp để người dùng ít phải đổi mode khi chuyển nơi nhập.

Không cần dịch vụ uinput

Fallback dùng Fcitx5 forwardKey(), không cần socket, daemon hay quyền truy cập thiết bị riêng.

Một pipeline liền mạch giúp giảm thành phần phải cài đặt và quản lý. Người dùng tránh được bước cấp quyền uinput vốn có thể khác nhau giữa các distro, đặc biệt trong lần cài đầu tiên.

Luồng xử lý

Mỗi phím đi qua một con đường có thể quan sát.

01Fcitx5Key event
02KeyQueueFIFO
03BambooVietnamese core
04ASurroundingTextDelete + commit
04BUinput Shift-SelectBôi đen + commit
04CNative / ForwardKeyLibei, XTest, Backspace

Không sleep main thread. Delay dùng event loop của Fcitx5.

Không chen ngang rewrite. Pipeline chỉ pump key kế tiếp sau khi hoàn tất.

Timing có thể cấu hình. Tinh chỉnh riêng cho Wayland và từng backend.

Đọc kiến trúc tổng thể Tìm hiểu Adaptive Delays

Bắt đầu

Cài đặt bằng một script.

Chạy một lệnh để tự kiểm tra hệ điều hành, tải đúng gói từ release mới nhất và cài đặt Areca. Installer sẽ hỏi trước khi cấp quyền uinput hoặc khởi động lại máy.

UbuntuArchFedoraopenSUSE
Tải bản phát hành mới nhất Xem mọi tùy chọn cài đặt
Cài đặt Areca GitHub Releases

Mở terminal và chạy lệnh sau. Installer sẽ tự chọn gói phù hợp với hệ điều hành và phiên bản hiện tại. 

curl -fsSL https://raw.githubusercontent.com/xhkzeroone/ArecaIME/main/install.sh | bash

Cần có curl và sudo. Hệ điều hành chưa có gói release sẽ được báo lỗi rõ ràng.

Sau khi cài: mở fcitx5-configtool, tìm Areca (Bamboo) và thêm vào danh sách input method.

Khắc phục lỗi uinput

Khởi nạp uinput và cấp quyền

Areca dùng /dev/uinput cho backend Backspace và Shift+Select. Installer thường đã thiết lập sẵn; nếu Areca báo không thể khởi tạo uinput, hãy chạy lần lượt các lệnh sau.

1. Nạp module và bật tự động sau khi khởi động

sudo modprobe uinput
echo uinput | sudo tee /etc/modules-load.d/areca-uinput.conf

2. Nạp lại udev rule và cấp quyền cho tài khoản

sudo udevadm control --reload-rules
sudo udevadm trigger
sudo usermod -aG input "$USER"

Sau lệnh usermod, hãy đăng xuất rồi đăng nhập lại. Nhóm input có quyền truy cập thiết bị đầu vào ở mức thấp; có thể bỏ qua bước này và để Areca dùng backend dự phòng.

3. Kiểm tra và khởi động lại Fcitx5

lsmod | grep '^uinput'
ls -l /dev/uinput
test -w /dev/uinput && echo "uinput: OK" || echo "uinput: chưa có quyền ghi"
fcitx5 -rd

Xem thêm hướng dẫn và cách cài thủ công trong README trên GitHub.

Thiết lập Fcitx5

Chọn đúng hướng dẫn cho desktop của bạn.

Areca cần Fcitx5, công cụ cấu hình và cách khởi động phù hợp với phiên desktop. Sau khi thay đổi biến môi trường, hãy đăng xuất rồi đăng nhập lại.

Cài Fcitx5 trước khi cài Areca

# Ubuntu / Debian
sudo apt install fcitx5 fcitx5-config-qt fcitx5-frontend-all

# Arch Linux / CachyOS
sudo pacman -S fcitx5-im

# Fedora
sudo dnf install fcitx5 fcitx5-autostart fcitx5-configtool fcitx5-gtk fcitx5-qt

KDE Plasma Wayland

Chọn Fcitx 5 tại System Settings → Keyboard → Virtual Keyboard. Tạo ~/.config/environment.d/fcitx.conf:

XMODIFIERS=@im=fcitx
GTK_IM_MODULE=fcitx
QT_IM_MODULE=fcitx
SDL_IM_MODULE=fcitx

Cấu hình tương thích này hỗ trợ cả app Wayland, XWayland và GTK/Qt cũ. Không thêm autostart thứ hai.

GNOME Wayland

Tạo ~/.config/environment.d/fcitx.conf:

XMODIFIERS=@im=fcitx
GTK_IM_MODULE=fcitx
QT_IM_MODULE=fcitx
SDL_IM_MODULE=fcitx

Chép org.fcitx.Fcitx5.desktop từ /usr/share/applications vào ~/.config/autostart/.

Dùng đủ module để tương thích cả ứng dụng Wayland, XWayland, GTK, Qt và SDL.

Hyprland

Thêm vào ~/.config/hypr/hyprland.conf:

env = XMODIFIERS,@im=fcitx
env = GTK_IM_MODULE,fcitx
env = QT_IM_MODULE,fcitx
env = SDL_IM_MODULE,fcitx
exec-once = fcitx5 -d

Nếu UWSM/XDG autostart đã chạy Fcitx5 thì bỏ dòng exec-once.

Niri

Thêm vào ~/.config/niri/config.kdl:

environment {
    XMODIFIERS "@im=fcitx"
    GTK_IM_MODULE "fcitx"
    QT_IM_MODULE "fcitx"
    SDL_IM_MODULE "fcitx"
}
spawn-at-startup "fcitx5" "-d"

Không thêm spawn-at-startup nếu phiên systemd đã dùng XDG autostart.

Sway / Wayland WM khác

Đặt trong ~/.config/environment.d/fcitx.conf:

XMODIFIERS=@im=fcitx
GTK_IM_MODULE=fcitx
QT_IM_MODULE=fcitx
SDL_IM_MODULE=fcitx

Thêm exec fcitx5 -d hoặc lệnh khởi động tương đương vào cấu hình compositor.

X11

Thêm vào ~/.xprofile:

export XMODIFIERS=@im=fcitx
export GTK_IM_MODULE=fcitx
export QT_IM_MODULE=fcitx
export SDL_IM_MODULE=fcitx
fcitx5 -d

Bỏ dòng cuối nếu desktop đã tự khởi động Fcitx5.

Cuối cùng mở fcitx5-configtool, bỏ chọn Only Show Current Language, tìm Areca (Bamboo) và thêm vào danh sách. Nếu gặp lỗi, chạy fcitx5-diagnose và kiểm tra máy chỉ có một tiến trình Fcitx5.

Đọc hướng dẫn đầy đủ trên GitHub

Lời cảm ơn

Areca đứng trên vai Bamboo.

Phần chuyển đổi Telex và các quy tắc tiếng Việt đến từ Bamboo Engine / bamboo-core của Lương Thành Lâm. Xin cảm ơn tác giả Bamboo, Trung Ngo (bogo.js) và Trần Kỳ Nam (GoTiengViet).

Areca và bamboo-core đều được phát hành theo giấy phép MIT.