AVIM for Firefox

Version 20080728.450 (Saturday, March 5th, 2011) by Minh Nguyễn

AVIM is a extension for Firefox and similar applications that provides an input method editor for Vietnamese, based on Hiếu Đặng’s embeddable script of the same name. Hiếu was the original developer of this extension; Minh Nguyễn is currently the lead developer.


The AVIM extension brings you modern Vietnamese typing with one of the fastest, most full-featured Vietnamese IMEs around:

The extension comes with a complete user interface, giving you much more control over your typing than webpage-based IMEs:

Unlike other IME extensions for Firefox, AVIM works everywhere:

AVIM goes through great lengths to bring you an experience without surprises:

Compared to Mudim, CHIM, and Vietnamese Portable, AVIM is by far the most powerful Vietnamese typing tool you can download.


System requirements

The AVIM extension can be used with any of the following applications:

You’ll also need a compatible keyboard. The included input methods assume a standard U.S. English keyboard, but any keyboard that includes the required keys will suffice. The specific keys required depend on which input method you end up using, but all the input methods require the alphabetic keys (AZ), and the extension’s keyboard shortcuts also require the colon (:) and semicolon (;).

The VNI input method additionally requires the numeric keys (09), and the VIQR input method requires the following keys: left parenthesis ((), plus (+), backtick (`), apostrophe ('), question mark (?), tilde (~), period (.), backslash (\), and hyphen (-). The VIQR* variant substitutes the asterisk (*) for plus (+).

If you want to type in Vietnamese inside Silverlight textboxes, you’ll need to install the Microsoft Silverlight plugin, version 2.0 or above.

Finally, to properly display the accented text, you’ll need fonts capable of displaying the various Vietnamese characters. Most modern operating systems now come with Vietnamese font support.


(XPInstall package, 60.3 kB)

If you’re planning to use AVIM in Firefox, left-click on the link above. You’ll see a popup or banner indicating that Firefox has blocked the installation. Click Allow, then click Install Now in the dialog box that appears. Restart Firefox.

If you’re downloading AVIM for another application, such as Thunderbird, right-click on the link above and select Save Link As. After saving the installer, open the destination application’s Add-ons window (usually by going to Tools ▸ Add-ons). Drag the installer into that window, click Install Now in the dialog box that appears, and restart the application.

The extension installer is also available at the official Firefox Add-ons website.


Typing in Vietnamese

Once you install the extension and restart Firefox, the Mixed input method is automatically enabled. To switch to a different input method, go to Edit ▸ Vietnamese Input or click on the panel labeled “Mixed” on the Add-on Bar. You can also use Ctrl+: and Ctrl+; (: and ; on the Mac) to cycle back and forth between the input methods. The input methods use the following key mappings:

Input methods in AVIM
MarkExampleKeys pressed
Mixed¹ Telex VNI VIQR VIQR*
Tone marks
Acute (sắc) á as or a1 as a1 a'
Grave (huyền) à af or a2 af a2 a`
Hook (hỏi) ar or a3 ar a3 a?
Tilde (ngã) ã ax or a4 ax a4 a~
Dot below (nặng) aj or a5 aj a5 a.
Other diacritical marks
Circumflex () â aa or a6 aa a6 a^
ê ee or e6 ee e6 e^
Horn (móc) ơ ow or o7 ow o7 o+ o*
Breve (trăng) ă aw or a8 aw a8 a(
Stroke (gạch ngang)² đ dd or d9 dd d9 dd
Special shortcuts
Escape a dead key a. a\.³
Remove a diacritic z or 0 z 0 -
Shift+Backspace or
  1. Configurable.
  2. Automatically transformed into the đồng sign when preceded immediately by a number (e.g., “1.000₫”).
  3. To enter an actual backslash, use two backslashes (\\).

As an example, here are the opening lines of the Vietnamese epic poem Truyện Kiều:

Trăm năm trong cõi người ta,
Chữ tài chữ mệnh khéo là ghét nhau
Trải qua một cuộc bể dâu,
Những điều trông thấy mà đau đớn lòng.
Lạ gì bỉ sắc tư phong
Trời xanh quen thói má hồng đánh ghen.

And here are ways to type them in using the provided input methods (which can vary, since AVIM is so flexible with dead keys):

Trawm nawm trong coxi nguwowfi ta,
Chuux tafi chuwx meejnh kheso laf ghest nhau
Trari qua moojt cuoojc beer daau,
Nhuwxng ddieefu troong thaasy maaf ddau ddowsn lofng.
Laj gif bir sawsc tuw phong
Trowfi xanh quen thosi mas hoofng ddasnh ghen.
Tra8m na8m trong co4i ngu7o72i ta,
Chu74 ta2i chu72 me65nh khe1o la2 ghe1t nhau
Tra3i qua mo65t cuo65c be63 da6u,
Nhu74ng d9ie62u tro6ng tha61y ma2 d9au d9o71n lo2ng.
La5 gi2 bi3 sa81c tu7 phong
Tro71i xanh quen tho1i ma1 ho62ng d9a1nh ghen.
Tra(m na(m trong co~i ngu+o+`i ta,
Chu+~ ta`i chu+~ me^.nh khe'o la` ghe't nhau
Tra?i qua mo^.t cuo^.c be^? da^u,
Nhu+~ng ddie^`u tro^ng tha^'y ma` ddau ddo+'n lo`ng\.
La. gi` bi? sa('c tu+ phong
Tro+`i xanh quen tho'i ma' ho^`ng dda'nh ghen\.
Tra(m na(m trong co~i ngu*o*`i ta,
Chu*~ ta`i chu*~ me^.nh khe'o la` ghe't nhau
Tra?i qua mo^.t cuo^.c be^? da^u,
Nhu*~ng ddie^`u tro^ng tha^'y ma` ddau ddo*'n lo`ng\.
La. gi` bi? sa('c tu* phong
Tro*`i xanh quen tho'i ma' ho^`ng dda'nh ghen\.

Try out typing with AVIM at the test page.

Customizing AVIM

By default, the Mixed input method accepts both the Telex and VNI input methods. You can change this behavior, as well as several other options, using AVIM’s preferences dialog box.

The available options are:

Enable AVIM for Vietnamese input
If checked, AVIM is enabled. Otherwise, it’s disabled, so that typing proceeds as if the extension has not been installed. By default, it’s checked (enabled). This option is equivalent to the extensions.avim.enabled preference.
This button opens the Blacklist dialog, which contains a case-insensitive list of field IDs. Textboxes with these IDs are ignored by AVIM. By default, the list consists of the following IDs:
  • colorzilla-textbox-hex – hexadecimal color textbox, ColorZilla extension
  • email and e-mail
    E-mail addresses rarely contain non-ASCII characters
  • TextboxEval – the Code bar, Error Console
  • tx_tagName – Tag Name box, Insert Node dialog, DOM Inspector
    Tag names very rarely contain non-ASCII characters.
Here are some commonly-used IDs in Firefox’s user interface:
  • urlbar – Location Bar
    Ignoring the Location Bar is not recommended, because AVIM is useful when entering URLs of Vietnamese Wikipedia articles, for instance. However, you should ignore it if you’ve enabled the network.IDN_show_punycode option in about:config.
  • searchbar – Web Search Bar
  • FindToolbar – Find in Page Bar
And in Thunderbird:
  • ColorInput – custom color textbox, Text Color and Block Background Color dialogs, Compose window
    If you use Telex, you may want to prevent yourself from accidentally entering diacritics instead of a hexadecimal code (for example, #èfe instead of #efefef).
This option is equivalent to the extensions.avim.ignoredFieldIds preference.
Input method
Selects the input method that is applied to your keyboard input. By default, it’s set to Mixed. This option is equivalent to the extensions.avim.method preference, which accepts the following values:
  1. Mixed
  2. Telex
  3. VNI
  4. VIQR
  5. VIQR*
When the Mixed input method is selected, the Customize button is enabled. A separate dialog appears when you click the button. If any of the options in this dialog is checked, that input method’s keystrokes are accepted by the Mixed input method. By default, Telex and VNI contribute to the Mixed input method. These options are equivalent to the preferences beginning with extensions.avim.auto.
When a word breaks Vietnamese spelling rules…
If “Insert characters literally” is selected, AVIM works as a spell checker of sorts. Consider a word that doesn’t conform to Vietnamese spelling rules – which typically means it’s a foreign word or name. If you have chosen the Telex input method, as normally comes out as á, but if this option is checked and you type in Washington, you’ll get Washington; if “Apply diacritics to the word anyways” is selected, you’ll get Wáhington. By default, characters are inserted literally. This option is equivalent to the extensions.avim.ignoreMalformed preference.
Except after informal spelling patterns
If checked, AVIM allows you to place accent marks on words that start with dz (equivalent to d) or f (equivalent to ph), even when spelling rules are being enforced. Such spellings aren’t acceptable in formal writing but are common in online forums. This option also allows the abbreviation “Ng̃” for “Nguyễn”. By default, it’s unchecked (not allowed). It’s equivalent to the extensions.avim.informal preference.
When a word ends in two vowels, apply diacritics to…
If “The first vowel” is selected, AVIM ensures that you place tone marks on diphthongs the traditional way, so that both xo'a and xoa' produce xóa (using the VIQR input method). If “The second vowel” is selected, AVIM uses the newer style, so that both produce xoá. By default, the tone mark would be placed on the first vowel. This option is equivalent to the extensions.avim.oldAccents preference.
Turn off input method editors embedded in Web pages
If checked, the script monitor is enabled. As soon as you type into a webpage, the extension automatically disables any IME scripts on that page that could interfere with AVIM. By default, this option is checked, so the AVIM/HIM, Google Virtual Keyboard, Mudim, MViet, VietTyping, and VietUni scripts are disabled. This option is equivalent to the extensions.avim.scriptMonitor.enabled preference.
This button opens a separate dialog that allows you to choose which scripts to disable automatically. The script monitor is capable of disabling the following scripts: AVIM/HIM, CHIM, Google Virtual Keyboard, Mudim, MViet, VietIMEW, VietTyping, VietUni, and Vinova. They correspond to the preferences beginning with extensions.avim.scriptMonitor.
Ignore password boxes
If left unchecked, AVIM allows you to add diacritics to passwords, both on webpages and in the application’s user interface. By default, it’s checked (unaccented passwords). This option is equivalent to the extensions.avim.passwords preference. Use caution when using accented passwords on a website: the website may not handle Unicode passwords properly; additionally, you might not be able to enter your password correctly when you use a different computer.
Show in Add-on Bar
If checked, the Add-on Bar button is displayed; otherwise, it’s hidden. By default, it’s checked (displayed). This option is equivalent to the extensions.avim.statusBarPanel preference.

Using AVIM in Vietnamese

By default, AVIM’s interface uses the same language that Firefox does on your system. Firefox now comes in Vietnamese, but if you prefer to use just your extensions in Vietnamese:

  1. Using Firefox’s Location Bar, navigate to about:config. (Or in Thunderbird, go to Tools ▸ Options, switch to the Advanced tab, and press the Config Editor button.)
  2. Click the “I’ll be careful, I promise!” button to continue. (If you follow these steps, everything should be fine.)
  3. Type general.useragent.locale into the Filter bar and wait a second.
  4. Double-click on the preference labeled general.useragent.locale.
  5. Type vi (meaning Vietnamese) into the dialog box that appears and press OK.
  6. Restart Firefox.

To undo the locale change, follow the above instructions, but instead of double-clicking on the preference, right-click on it and select Reset. Then restart Firefox.

Thanks to Trần Xuân Huy for the tip.

Known issues

What’s new

Version 20080728.450 (Saturday, March 5th, 2011)

Older releases…

How to help


This extension is powered by Hiếu Đặng’s AVIM script, which is available under the following permissive license:

AVIM JavaScript Vietnamese Input Method Source File

Copyright © 2004–2008 Hieu Tran Dang <lt2hieu2004 (at) users (dot) sf (dot) net> Website: http://rhos.sourceforge.net/

You are allowed to use this software in any way you want providing:

  1. You must retain this copyright notice at all time
  2. You must not claim that you or any other third party is the author of this software in any way.

The script file has been modified pursuant to this license and with Hiếu’s written permission. The included image files are in the public domain. All other files distributed with this extension are available under the MIT license:

Copyright © 2007–2011 Minh Nguyen.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

The Software is provided “AS IS”, without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the Software.

In short, do pretty much whatever you want with this software, as long as you keep the copyright notices included with AVIM intact and don’t sue Minh or Hiếu if anything goes wrong.

Building it yourself

If you’d like to keep up with the latest development code, you can use the following command (which requires Git) in a command line window, to check out the extension’s current source code:

git clone https://github.com/1ec5/avim.git

To package the code as an extension yourself, you can use the included build script, which requires Python 2.5–2.7. In a command line window, navigate to the avim/ directory and execute the following commands:

pip install -r requirements.txt
python build.py

Two installable archives, avim.xpi and avim-version.xpi, should now reside in that directory.

Build options

To streamline the release process, the build script supports several options:

Produce an unminified build for the Firefox Add-ons site. The package will be significantly larger.
Produce a BabelZilla-compatible build, to aid in localizing the extension. <em:localized> tags in the extension’s install manifest are removed, and included localizations are renamed according to BabelZilla’s predefined locale codes.
Produce a testing build. The test suite is included, to aid in finding regressions.
Print this help message to the command line.
Produce a build compatible with the Songbird Add-ons website. The installer package will be significantly larger, because optional metadata is included with each file in the package.
--use-name name
Override the package name. The default is avim.
--use-version version
Override the version string. The default is based on the REVISION constant in config_build.py.
Print the build script’s version to the command line.

Using the test suite

When you build a non-release (debug or localization) version of the extension, it includes an automated test suite. Although it’s still quite rudimentary, the test suite makes it quite easy to spot regressions in AVIM’s core functions.

To use the test suite:

  1. Install the debug build into a supported application.
  2. Open the application’s Add-ons Manager (Tools ▸ Add-ons) and select AVIM from the list of extensions.
  3. Click the Preferences button to open AVIM’s preferences panel and click the Open Test Suite button.
  4. Click the Browse button to specify the file to use as input. The plain text file should consist of a whitespace-separated list of well-formed Vietnamese words.
  5. Click the Run Tests button.

AVIM enters the specified words using the currently activated input method. As each test runs, the tester updates a multi-column list with the original word, the keystrokes used to input the word, and the resulting text. The final column indicates whether the outputted text matched the expected output. Each row is highlighted in green or red, so that it’s easy to skim the list for any regressions.

The test suite currently tests the selected input method, moving all dead keys to the end of the word. It accounts for automatic duplication of the horn diacritic (ơ and ư). Future improvements to the tester will allow you to verify that diacritical marks aren’t placed on malformed words.