Managing the built-in en-US dictionary

Requesting to add new words to the en-US dictionary

If you’d like to add new words to the dictionary, you can add your request to this bug:

• Include all possible forms, e.g. plural and genitive forms for nouns, different tenses for verbs.

• Try to provide information on the terms you want to add, in particular references to external sources that confirm the usage of the term (e.g. Merriam-Webster or Oxford online dictionaries).

Adding new words to the en-US dictionary

This section describes the process for adding new words to the dictionary:

1. Get a clone of mozilla-central (see Firefox Contributors’ Quick Reference), if you don’t already have one, and make sure you can build it successfully.

2. Move in the dictionary sources directory using this command: cd extensions/spellcheck/locales/en-US/hunspell/dictionary-sources.

3. Identify the current version of SCOWL by checking the file README_en_US.txt (at the beginning of the file there is a line similar to Generated from SCOWL Version 2020.12.07, where 2020.12.07 is the SCOWL version).

4. Download the same version of the dictionary from the SCOWL homepage or SourceForce as a tarball (tag.gz) and unpack it in the working directory. Rename the resulting folder from scowl-YYYY.MM.DD to scowl.

5. There’s a special script used for editing dictionaries. The script only works if you have the environment variable EDITOR set to the executable of an editor program; if you don’t have it set, you can use EDITOR=vim sh edit-dictionary.sh to edit using vim (or you can substitute it with another editor), or you can just type sh edit-dictionary.sh if you have an EDITOR already specified.

   Copy and paste the full list of words, then save and quit the editor. It’s not necessary to put the words in alphabetical order, as it will be corrected by the script.

   Note: you might need to install aspell on your system (e.g. via brew install aspell on macOS).

6. Run the script sh make-new-dict.sh to generate a new dictionary and make sure it runs without errors. For more details on this script, see the make-new-dict.sh section.

7. Do a sanity check on the resulting dictionary file en_US-mozilla.dic. For example, make sure that the size is about the same as the original dictionary (or slightly larger).

8. If everything looks correct, use sh install-new-dict.sh to copy the generated file in the right position.

9. Build Firefox and test your updated dictionary. Once you’re satisfied, use the process described in To write a patch to create a patch.

Note that the update script will modify 2 versions of the dictionary, and both need to be committed:

• en-US.dic: the dictionary actually shipping in the build, it uses ISO-8859-1 encoding.

• utf8/en-US.dic: a version of the same dictionary with UTF-8 encoding. This is used to work around issues with Phabricator, and it allows to display actual changes in the diff.

Exclude words from suggestions

It’s possible to completely exclude words from suggested alternatives by adding an affix rule ! at the end of the definition in the .dic file. For example:

• bum would be changed to bum/! (note the additional forward slash).

• bum/MS would be changed to bum/MS!.

In order to exclude a word from suggestions, follow the instructions available in Adding new words to the en-US dictionary. Instead of running the edit-dictionary.sh script (point 5), use a text editor to edit the file en-US.dic directly, then proceed with the remaining instructions.

Upgrading dictionary to a new upstream version of SCOWL

The English dictionary available in mozilla-central is based on the SCOWL dictionary. Some scripts distributed with the SCOWL package are used to generate the files for the en-US dictionary.

The working directory for this process is extensions/spellcheck/locales/en-US/hunspell/dictionary-sources.

1. Download the latest version of the dictionary from the SCOWL homepage or SourceForce as a tarball (tag.gz) and unpack it in the working directory. Rename the resulting folder from scowl-YYYY.MM.DD to scowl.

2. Run the script sh make-new-dict.sh to generate a new dictionary and make sure it runs without errors. For more details on this script, see the make-new-dict.sh section.

3. Do a sanity check on the resulting dictionary file en_US-mozilla.dic. For example, make sure that the size is about the same as the original dictionary (or slightly larger).

4. If everything looks correct, use sh install-new-dict.sh to copy the generated file in the right position and use the process described in To write a patch to create a patch.

Info about the file structure

Info about the included scripts