AVIM for Firefox

Version 20080728.306 (Saturday, February 14th, 2009) by Minh Nguyễn

AVIM is a change-around 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 change-around; Minh Nguyễn is currently the lead developer.


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

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

Unlike other IME change-arounds 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 change-around 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 change-around’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 (+).

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, 43.3 kB)

If you’re planning to use AVIM in Firefox, left-click on the link above. You’ll see a banner (typically yellow) 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 change-around installer is also available at the official Firefox Change-arounds website.


Typing in Vietnamese

Once you install the change-around and restart Firefox, the Auto input method is automatically enabled. To switch to a different input method, go to Edit ▸ Vietnamese Input or click on the panel labeled “Auto” on the status 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
Auto¹ 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 -
  1. Configurable.
  2. 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 Auto 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 change-around has not been installed. By default, it’s checked (enabled). This option is equivalent to the extensions.avim.enabled preference.
Input method
Selects the input method that is applied to your keyboard input. By default, it’s set to Auto. This option is equivalent to the extensions.avim.method preference, which accepts the following values:
  1. Auto
  2. Telex
  3. VNI
  4. VIQR
  5. VIQR*
Enforce Vietnamese spelling rules
If checked, 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 the option is unchecked, you’ll get Wáhington. By default, this option is checked (enforced). This option is equivalent to the extensions.avim.ignoreMalformed preference.
Allow dz and f at the beginning of a word
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. By default, this option is unchecked (not allowed). It’s equivalent to the extensions.avim.informal preference.
Place tone marks on the first vowel in a final diphthong (old-style accent marks)
If checked, 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 unchecked, AVIM uses the newer style, so that both produce xoá. By default, it’s checked (old style). This option is equivalent to the extensions.avim.oldAccents preference.
Accept keystrokes from the following input methods when Auto is selected
If any of the options under this heading is checked, that input method’s keystrokes are accepted by the Auto input method. By default, Telex and VNI contribute to the Auto input method. These options are equivalent to the preferences beginning with extensions.avim.auto.
Disable input editing scripts inside 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, MViet, VietTyping, and VietUni scripts are disabled. This option is equivalent to the extensions.avim.scriptMonitor.enabled preference. You can customize which scripts are disabled using the remaining preferences beginning with extensions.avim.scriptMonitor. The script monitor is capable of disabling the following scripts: AVIM/HIM, CHIM/Mudim, MViet, VietIMEW, VietTyping, VietUni, and Vinova.
Allow diacritics in password boxes
If checked, AVIM allows you to add diacritics to passwords, both on webpages and in the application’s user interface. By default, it’s unchecked (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 status bar
If checked, the status bar panel is displayed; otherwise, it’s hidden. By default, it’s checked (displayed). This option is equivalent to the extensions.avim.statusBarPanel preference.
Ignored Textboxes tab
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.

Using AVIM in Vietnamese

By default, AVIM’s interface uses the same language that Firefox does on your system. Vietnamese language packs are available for Firefox 2, 3.0, and 3.1 beta 2. If you prefer to use just your change-arounds 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.306 (Saturday, February 14th, 2009)

Older releases…

How to help


This change-around 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://noname00.com/hieu

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 change-around are available under the MIT license:

Copyright © 2007–2008 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 Subversion) in a command line window, to check out the change-around’s current source code:

svn co http://version.1ec5.org/avim/trunk/ avim

To package the code as an change-around yourself, you can use the included build script, which requires Python 2.5 or above. In a command line window, navigate to the avim/ directory and execute the following command:

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 Change-arounds site. The package will be significantly larger.
Produce a BabelZilla-compatible build, to aid in localizing the change-around. <em:localized> tags in the change-around’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 Subversion revision that you’ve checked out.
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 change-around, 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 change-arounds.
  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.