Quick Start

Get started with Gõ Nhanh in under 5 minutes. Install, configure, and start typing Vietnamese on macOS.

Get up and running with Gõ Nhanh in under 5 minutes. This guide covers installation, setup, and your first typing experience.

Installation

1. Install via Homebrew (Recommended)

   The easiest way to install Gõ Nhanh is through Homebrew:

   brew install --cask gonhanh
   

   The app will automatically check for updates every 24 hours. You can also update manually:

   brew upgrade --cask gonhanh
   
2. Alternative: Manual Download

   If you prefer not to use Homebrew, download the DMG file directly:

   1. Download GoNhanh.dmg
   2. Open the .dmg file
   3. Drag the app to your Applications folder

   macOS Security Warning: If the app doesn’t open, you need to remove the quarantine attribute. Run this command in Terminal:

   xattr -cr /Applications/GoNhanh.app
   

   This is a one-time step required for apps downloaded outside the App Store.

3. Grant Accessibility Permissions

   Gõ Nhanh needs Accessibility permissions to intercept and transform your keystrokes.

   1. Open the app (it will launch automatically if installed via Homebrew)
   2. macOS will prompt you to grant permissions
   3. Click Open System Settings
   4. In Privacy & Security → Accessibility, toggle on GoNhanh
   5. Restart the app

   The onboarding wizard will guide you through these steps automatically on first launch.

First Use

Choose Your Input Method

On first launch, you’ll be prompted to choose between two input methods:

Telex (Default)

The most popular Vietnamese typing method.

• Vowels: aa → â, aw → ă, ee → ê, oo → ô, ow → ơ, uw → ư
• Tones: as → á, af → à, ar → ả, ax → ã, aj → ạ
• Special: dd → đ

VNI

Numeric-based input method.

• Vowels: a6 → â, a8 → ă, e6 → ê, o6 → ô, o7 → ơ, u7 → ư
• Tones: a1 → á, a2 → à, a3 → ả, a4 → ã, a5 → ạ
• Special: d9 → đ

You can change your input method anytime from the menu bar icon → select Telex or VNI.

Your First Typing Test

Once installed, try typing Vietnamese:

1. Open any text editor (Notes, TextEdit, browser, etc.)
2. Make sure Gõ Nhanh is enabled (menu bar icon shows VN)
3. Type using Telex: viet nam → “việt nam”
4. Type a full sentence: xin chao ban → “xin chào bạn”

Telex Examples

Gõ:  xin chao, ban khoe khong?
Ra:  xin chào, bạn khỏe không?

Gõ:  toi dang hoc tieng viet
Ra:  tôi đang học tiếng việt

Gõ:  cam on ban rat nhieu
Ra:  cảm ơn bạn rất nhiều

Switching Between Vietnamese and English

Gõ Nhanh provides multiple ways to switch between Vietnamese and English:

Toggle On/Off

Press Ctrl + Space (default) to toggle Vietnamese input on or off.

• Enabled: Menu bar shows VN (Vietnamese mode)
• Disabled: Menu bar shows EN (English mode)

You can customize this shortcut in Settings → General → Shortcut.

Auto-Restore Feature

Gõ Nhanh automatically detects common English words and restores them when you press Space:

You Type	Without Auto-Restore	With Auto-Restore
text	têt	text ✓
expect	ễpct	expect ✓
with	ưith	with ✓
user	úẻ	user ✓
perfect	pềct	perfect ✓

How it works: The engine analyzes each word after you type it. If the result contains invalid Vietnamese syllables, it automatically restores the original English input.

ESC Key Recovery

If auto-restore doesn’t catch a word, press ESC to manually restore it:

1. Type box → becomes bõ (valid Vietnamese)
2. Press ESC → restores to box

Smart Per-App Mode

Gõ Nhanh remembers your language preference for each app:

• Coding in VS Code (Vietnamese OFF) → typing stays in English
• Switch to Slack (Vietnamese ON) → typing switches to Vietnamese
• Return to VS Code → automatically switches back to English

Per-app mode is enabled by default. You can disable it in Settings → General → Remember state per app.

Next Steps

Now that you’re up and running, explore more features:

Settings

Customize tone placement, shortcuts, and advanced options

Shortcuts

Create custom abbreviations like vn → Việt Nam

Troubleshooting

Fix common issues with specific apps

Features

Learn about all available features

Need Help?

If you encounter any issues:

1. Check the Troubleshooting guide
2. Report issues on GitHub
3. Join the community on Discord