User guide

iPhone / iPad

Get VietTelex on the App Store (download page), then go to Settings → General → Keyboard → Keyboards → Add New Keyboard… → Vietnamese (VietTelex). While typing, tap 🌐 to switch to VietTelex. Try it right away in the app's Thử gõ box: vieejt → việt.

Android

Get it from the download page. Settings → System → Languages & input → On-screen keyboard → Manage → enable VietTelex, then select it (the app has a Chọn VietTelex button). The “may collect all the text you type” warning is Android's generic notice for every third-party keyboard — VietTelex runs entirely on-device.

macOS

• Install one way: download VietTelex-x.y.z.pkg (signed & notarized) and double-click it, or run brew install --cask ptrinh/viettelex/viettelex. Don't install through both channels.
• The installer opens System Settings → Keyboard: Input Sources → Edit… → ＋ → Vietnamese → ViệtTelex → Add.
• To type in Terminal, iTerm, Chrome/Edge/Brave: grant Accessibility (Privacy & Security → Accessibility → tick VietTelex); a one-time restart may be needed.
• Switch Vietnamese/English with 🌐 or ⌃Space like any macOS input source (macOS remembers it per app). VietTelex settings: the Vᴛ menu bar icon → Cài đặt… (Settings…).

Windows

• Download the .msi from the download page (or GitHub Releases): …-x64.msi for Intel/AMD PCs, …-arm64.msi for ARM (Snapdragon). Requires Windows 10 1903 or later. The installer is code-signed.
• Run it — no restart needed. When it finishes, the VietTelex Settings window opens; later, open it from VietTelex in the Start menu.
• VietTelex is a system Vietnamese keyboard: pick it with WinSpace. Not in the list? Open VietTelex once from the Start menu, or add it under Settings → Time & language → Language → Vietnamese → Keyboards.
• Upgrading: install the new MSI over the old one, or use Check for updates in the app.

Linux (Ubuntu 22.04 / 24.04, amd64 + arm64)

VietTelex is an input method for Fcitx5 (recommended) or IBus (the Ubuntu/GNOME default). Quickest: curl -fsSL https://viettelex.com/install.sh | bash (see the download page). Or add the APT repository yourself (updates arrive via apt upgrade):

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://ptrinh.github.io/viettelex-apt/viettelex-archive-keyring.gpg \
  | sudo tee /etc/apt/keyrings/viettelex.gpg >/dev/null
sudo tee /etc/apt/sources.list.d/viettelex.sources >/dev/null <<EOF
Types: deb
URIs: https://ptrinh.github.io/viettelex-apt/
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: main
Signed-By: /etc/apt/keyrings/viettelex.gpg
EOF
sudo apt update
sudo apt install viettelex-fcitx5   # or: sudo apt install viettelex-ibus

• Or download the .deb files (with SHA256) from the download page (~jammy1 = 22.04, ~noble1 = 24.04) and run sudo apt install ./libviettelex-core_*.deb ./viettelex-fcitx5_*.deb ./viettelex-settings_*_all.deb — this route does not auto-update.
• Then open VietTelex from the app menu (or viettelex-settings --onboarding) and follow the setup guide. Fcitx5: im-config -n fcitx5, log in again (first time only), then click Thêm (Add). IBus (GNOME): ibus restart, then Settings → Keyboard → Input Sources → + → Vietnamese → VietTelex (or click Thêm in the guide).
• Switch Vietnamese/English: CtrlSpace. Changes in the settings app apply immediately — no input-method restart.

• VNI — tones as digits while inside a word: 1 acute, 2 grave, 3 hook, 4 tilde, 5 dot, 6 circumflex (â ê ô), 7 horn (ơ ư), 8 breve (ă), 9 đ, 0 remove: tie6ng1 vie6t5 → tiếng việt. Outside a word, digits stay digits. Picking VNI turns on the number row.
• Simple Telex (Telex đơn giản) — a lone w stays w instead of ư.
• Free tone placement (Bỏ dấu tự do) — tone keys can go anywhere in the word.
• Quick Telex — doubled initial consonants: cc → ch, nn → ng, tt → th…
• New-style tones (Bỏ dấu kiểu mới) — hoà, thuý instead of hòa, thúy.
• Bracket vowels: [ types ơ, ] types ư (off by default) — the UniKey habit: th[ → thơ. Leave it off if you write code. macOS Windows Linux
• Auto-capitalise sentences (Tự động viết hoa đầu câu; on by default) — shift turns on at the start of a field, after . ! ? and on a new line. On iPhone the system Auto-Capitalisation switch in Settings → Keyboards doesn't apply to third-party keyboards — turn it off here. iOS Android
• Context-aware (Quyết định theo ngữ cảnh) — after an English word, an ambiguous next word stays English: “he is”, not “he í”.
• Words that are both English and Vietnamese (last/lát, list/lít, his/hí): Vietnamese wins by default — double the tone key to keep English (lisst → list). macOS Windows Linux
• Auto-restore English — non-Vietnamese words go back to what you typed (google, github…). Live spell check stops adding tones as soon as a word can't be Vietnamese.
• Teencode spelling (off by default) — accepts wá, zui zẻ, kó, bíe, thík, gòy, ừk.
• Keyboard layout — type Telex on Colemak, Dvorak…; left on “follow”, it uses the layout of the input source you switched from. macOS

• Delete the space to reopen the word: tháy ␣ ⌫ a → thấy.
• Put the cursor right after a word and type a tone key s f r x j: viêt + j → việt; chao + f → chào (VNI: digits 1–5, 0).
• Linux Only in apps that let the input method edit text around the cursor (many GTK/Qt apps); not in terminals, browsers and other apps.

• Glide over the unaccented letters of a syllable and lift: v→i→e→t gives “việt”.
• Type a tone key (s f r x j) right after to change the tone; ⌫ right after deletes the whole swiped word; the suggestion bar lists alternatives.
• Swipe English words (on by default with swipe typing): check, mail, file, meeting… When a path is both Vietnamese and English (the/thế, can/cần), Vietnamese wins unless you're typing English, and the other option stays on the bar.
• Neural swipe model (Mô hình neural gõ vuốt; optional, off by default): adds the FUTO Swipe neural network, running fully on-device, to score alongside the built-in decoder — about 3 MB extra memory while the keyboard is open.
• Disabled with VoiceOver/TalkBack and in password, email and URL fields. On iOS it's iPhone-only (not iPad).

• Type the abbreviation, then space, Enter or punctuation: ko → không.
• Type the abbreviation, then space: ko → không.
• Case follows your typing (when the key is stored lowercase): ko → không, Ko → Không, KO → KHÔNG.
• Keys with symbols or digits (->, k2) expand on space.
• ⌫ right after an expansion restores what you typed.
• ⌥↩ adds a line break inside an expansion. macOS
• No expansion right after a digit or / # @ (5h, /h3), or in password, email and URL fields.
• Dùng Thay thế văn bản của iOS (use iOS Text Replacement) iOS, on by default: entries from Settings → General → Keyboard → Text Replacement expand like shortcuts; read-only (edit them in iOS Settings), and VietTelex's own table wins on a clash. Android has no equivalent list readable by third-party keyboards.
• The table starts empty; Thêm bộ gợi ý adds: ko, dc, đc, vs, mn, trc, cty, bsi, stk, -> (→).
• Import/export YAML key: expansion — the same format on Mac, iPhone, Android, Windows and Linux. Import also accepts JSON and plain key:value text.

• Word suggestions that learn the words you use (stored on-device only). Personal dictionary (Từ điển cá nhân): view, search, delete learned words, add names and terms. Sensitive-word filter never proactively suggests profanity.
• Mistap suggestions (Kiểu Gõ tab): nbjeeuf → nhiều, ohims → phím — shown on the bar, tap to replace.
• Emoji suggestions matching the current word (yêu → ❤️).
• Number chips: after typing a number — spell it out in words, format as money (1tr2 → 1.200.000 ₫).
• Typo fixes (on by default; turn off in Tùy chỉnh → “Gợi ý sửa lỗi gõ sai”): hit a neighbouring key or swap two keys (tpoi, khpong) and type a space or comma — the fix (tôi, không) appears under the cursor, only when it is very likely; press Tab to replace (the space/punctuation stays). Never automatic; English words, chat words and valid words are left alone. Esc stops suggesting that word.
• Tones for unaccented sentences (off by default; turn on in Tùy chỉnh → “Gợi ý thêm dấu cho câu không dấu”): after 3+ unaccented syllables (toi di hoc) type . ! ? or pause for about a second after a space — the toned text (tôi đi học) appears under the cursor; press Tab to replace the whole run. Enter never triggers it (it may have sent the message); typing on cancels it.
• Dates and times (on by default; turn off in Tùy chỉnh → “Gợi ý ngày giờ”): type hôm nay, ngày mai, hôm qua and a space for the date (28/09/2026), bây giờ for the time (21:35); after an English word, today, tomorrow, yesterday, now work too. Press Tab to replace the words with it; keep typing or press Esc to keep the words.
• Show maths results: type a sum followed by = (12*3=, 1.5+2=) → the result appears first in the suggestion bar; tap to insert it after the =.
• Paste button: right after you copy something, the bar shows a Paste card. iOS needs Full Access; to stop iOS asking every time: Settings → VietTelex → Paste from Other Apps → Allow.
• “Thêm dấu” chip Plus (off by default): after a sentence typed without tones, one tap adds them all — hom nay troi dep → hôm nay trời đẹp. Turn it on in Features → Suggestions & dictionary (or right on the VietTelex Plus screen); type the sentence without tones, press space, and the “Thêm dấu” chip appears at the start of the suggestion bar — tap it to add tones, tap “Hoàn tác” (Undo) to revert.

• Tap ☰ on the suggestion bar for a grid of saved phrases; tap one to insert it. A short label (emoji) keeps the grid compact.
• While the snippet grid is open, the 😊 key becomes a trash can that clears the whole field.
• Live snippets: content starting with https:// is fetched when you tap it and the result is inserted (max 1000 bytes) — e.g. “🌐 IP” inserts your current IP address. iOS needs Full Access. Without network the URL itself is inserted.
• Import/export YAML - "👋 | Chào buổi sáng"; importing merges. Android can also add a snippet by sharing text from another app to VietTelex. iOS the ⚙️ tile at the end of the grid opens the Mẫu Câu tab.
• Text tools Plus: the Aa chip at the top of the snippet grid — UPPERCASE, lowercase, Title Case, Sentence case, remove tones; applied to the selection or the sentence before the cursor.

• Clipboard history (off by default): the 📋 button on the bar opens up to 20 recent copies — tap to paste, pin to keep. Unpinned items expire after 1 hour (password/OTP-like: 2 minutes). Password fields and content marked sensitive are skipped. iOS needs Full Access.
• Number-split chips Plus: when the copied text contains a bank account / phone number / OTP, a “Dán STK…” chip pastes just the number. Unlimited pins are also Plus.
• Incognito mode: no word learning, no clipboard saving. Android turns it on automatically in private-browser fields.

• The 😊 key opens a full emoji keyboard with a Recents 🕐 group.
• Search emoji in Vietnamese: tap the search bar at the top; tones are optional — cuoi → 😀 “mặt cười”. Tap a result to insert it.
• A kaomoji / special characters tab (^‿^) at the end of the category strip.

• Ngôn ngữ / Language (first item in Tính Năng / Features): switch the app and keyboard labels between Tiếng Việt (default) and English — applies immediately.
• Themes & wallpaper: System, OLED dark and High contrast are always free; other themes (Hồng đào, Bạc hà, Trời xanh, Oải hương, Kính…) and a custom background image (overlay dimming, blur) are Plus. Images are compressed on-device.
• Key transparency and label transparency (0–100%, free with every theme): keys — background, wallpaper, key fill and borders, at 100% only the labels remain; labels — letters and icons on the keys, at 100% the keys are blank. iOS always keeps its own frosted-glass layer behind the keyboard.
• Restore default look (Khôi phục giao diện gốc): back to the System theme, wallpaper off (the image is kept), dimming/blur and transparency reset.
• Row height ±10 and the faint Vᴛ logo on the space bar (Giao diện); number row 1…0 above the letters (Phím & cử chỉ).
• Hold top row for digits (shown while the number row is off) and hold rows 2–3 for symbols — see Hidden gestures.
• Add space after punctuation (Phím & cử chỉ, off by default): typing . , ? ! ; : adds a space after it. Not inside numbers (3.5, 1,000), emails, links, or in email/web/number/password fields. A space typed right after doesn't double up; ⌫ right after removes just that space; a closing bracket/quote moves the space after it (hi.)␣).
• Swipe the space bar to switch Vietnamese / English (Phím & cử chỉ, off by default): flick the space bar left/right; while on, the space bar's bottom-right corner shows a faint VI / EN like the stock keyboard (instead of the Vᴛ logo).
• Key preview pop-ups, haptics (iOS needs Full Access).
• Key sound (Phím & cử chỉ, off by default): VietTelex's own key sound (letter / delete / function keys sound different) with a Volume slider 0–100%; pick a Sound style: Soft (default, low and gentle), Wood tap, Mechanical, Typewriter, Bubble — or Your sound (a short audio file you choose; leading silence trimmed, at most 0.3 s kept, loudness made safe; the file stays on the device and isn't in backups). Dragging the Volume / Vibration strength sliders or picking a style previews it right away; never doubles up with the system click, doesn't interrupt your music, and stays quiet in silent or vibrate mode. Off = the system keyboard click as before. iOS needs Full Access (without it you get the iOS click).
• One-handed mode (phones): Off / Left / Right — shrinks the keyboard to one side; buttons in the empty strip switch sides or exit. Quick toggle via the gesture in Hidden gestures.
• Smart key selection Experimental (Tính Năng → Chính tả & sửa lỗi, on by default): a tap right on the edge between two keys picks the one that fits the word; a tap in the middle of a key always gives that key, and typed text is never auto-corrected.
• Auto-correct typos Experimental (Tính Năng → Chính tả & sửa lỗi, off by default): when you press space, if the word you just typed isn't a valid word and a tap clearly leaned onto the neighbouring key, it is replaced with the common word (tpoi → tôi). Only confident fixes; English words, words you use often and password/email/web fields are left alone. Press ⌫ right after (or tap the ↩︎ original chip on the suggestion bar) to get your original word back — that word won't be corrected again.

• Text-editing panel: tap the cursor icon on the suggestion bar — arrows, line start/end, select / select word / select all, copy / cut / paste, undo / redo; the last row holds the text tools Plus.
• Telex for hardware keyboards (Tính Năng → Phím & cử chỉ → Bàn phím cứng): type Telex/VNI on Bluetooth/USB keyboards, Samsung DeX, Chromebook; Ctrl/Alt shortcuts still reach the app.
• Number / phone / date fields open a dedicated number pad.

• Export / import a backup file: settings, shortcuts, snippets (and learned words if “Kèm từ đã học” is on) — one file that opens on iPhone, iPad and Android. Import: settings follow the file, shortcuts and snippets are merged.
• iCloud sync iOS Plus: settings, shortcuts and learned words follow you to other devices on the same Apple ID.
• iCloud sync macOS: Settings… → Tùy chỉnh → Đồng bộ cài đặt gõ và gõ tắt với iPhone/iPad (sync typing settings and shortcuts; needs iCloud sign-in).
• Android also backs settings up to Google (system backup) when you enable it.

The Vᴛ menu bar menu

• Cơ chế gõ: … (typing mode) of the current app — click to open the Typing modes table and copy debug info for a bug report.
• Text tools (enable in Tùy chỉnh → “Hiện công cụ văn bản trong menu VietTelex”): select text in any app, then open the VietTelex menu → Công cụ… (Tools…; a small panel appears next to the cursor — click a button or press 1–6, Esc closes) — add tones to the selection (toi di hoc → tôi đi học), UPPERCASE, lowercase, Title Case, Sentence case, remove tones.
• Maths results (on by default; turn off in Tùy chỉnh → “Hiện kết quả phép tính”): type a calculation followed by = (12*3=, 200+10%=) — “= 36” appears right under the cursor (the macOS candidate window, or a small “⇥ Tab” hint in terminals/browsers); press Tab or Enter to insert the result, Esc or any other key dismisses it.
• Number chips (on by default; turn off in Tùy chỉnh → “Chip số”): type an amount with k/tr/tỷ and a space (50k, 1tr2, 2 tỷ) — the money format “1.200.000 ₫” appears under the cursor; press Tab to replace, any other key dismisses it.
• Cài đặt… opens VietTelex settings; Cài đặt hệ thống… opens Keyboard → Input Sources.

Hotkeys

• Switch Vietnamese/English: macOS's 🌐 or ⌃Space; the Cài đặt hotkey… button opens Keyboard Shortcuts → Input Sources to change it.
• Switch hotkey Experimental (Thử nghiệm tab): press and release ⌃⇧, ⌥⇧ or ⌘⇧ alone to toggle between VietTelex and your previous input source — modifier-only combos macOS can't assign. Ignored if you type a key or click while holding them. Needs Accessibility.
• Add-tones hotkey (off by default): ⌃⌥T, ⌃⇧T or ⌥⌘T — adds tones to the selected text in any app, even while another input source is active. Needs Accessibility (copies the selection, then pastes the result; your clipboard is restored).

An app types wrong? The typing modes table

• Bảng cơ chế gõ tab: VietTelex learns how to type in each app; you can pin a mode by hand — Tap (real keystrokes, no underline, needs Accessibility), Marked text (always renders correctly but underlines while typing), Gõ trực tiếp (in-place), Passthrough (IME off in that app)… A button clears the learned data (manual pins are kept). YAML import/export.
• Per-app details: Typing modes in VietTelex (Vietnamese).
• Keep VietTelex when macOS auto-switches the input source Experimental: some apps (Word comments…) make macOS fall back to the default input source in every new field; this switches back to VietTelex — only when the change wasn't yours.
• Ẩn tính năng nâng cao (hide advanced features) hides the Typing modes and Experimental tabs if you don't need them.

Other

• Menu bar icon (Thử nghiệm tab): Vᴛ, ★ or 🇻🇳 — takes effect after a Mac restart.
• Updates: the Check for updates button, or “check weekly and notify me”.
• Debug log (Thử nghiệm tab) records events only, never the text you type; copy it and paste into a bug report.
• Gỡ cài đặt VietTelex… (uninstall) in the Giới thiệu tab removes the app, settings and shortcuts. Installed with Homebrew: brew uninstall --cask viettelex.

Switching Vietnamese/English

• Kiểu gõ tab → Phím chuyển Việt/Anh (switch hotkey): CtrlShift (UniKey style, default — press and release), AltZ, WinSpace (switches the Windows input method, VietTelex ↔ ENG) or Off.
• With CtrlShift / AltZ, VietTelex remembers Vietnamese/English per app.
• With WinSpace, per-app memory depends on Windows' own option “Let me use a different input method for each app window” — VietTelex settings show its state and offer a button to turn it on.

No underline, types everywhere

• By default VietTelex edits text in place — the word being typed is not underlined.
• Terminals (Command Prompt, PowerShell, Windows Terminal, PuTTY…) and Qt/Java/Adobe apps (Telegram, JetBrains…) are typed directly, UniKey style, while VietTelex is running.
• Password, PIN, number, phone and email fields get the raw keys, no tones.
• Ứng dụng (Apps) tab — change only when an app types wrong: enter the executable (e.g. notepad.exe) and pick Mặc định (default, in-place), Composition, Trực tiếp (direct, no underline, UniKey style), Dự phòng (fallback keyboard hook) or Luôn tiếng Anh (always English). “Dự phòng” needs VietTelex running.

Text tools

• Select text in any app, then right-click the VietTelex tray icon → Text tools: Add tones to selection (toi di hoc → tôi đi học), UPPERCASE, lowercase, Title Case, Sentence case, Remove tones. Needs Show icon in the notification area; hide the submenu with Spelling tab → Show text tools in the menu.
• Add-tones hotkey (Spelling tab, off by default): CtrlAltT, CtrlShiftT or WinAltT — adds tones to the selected text in any app, even while another input method is active.
• VietTelex reads and replaces the selection directly through the input method where the app supports it; elsewhere (older Qt/Java apps, or another keyboard active) it copies the selection and pastes the result — your clipboard is restored. Never in password fields, terminals, remote-desktop apps or apps running as administrator.

Icons, updates, other

• Keyboard icon (taskbar and the WinSpace list): Vᴛ, Star, Vietnam flag, Logo or “VI” text — changing it needs administrator rights.
• Notification-area (tray) icon (off by default): shows the current app's Vietnamese/English state (dimmed = English).
• Ngôn ngữ / Language of the settings window and tray menu: Tiếng Việt (the default, whatever the Windows display language) or English — applies immediately.
• Updates: click Check now, or turn on the automatic check (once a day). A downloaded installer is only run if it's validly signed.
• Debug log: records events to %LOCALAPPDATA%\VietTelex\debug.log, never what you type.
• Uninstall… in VietTelex settings, or Windows Settings → Apps.

Switching Vietnamese/English

• Default CtrlSpace; change it in the Tuỳ chỉnh tab → Phím chuyển Việt/Anh (needs at least one of Ctrl/Alt/Shift/Super; SuperSpace is reserved by GNOME; Backspace = no hotkey).
• Remember Vietnamese/English per app and new apps start in Vietnamese (both on by default); Quên tất cả forgets the remembered states. Ubuntu 22.04 with IBus doesn't report which app is typing, so the state is shared by all apps (except on GNOME Wayland).

How the word being typed is shown

• Cách hiện từ đang gõ: preedit (default, works in every app) or surrounding (edit in place), which falls back to preedit in apps that don't support it.
• Underline the word being typed is off by default. Chrome/Electron and Wayland apps on GNOME always draw their own underline — it can't be turned off.
• Terminals: type directly, fix tones with Backspace (on by default) in GTK3/Qt terminals; other terminals use preedit.
• Bảng cơ chế gõ tab: force a mode per app — Auto, preedit, surrounding, direct (Backspace) or Vietnamese off. YAML import/export.
• Remote desktop, virtual machine and Wine apps have Vietnamese off by default (type on the remote side); add the app to the table to type Vietnamese there.

Text tools

• Select text in any app, then open the input-method menu (the VietTelex tray / top-bar icon) → Tools… (Công cụ…) — add tones to the selection (toi di hoc → tôi đi học), UPPERCASE, lowercase, Title Case, Sentence case, remove tones. Same as on macOS.
• Turn it on or off in Options (Tuỳ chỉnh) → Show text tools in the menu (on by default); the Add tones hotkey is off by default — pick a combination with Ctrl/Alt/Super.
• Needs the viettelex-text-tools package (apt installs it along). In apps that don't report the text around the cursor, VietTelex reads the highlighted text (PRIMARY selection); with IBus that needs wl-clipboard or xclip already installed. The clipboard is never touched. Disabled in password fields and terminals.

Language & icon

• Options (Tuỳ chỉnh) → Ngôn ngữ / Language: Vietnamese (the default, even on an English system) or English — applies at once to the settings app and the input-method menu.
• The tray icon matches the macOS menu bar: Vᴛ while typing Vietnamese, E after switching to English. GNOME shows the text VT / E.

Compatibility & other

• The Tương thích (compatibility) tab lists only the issues that apply to your machine, each with a copy-the-fix button — e.g. Chrome/Electron on Wayland need --enable-wayland-ime. Full list: linux/README.
• A sudo password prompt in a terminal can't be detected — switch to English before typing the password.
• Settings live in ~/.config/viettelex/config.toml and shortcuts.yml.
• Updates: sudo apt upgrade (APT repository), or the Check for updates button in the Giới thiệu tab.