AVIM for Firefox

Version 20080728.450 (Saturday, March 5^th, 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.

Features

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

AVIM supports four standard input methods (Telex, VNI, and two varieties of VIQR), as well as a default “Mixed” input method, a combination of Telex and VNI.
Unlike ordinary keyboard layouts, AVIM allows you to enter a diacritical mark anywhere after the letter it belongs to, and diacritical marks can be entered in any order. Various auto-corrections result in well-formed Vietnamese words. So if you use the VIQR input method, ddu+o+`ng, dduo+`ng, dduo+ng`, ddu+`ong+, duon`g+d, and even dduong+'?~.` all produce đường.
AVIM doesn’t provide complete spell checking – you need Vietnamese Dictionary for that – but its rule-based spell checking helps keep your writing free of errors. When AVIM encounters a word that doesn’t follow Vietnamese spelling rules, it treats additional keys literally, so a key that would normally add a diacritical mark to the word instead produces the original character for that key. This behavior is useful when using foreign words in your Vietnamese writing.
AVIM understands both styles of placing diacritical marks – old (e.g., xóa) and new (xoá) – and auto-corrects your input to be consistent with your preference.
Input editing bugs are uncommon, because AVIM is well-tested in a wide variety of situations. It has even been tested against the entire word list of the Free Vietnamese Dictionary Project. The script version, already in development by 2005, is used on websites throughout the Internet. Each day, thousands of Firefox users use the extension.

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

A compact button on Firefox’s Add-on Bar, much like the panels along Microsoft Word’s status bar, displays the current input method. Left-clicking on the panel reveals a menu for disabling and customizing AVIM. The button can be hidden.
A similar menu under the Edit menu provides access to AVIM’s basic options even if you hide the Add-on Bar button or your entire Add-on Bar.
If you’re used to the row of radio buttons and checkboxes that most webpage-based IMEs include, the extension provides a set of toolbar buttons that you can add individually (View ▸ Toolbars ▸ Customize…). If you don’t use all five input methods, you can add just the ones you do use.
A preferences dialog box, accessible through the Add-ons window (Tools ▸ Add-ons), allows you to configure AVIM’s behavior in detail.
Several keyboard shortcuts keep you from having to reach for the mouse. AVIM can be quickly enabled or disabled by toggling the Enabled option of either menu, or by pressing Ctrl+Alt+V (⌥⌘V on the Mac). This shortcut is useful when entering foreign words or source code into a webpage.
AVIM is available in five languages – Dutch, English, German, Portuguese, Spanish, and Vietnamese – all in one small download. The extension automatically selects its interface language based on the Firefox localization that you’re using; if AVIM isn’t available in that language, it defaults to English.

Unlike other IME extensions for Firefox, AVIM works everywhere:

AVIM recognizes every textbox in every webpage you visit. (Although AVIM ignores password boxes by default.)
The extension also recognizes every textbox in Firefox itself, including those in built-in windows such as the Library (formerly known as the Bookmarks Organizer), any window opened by an extension, and any dialog box that a webpage displays using JavaScript.
AVIM fully supports any webpage written in HTML, even full-fledged Web apps like Office Web Apps.
AVIM is the only IME extension that supports the Microsoft Silverlight plugin.
The extension supports the Songbird media player and Mozilla Thunderbird, Firefox’s companion e-mail client.

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

Any change to AVIM’s configuration is immediately applied to any Firefox windows you have open, and is automatically applied to any Firefox windows you open from that point on.
AVIM’s keyboard shortcuts don’t interfere with any of Firefox’s built-in shortcuts and also don’t interfere with shortcuts used by known extensions.
Textboxes don’t scroll to the top or jump to the beginning every time you add a diacritical mark, and the caret stays in place when you undo.
The preferences dialog box detects if the Mudim extension is also installed and turned on and offers to turn it off for you, preventing conflicts between the two extensions. AVIM doesn’t actually disable Mudim, but rather sets it to its Off mode.
Similarly, a script monitor automatically disables in-page IME scripts that could interfere with AVIM.
AVIM uses a completely standard user interface, so it looks like part of Firefox, no matter which Firefox theme you use.

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

Screenshots

System requirements

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

Mozilla Firefox, version 2.0 and above
Mozilla Thunderbird, version 2.0 and above
SeaMonkey, version 1.1 and above
Firefox Mobile, version 0.7 to 4.0 beta 3
Mozilla Prism, version 0.9 and above
Flock, version 1.2 to 2.6
Songbird, version 0.2.5 and above
Postbox, version 1.0 and above
Eudora OSE, version 1.0 and above
Komodo IDE or Komodo Edit, version 4.0 and above
Spicebird, version 0.7 and above (beta)
Instantbird, version 0.1.2 and above
BlueGriffon, version 0.1 and above
Any other application based on Mozilla 1.8.1 or above.

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 (A–Z), and the extension’s keyboard shortcuts also require the colon (:) and semicolon (;).

The VNI input method additionally requires the numeric keys (0–9), 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.

Installation

avim-20080728.450.xpi

(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.

Usage

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
Mark	Example	Keys pressed
Mark	Example	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 (mũ)	â	`aa` or `a6`	`aa`	`a6`	`a^`
Circumflex (mũ)	ê	`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`	`-`
Remove a diacritic		`Shift`+`Backspace` or ⇧⌫
Configurable. Automatically transformed into the đồng sign when preceded immediately by a number (e.g., “1.000₫”). 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):

Telex: 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.
VNI: 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.
VIQR: 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\.
VIQR*: 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.

Exceptions

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:

Mixed
Telex
VNI
VIQR
VIQR*

Customize

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.

Configure

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:

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.)
Click the “I’ll be careful, I promise!” button to continue. (If you follow these steps, everything should be fine.)
Type general.useragent.locale into the Filter bar and wait a second.
Double-click on the preference labeled general.useragent.locale.
Type vi (meaning Vietnamese) into the dialog box that appears and press OK.
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

Due to technical limitations, Silverlight applets written using managed code are not supported.
AVIM registers too many undo levels (about one per letter).
In rich text editors, tone marks are lost when shifted to the last character in the word. For example, xo'a becomes “xoa”, instead of “xoá”, when the Old Accents option is disabled.
Also in rich text editors, the caret may briefly appear in the wrong position after redoing.
Neither AVIM’s Vietnamese Input menu nor its status bar panel function correctly in Songbird 1.8, though its keyboard shortcuts and preference pane continue to work fine.
AVIM breaks Ace’s undo and redo functionality.
When editing a bookmark’s tags, Firefox automatically suggests (“autofills”) tags and highlights those suggestions, interfering with AVIM.
The Vietnamese Input menu doesn’t appear in ChatZilla.
In Komodo IDE and Komodo Edit, AVIM doesn’t recognize custom dialogs created by project macros.

What’s new

Version 20080728.450 (Saturday, March 5^th, 2011)

Older releases…

How to help

AVIM makes a good effort to recognize every textbox in every webpage that Firefox loads. However, some webpages make it difficult to do so. If you encounter a publicly-accessible website that is not supported by AVIM, please let Minh know. (Note that for technical reasons it isn’t possible to support textboxes in Flash webpages or Java applets.)
If you’re proficient in Vietnamese, help Minh and Hiếu find words that AVIM doesn’t handle correctly.
If you’re proficient in a language that AVIM isn’t available in, help translate AVIM into that language. It’s not much work, and you can translate online at BabelZilla.

License

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:

You must retain this copyright notice at all time

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:

-m --amo: Produce an unminified build for the Firefox Add-ons site. The package will be significantly larger.
--babelzilla: 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.
-d --debug: Produce a testing build. The test suite is included, to aid in finding regressions.
-h --help: Print this help message to the command line.
--songbird: 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.
-v --version: 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:

Install the debug build into a supported application.
Open the application’s Add-ons Manager (Tools ▸ Add-ons) and select AVIM from the list of extensions.
Click the Preferences button to open AVIM’s preferences panel and click the Open Test Suite button.
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.
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.