Minh’s Notes

Human-readable chicken scratch

Minh Nguyễn
November 19th, 2007


Vietnamese VIQR Keyboard Layout 1.0 for Mac OS X

If you type primarily in English, you have it easy: all 26 letters are right in front of you, one keystroke away. But if, like me, you do any typing in a language like Vietnamese, you’ll sometimes find it tempting to just use a typewriter, where you don’t have to worry about font support for accent marks or application support for various flavors of Unicode, and you can usually flip the page down a notch to turn a caret into a bone fide circumflex. It’s just easier.

When I absolutely have to use a post-1980s device like the computer (what horror!), my keyboard takes a beating, especially when I edit the Vietnamese Wikipedia. Since computers these days treat accented characters like as distinct from their base letters (in this case, e), Vietnamese contains over 90 such characters, and there’s no way you’d cram that into a keyboard. So various folks have devised input methods for Vietnamese: you strike multiple keys, one letter comes out. Not the best way to avoid Carpal Tunnel Syndrome, but you just try talking to someone without any vowels. Isn’t happening, unless you’re a Klingon.


VIQR is the most inconvenient of these input methods. In order to type the word tiếng Việt (Vietnamese for “Vietnamese”), you’d enter:

tie^'ng Vie^.t

Only a habitual Perl programmer would actually enjoy using the diaspora of keys needed for VIQR, but I find it less cryptic than schemes like VNI, which uses numbers instead of arcane punctuation:

tie61ng Vie65t

Looks like the subject line of an e-mail advertisement for V-one-agra, I know. And if for nothing else, VIQR is cool because it’s got a catchy acronym (rhymes with “quicker”, ironically enough).

All that’s an inexcusably long way to introduce a little tool I’ve been cooking up: the Vietnamese VIQR Keyboard Layout 1.0 for Mac OS X. (Yep, it’s got a long name too.) After enabling this keyboard layout, you can type perfectly-accented Vietnamese into any Mac application that supports Unicode. That includes the works: TextEdit, Firefox, Word, Adium, iTunes, the Dashboard, and even Terminal.


So if you’re a Mac user, you can add VIQR support to your computer by downloading this keyboard layout:

(tarball, 12 kB)

System requirements

First of all, this keyboard layout requires Mac OS X. Any localization will do. Although I haven’t tested the keyboard layout on anything by Tiger (version 10.4), it should theoretically work as far back as Jaguar (10.2).

Windows users should try UniKey, which supports multiple input methods and is much more flexible. (For instance, it allows you to enter the diacritics after the letters.)

Apparently Leopard includes its own VIQR layout, but I haven’t gotten my hands on Leopard yet, and I desperately needed to type in VIQR. (Leopard includes several Vietnamese input methods now, all under the UniKey brand, so perhaps it has the same advanced features as the real UniKey.)

If you’re not on Leopard yet but don’t particularly care for VIQR, you might prefer one of Gero Herrmann’s Vietnamese keyboard layouts.

It turns out the “Vietnamese Unikey” input method included in Leopard is completely broken. However, as Kỳ Anh reports, that input method has finally been fixed in Mac OS X 10.6 (Snow Leopard). So if you’ve upgraded to Snow Leopard, I highly recommend using the built-in input method rather than my keyboard layout. Otherwise, if you haven’t upgraded but still find keyboard layouts too awkward, consider installing AVIM for Firefox.

Installation and setup

  1. Download the tarball and unzip it.
  2. The resulting folder contains five files, but of those, you only need VietnameseVIQR.keylayout and VietnameseVIQR.icns. The latter is the keyboard layout’s icon. Copy both to one of these locations on your computer (both locations are accessible from the Finder):

    Name of User ▸ Library ▸ Keyboard Layouts ▸
    Placing the files here makes the keyboard layout accessible to you and you alone.
    Name of Hard Drive ▸ Library ▸ Keyboard Layouts ▸
    Network ▸ Library ▸ Keyboard Layouts ▸
    On Mac OS X Server, placing them here makes the keyboard layout accessible to every user on your network.
  3. Log out and back in again. (No way around this step, unfortunately for anyone who has to write and debug a keyboard layout.)
  4. In System Preferences, open the International panel (under the Personal section) and switch to the Input Menu tab. “Vietnamese-VIQR” should now appear in the list; turn it on. Also, make sure that the “Show input menu in menu bar” option is checked, so that you can switch between the different keyboard layouts you’ve enabled.

  5. There should be a new icon for the Input Menu on the right side of your menu bar. (If you don’t like its placement, hold down and drag it around.)

A geopolitical note

For consistency with the built-in Vietnamese keyboard layout, the VIQR layout’s icon bears the current flag of Vietnam. However, I know that many overseas Vietnamese would be uncomfortable displaying this flag on their menu bar all day, so I included two alternatives: VietnameseVIQR-South.icns, which bears the historical flag of South Vietnam, and VietnameseVIQR-Map.icns, which features Vietnam’s silhouette. If you prefer, you can replace VietnameseVIQR.icns with either of these icons.


The Wikipedia article on VIQR does a good job of explaining how to use this input method. Here’s a quick demonstration:

You’ll need the Flash Player to watch the clip.

(QuickTime movie, 1.5 MB)

Yes, that was too fast for an instructional video. No, that wasn’t intended to be an instructional video.

Known issues

In some programs, buttons in dialogs don’t respond to keyboard shortcuts. For instance, in TextEdit, D doesn’t trigger the “Don’t Save” button when closing an unsaved document.


The keyboard layout is licensed under the standard MIT License. In essence, go all out. Just don’t blame me if no one can understand you any longer, because circumflexes and tildes suddenly litter your handwritten English notes, because you love VIQR so much.


The keyboard layout was made with the help of Ukelele and KeyLayoutMaker, both freeware tools by SIL International. However, I had to do a lot of hand-tweaking to get it to a usable state.

It conforms to the VIQR standard, though it handles dead keys differently than most JavaScript-based input methods for Vietnamese, due to the limitations in Apple’s XML Keyboard Definition format. In addition to the standard characters, the đồng sign () is accessible via 4 (replacing the cent sign from the standard U.S. English keyboard layout).


TrackBack URL: <http://panel.1ec5.org/mt/mt-ping.fcgi/807>

  1. Introducing an extension for Firefox and its companion e-mail program, Thunderbird, that checks your Vietnamese spelling as you type.

  2. Back in November, I released a keyboard layout for Vietnamese, to improve the Vietnamese typing situation on the Mac. Now I’m showing non-Mac users some input method love too.

  3. Updated: A keyboard layout for typing fully-accented Vietnamese into any Mac application: you strike multiple keys, one letter comes out. Not the best way to avoid Carpal Tunnel Syndrome, but you just try talking to someone without any...

  4. Hundreds of words of pointless drivel, seasoned generously with outbound hyperlinks. Thank the spambots.


  1. Well M.X. Nguyễn, I finally took it upon myself to get my own hosting. I may put up a blog soon but for now it's just a placeholder with a cute frog.

    You should really look into getting a domain name-- I'm sure $7 a year wouldn't kill you to get minhsnotes.com or something. That is, unless you have a reasoning otherwise.

  2. Whoops. I meant, get an extra domain besides 1ec5.org.

    1. I actually intend for my site to center around the 1ec5 name someday in the future. (After I redesign the redesign I’m working on right now.) It’s hard to come up with something more obscure than “1ec5”, anyhow.

  3. I used to write with VIQR exclusively, but have now converted to Telex. It was sort of weird at first but once you get used to it, it's much easier. VIQR requires too many keypresses, and requires you to constantly extend your fingers to reach the numbers row. Now that Telex is so ingrained in me, I have trouble typing with VIQR where Telex is unavailable (**cough**Pidgin**cough**).

    One of my pet peeves is using flags as symbols for languages or people. This is idiotic and sometimes insulting. Why use something that is not familiar to all speakers of a language or not even insulting to some of them when you can use something universally understood like the language name itself in that language. Thankfully, I never had to deal with that in the operating systems that I've used.

    1. I suppose it never bothered me to have my fingers reach for the keyboard’s extremities so often, since programming (**cough** regular expressions **cough**) makes me do that anyways.

      The only reason I used a flag to represent this keyboard layout by default was that the existing Vietnamese keyboard layout (Telex) already uses the Vietnamese flag. Otherwise, I would’ve just made the silhouette of Vietnam the default. Not a perfect solution for every language, but probably good enough for Vietnamese, which is identified with the country most of the time anyways.

      I’m pleased that Leopard, the latest version of Mac OS X, represents the Vietnamese input methods with what appears to be the Temple of Literature.

  4. Hi Minh,

    I followed all the steps to add VIQR to my menu bar on a mac computer and after selecting the Vietnamese-VIQR icon in the Input menu I didn't see the options for "Show Character Palette", "Show IPA palette" or "Show Keyboard Viewer".

    1. Sorry, those menu items aren’t part of the VIQR keyboard layout; only the Vietnamese-VIQR item is. You can turn on the Character Palette and Keyboard Viewer using the Input Menu tab of the International preference pane. (They’re at the top of the list.) You can download the IPA Palette separately, but that’s for writing in the International Phonetic Alphabet, which I do on occasion. Sorry again for the confusion.

  5. ThanhVu Nguyen


    Minh, thanks for the article and the program.

  6. Hi--

    Sorry for a random question, but does movable type support VN fonts and script? have you had any issues with this?

    J. Sager


    1. By default, Movable Type does not use Vietnamese-specific encodings like VISCII, VNI, or VPS, if that’s what you mean. (These encodings all have “Vietnamese fonts” that you have to download.) Instead, like most web applications these days, MT uses Unicode.

      Unicode fonts that support Vietnamese include Times New Roman, Arial, Helvetica, Tahoma, etc., so things should work right out of the box if you use ordinary fonts. However, if you’d like to use legacy Vietnamese encodings, you can specify it in MT’s configuration file (mt-config.cgi), using something like this:

      PublishCharset VISCII

      This is a system-wide setting, so it affects every blog using that installation of MT. Some versions of MT also have a setting right inside the user interface that apply only to a specific blog. This configuration setting changes the encoding used when publishing entries, but MT’s interface will remain in Unicode, so it’s a bit awkward to compose entries. (Depending on your browser, you’d need to set the encoding using the View menu each time you edit.)

      The main issue with using a legacy Vietnamese encoding is browser support. Firefox is rather nice in this regard: it supports TCVN, VISCII, VPS, and Windows-1258, but not VNI. As far as I know, Internet Explorer supports only Windows-1258, but I’m not certain about that.

      Your best bet is actually to use Unicode, which doesn’t require specialized Vietnamese fonts and is supported by most software applications these days. Hope this helps.

  7. Cam on nhieu qua, Minh!

  8. ThanhVu nguyen


    Minh, not sure if this is normal behavior, it often happens (e.g., in gmail) that after I type something, go back and edit the word, after done editing I have to use the arrow key to move to a different word for my modification to stay, otherwise it is auto delete (i.e., the changes not committed).

    1. When you go back and edit the word, was the last key you pressed a vowel or D? Unfortunately, I believe this is normal behavior in that case. In Cocoa-based applications like Safari and TextEdit, that vowel or D will be highlighted in yellow until you press something else, like the spacebar, an arrow key, , or one of the keys that produces an accent mark. In Firefox (and maybe other applications), the vowel is given a thick underline instead. The highlighting or underlining means the letter hasn’t been completed yet.

      This seems to be the way Mac OS X’s keyboard layout feature works. The highlighted or underlined character is called a dead key. Most keyboard layouts require you to press a dead key before the vowel, so if the vowel is never entered, Mac OS assumes you changed your mind and don’t want that accented letter after all, and gets rid of the dead key character. Because Vietnamese input methods are the other way around – vowels before accent marks – the dead key character is the vowel, and that means the vowel is sometimes removed. I don’t know if this is how the UniKey input managers in Leopard function.

      If that’s not the problem you’re seeing, let me know.

  9. ThanhVu Nguyen


    Minh yes I believe that's what I have been experiencing in Tiger. Just a minor issue nonetheless.

  10. ThanhVu Nguyen


    Minh I saw on this page that you also edit Vietnamese entries on wikipedia, I'd like to contribute but not very familiar with the editing/management parts. In particular I want to create a page containing lyrics (in utf-8) of famous songs from renown Viet composers such as Van Cao, or poems from Ho Xuan Huong, Ba Huyen Thanh Quan etc.

    Anyway let me know if you're interested. My email is nguyenthanhvuh@gmail.com .

  11. I used to use VPS keypad from OS X classic version and it worked beautifully. Since I updated my system to Tiger, I can't seem to use the fonts anymore. Although, I did install the VIQR key and it worked fine on TextEdit and online, but because i do design job and it requires me to use different program like Illustrator or photoshop and can't seems to work on them. Do you have any suggestion or different program for them? Looking forward to hear from you. Cheers, Amy

    1. Sorry, I’m not that familiar with either software package, although I know Photoshop doesn’t use the native Mac facilities for displaying text – as far as I know, all text is custom-drawn, so I’m not confident that I could make this keyboard layout work in it.

  12. ThanhVu Nguyen


    Minh, could you also provide the Vietnamese icons without the VIQR text at the bottom ? Thanks

    1. It’s already available on your system at Name of Hard Drive ▸ Library ▸ Keyboard Layouts ▸ Unicode.bundle ▸ Contents ▸ Resources ▸ Vietnamese.icns. But since that’s rather hard to find, I’ve uploaded a copy, and I’ll include that file in any later releases of this keyboard layout. As always, replace VietnameseVIQR.icns with that file, and you’re good to go.

  13. ThanhVu Nguyen


    ah I was referring to the pre75 viet icon --- do you have that cone w/out the viqr text ? Thanks

  14. Hi friend, I am lee, from vietnam, Now i had a trouble using vietkey or unicode. I can not write vietnamese word on my macbook pro. actually, I tried many time for this. I have been survey but the end I am still not use it. Please help me. Thanks ,
    I always write vni, for example, co61ng ho2a,

    please show for me thanks

    1. Hi Lee, the version of Unikey built into Mac OS X 10.5 (Leopard) lets you type using VNI. You can follow steps 4 and 5 above. In the list of input methods, enable “Vietnamese Unikey” and, underneath it, “VNI”.

      If that doesn’t work, or if you’re using an older version of Mac OS X, you might be able to use one of Gero Herrmann’s keyboard layouts.

  15. Hi Minh. Thank you for your posting of the VIQR Keyboard definition for OSX. I had a new MacBook running Leopard and was looking for something similar to VPSKeys but they only have it for Mac classic. So I googled and found that OSX does support Vietnamese fonts and keyboard. However, when I tried all keyboard & font seem to work except VIQR. That's when I saw your blog and downloaded your stuffs which work well with MSWord which is what I would need. But there is one minor thing that you should know: the South & Map icons do not seem to work and I've got a keyboard icon instead (the original icon does work and shown on the upper bar). Is there anything that you could do? Thanks.

    1. Hi Hung. You need to rename the icon file to VietnameseVIQR.icns. Mac OS X specifically looks for that file name.

    2. Hi Minh. Such a simple thing that I should have thought of. Thanks. Another problem I found yesterday when I had your keyboard driver on and had to log back in from screen saver. Leopard did not recognize my password every time I tried, and I later found by watching that the vowels (a, e, u, etc...) were not being entered as small circle. So I did try to use to back lash (\) with the hope of breaking out of the state the the driver was in, but to no avail. I did actually have to reboot the system to get back in, which would not be so good if I want to screen saver to secure my Mac Book. Is this something you can fix? Thanks Hung.

    3. Unfortunately, I don’t think I can address that issue in the keyboard layout itself. The problem is basically that the VIQR keyboard layout puts the base letters before the combining diacritics; all other Mac layouts put the diacritics first.

      However, you can enable the input menu in the login screen: in System Preferences, go to the Accounts panel and open the Login Options page. Check the “Show Input menu in login window” option. As long as you have a typical keyboard layout (like U.S. English) enabled, you can log back in.

      If you use Keychain Access’ Lock Screen feature, the login dialog to unlock the screen doesn’t have an input menu. But you can enable fast user switching in the Login Options page, which gives you a Switch User button that takes you to the normal login screen.

      I’m sorry it’s so inconvenient to use this keyboard layout anywhere other than an ordinary textbox. Please consider reporting the issue to Apple.

    4. Thank you Minh. Your pointer on Login Options and fast switching did alleviate the problem I had. I will report to Apple on their VIQR keyboard not working.

  16. Hi,
    I'm looking for the vietnamese keyboard which can work on my mac computer, and I found vietnamese VIQR. I got it and did every step you show, but it doesn't work. I don't know how to fix it. Could you please instruct me again?

    thanks a lot.

    1. First of all, what version of Mac OS X are you using? I’ve only tested this keyboard layout on 10.4 (Tiger) and 10.5 (Leopard), but I’ve heard that it should work in older versions.

      Some tips:

      • Make sure you unzip VietnameseVIQR-1.0.tar.gz.
      • Try placing VietnameseVIQR.keylayout and VietnameseVIQR.icns directly in the Your User Name ▸ Library ▸ Keyboard Layouts folder. It’s supposed to work when you put it in the other folders mentioned above, but sometimes it doesn’t work.
      • Once you enable the Vietnamese-VIQR keyboard layout in System Preferences, don’t forget to enable the Input Menu and select Vietnamese-VIQR from that menu as well.
      • If you use Leopard, don’t confuse this keyboard layout with the Vietnamese Unikey input method that comes with Leopard. It has a VIQR option that doesn’t work.

      I hope that helps. If not, do any other keyboard layouts (like the original Vietnamese keyboard layout) work for you?

  17. Trần Kỳ Anh


    Could you add the capability to allow accents that are typed in at the end of the word to still have the proper Vietnamese rendition?

    For example, the ability for "tiếng Việt" to be entered in as either "tie^'g Vie^.t" OR "tieng^' Viet^."

    This function is available in UniKey for Windows and it would be great if this could also be available for the Mac. Please let us know if this would be at all possible for you to do.

    I would also like to add myself to the list of grateful individuals for making this layout available, and I look forward to your response.

    Much appreciated,
    Trần Kỳ Anh

    1. That would be an indispensable feature, and I realize this keyboard layout is quite frustrating to use without it. Unfortunately, it would be highly impractical to create a keyboard layout with word-final accent marks, because a keyboard layout on the Mac is nothing more than an XML file that defines a finite state machine. In other words, I would have to define exactly how each accent mark would change every subset of every possible Vietnamese word. (If you’re familiar with theoretical computer science, this feature is only practical on a Turing machine. Most programming languages are Turing-complete, but the keyboard layout format is not.)

      Mac OS X does support a more advanced feature called an input method. In fact, Mac OS X 10.5 (Leopard) comes with a “Vietnamese UniKey” input method – a port of the Windows version that supports word-final accent marks. What’s frustrating is that its VIQR support is completely broken. Please consider reporting the bug to Apple. With enough attention, perhaps this issue will be fixed in Mac OS X 10.6 (Snow Leopard).

      In the meantime, you could download AVIM, an extension I wrote that allows you to type in Vietnamese – with word-final accent marks – in any part of Firefox or Thunderbird.

    2. Trần Kỳ Anh


      I just wanted to provide an update to you indicating that VIQR is now functional in OS X under Snow Leopard (v10.6).

      I received a reply in response to a bug report indicating that it may have been fixed in the latest version. I then tested it for myself on a MacBook Pro to verify this to Apple, and found that it is indeed functioning.

      Unfortunately, it is not without bugs – a foreign character is inserted if you use one of the 'arrow keys' while in the middle of typing a word – but it is still useable. I found that this new problem seems to exist for all of the Vietnamese Input Methods, though, not just VIQR.

      Also, since it is only available in Snow Leopard, the fix does not apply to those who use PowerPC Macs, as Snow Leopard only supports MacIntels. I am not technically versed enough to know whether whatever files that are used to implement VIQR in Snow Leopard can be isolated and just copied over to someone using Leopard.

      However, it does work (for the most part) and that is a start. I replied to Apple indicating the 'arrow key' problem and the fact that VIQR is still unusable under v10.5. Hopefully these problems will be addressed, or a workaround can be found.

      In any case, I thought you might want to be updated if you were not already aware of the situation.

      All the best,
      Kỳ Anh

    3. Thanks for the great news, Kỳ Anh! If the Vietnamese IMEs in Snow Leopard are isolated in a file separate from the other languages, I’d imagine you’d be able to move the file over to Leopard with no problem. As far as I know, Apple hasn’t made any changes to the IME APIs since Leopard.

  18. I have a problem with using unikey, Mac version. I am owning a Macbook Pro and my Mac wouldn't type the accent marks starting from 1-5, and I can't find u* and o*. It's really weird how mine does its lettering.

    1. This is off-topic, but it sounds like you’re trying to use the VNI input method (a1 for “á” etc.). Open the International pane in System Preferences, switch to the Input Menu tab, and make sure VNI is selected under Vietnamese UniKey. Then, in the input menu, make sure VNI is the current input method, rather than, say, Telex. (The VNI UniKey icon looks like the Temple of Literature with “VN” underneath.) u7o7 will produce “ươ”.

      (VNI is one of three mainstream Vietnamese input methods, along with Telex and VIQR.)

  19. Xin vui l`ong chi? c'ach cho to^i download Vpskeys 4.3 hay mo^.t program na`o dde^? gi'up cho to^i c'o the^? vie^'t tie^'ng Vie^.t c'o da^'u . Th`anh tha^.t c'am o*n . Email cu?a to^i l`a metta10cox.net. Ma'y cu?a to^i thuo^.c l.oai iMac
    Ton Tra^`n

  20. Xin vui l`ong chi? c'ach cho to^i download Vpskeys 4.3 hay mo^.t program na`o dde^? gi'up cho to^i c'o the^? vie^'t tie^'ng Vie^.t c'o da^'u . Th`anh tha^.t c'am o*n . Email cu?a to^i l`a metta10cox.net. Ma'y cu?a to^i thuo^.c l.oai iMac
    Ton Tra^`n

  21. Hi,

    I wonder if you could help me out in typing Vietnamese on a 64-bit Mac? I have tried unikey but it would only run on a 32-bit machine. Thanks a lot!

    1. Leopard and Snow Leopard both have a built-in Mac port of Unikey (“Vietnamese Unikey”) that works fine, even on 64-bit systems, with the caveat that the VIQR input method included with Leopard was completely non-functional. If you use VIQR, you’ll either have to upgrade to Snow Leopard, install the keyboard layout on this page (which is an admittedly poor experience compared to Unikey), or download the AVIM extension (if the per-application support is fine with you).

  22. Hello,
    I have a macpro. I dl the vietnamese-VIQR and completed all the steps. I even dl the IPA but I still could not type in vietnamese. When i open microsoft i had to switch back to US mode to type cuz the VIQR didn't show any. Do you know what happen? can you help me out?
    Thank you

    1. Hi Vien,

      The IPA Palette is unrelated to typing in Vietnamese on the Mac, so that’s unlikely to be the problem.

      To help you solve your problem, I need a little more information. What version of Mac OS X are you running? (I’ve tested this layout on Tiger and Leopard without seeing any problems. Although I haven’t tested it in Snow Leopard, it should be fine there too.) Also, do you have any input managers installed?

  23. Chao Anh Minh: I own a MacBookPro, version 10.6.8. I went to www.youtube.com/user/shantaclaw. I understood everything until the final instruction which allows you to type in Vietnamese. That last part I didn't understand. I am sorry to have to ask you to go to that site to see my problem. Of course you do it when you have time. I don't mind adding extra things to the wowels but my friends told me those things made them dizzy and gave them headaches. Thanks Anh Minh. If you don't have time, just ignore my problem. Wishes are going your way and your family for a very Healthy. Happy and Successful New Year. nga

Comments and Concerns

Press “Submit” to send this card to Minh. Your comment will appear on this page as soon as he approves it. No solicitation, please. Your e-mail address is never displayed on this website and will not be shared with any other entity.