Setting Up a Spell Checker for VS Code

A guide to setting up and using a (multilingual) spell checker for VS Code to detect typos in code or documentation at an early stage.

Wouldn’t it be nice if we didn’t have typos in error messages, log entries, public API names, or ideally throughout the entire code? Anyone who has been programming for a while knows that these things happen repeatedly. Since an outsider’s motivation to report such a typo is very low, these often remain in the codebase for years. Even though a single typo is not a big deal by itself, in large quantities, it can somewhat lower the perceived quality of the software in the eyes of users. To counteract this, by the end of this article, we will be able to install and configure a spell checker in Visual Studio Code. We will also be able to set up a multilingual configuration. Additionally, we will know how to use the spell checker not only to detect errors but also to add unknown words to a project-specific dictionary.

Designed by Freepik

Installation of the CSpell Extension

First, we need to install the Code Spell Checker extension. This extension includes the CSpell library for spell checking, support for common programming languages, and the English dictionary. If you want to check for spelling errors in languages other than English, an additional extension must be installed for each language. For example, for the German language, the German - Code Spell Checker must be installed.

Creation of a Basic Configuration and a Custom Dictionary for VS Code Spell Checker

Usually, no repository comes without project- or domain-specific words, which CSpell typically does not recognize. To prevent such words from being displayed as errors, we need to teach them to CSpell. This is done using a custom dictionary. Here, we can add words that are unknown to CSpell as needed, so they are no longer marked as errors.

For CSpell to be able to use a custom dictionary, a configuration must first be created. CSpell provides various options for this. A good approach is to create a JSON configuration file .vscode\cspell.json within our repository. Alternatively, we can also create the cspell.json file at the top level. This way, we can use the configuration in IntelliJ with an additional plugin. If this is not required, it would make more sense to choose the first option. This makes the top level a little clearer.

Our basic configuration thus looks as follows:

{
  "version": "0.2",
  "language": "en",
  "dictionaries": ["Custom Words"],
  "dictionaryDefinitions": [
      {
          "name": "Custom Words",
          "path": "./custom-words.txt",
          "addWords": true
      }
  ]
}

With "language": "en", we specify that we want to use the English dictionary. Additionally, we define our own dictionary named "Custom Words". This should be stored separately in the file ./custom-words.txt. Although we could add the words here inline instead of in a dictionary file, it would quickly make the configuration confusing.

Multilingual Configuration

It is common to use additional languages besides English. This can occur either in the source code itself or in the non-English documentation. The quickest but also the least accurate way is to specify two or more languages in the language property. For example, "language": "en,de" specifies both the English and German dictionaries simultaneously. With such a configuration, none of the words in the following sentence will be marked as an error: "The Dokument could not be saved." This hinders an effective spell check in VS Code, which is why I recommend a different approach.

It would therefore make sense to specify only a single language globally and to specify exceptions with the overrides property. For this, we can override the language and dictionaries properties for each glob pattern. It is advisable to maintain a separate dictionary for each language. This allows us to assign the required language and the corresponding custom dictionary to each file individually.

Our example configuration now looks like this:

{
  "version": "0.2",
  "language": "en",
  "dictionaries": ["Custom Words (English)"],
  "dictionaryDefinitions": [
      {
          "name": "Custom Words (English)",
          "path": "./custom-words.en.txt",
          "addWords": true
      },
      {
          "name": "Custom Words (German)",
          "path": "./custom-words.de.txt",
          "addWords": true
      }
  ],
  "overrides": [
      {
          "filename": "**_de.adoc",
          "language": "de-de",
          "dictionaries": ["Custom Words (German)"]
      }
  ]
}

Here we create two dictionaries: "Custom Words (English)" and "Custom Words (German)." The first dictionary is used globally, and the second one is used for our override of files with the glob pattern **_de.adoc.

Using CSpell for Spell Checking in VS Code

Adding unknown words to the previously configured dictionary is quickest when we right-click on the unknown word and select "Spelling > Add Words to Dictionary" from the context menu. If multiple dictionaries are configured for the file being checked, a dictionary selection will be offered. After that, the word is added directly to the dedicated dictionary, and a corresponding dictionary file is created if necessary. The dictionary file is created at the path specified in dictionaryDefinitions. Normally, the word is no longer marked as unknown immediately afterward. The only exception is when a dictionary file has not yet been created, and adding a word causes the dictionary to be created. The newly created dictionary is not immediately recognized. This only applies to files opened after the dictionary is created. However, we can close the file and reopen it. The spell checker is then available with the new dictionary.

If we want suggestions to correct a word marked as unknown, we can get them by right-clicking on the word and selecting the menu entry "Spelling Suggestions...".

However, we must remember that this VS Code extension only performs spell checking and does not check grammar. So, sentences in Yoda style will not be flagged.

Forbid Words

Sometimes there is a desire to display correctly spelled words as errors. In most cases, these are offensive, politically incorrect, stylistically inappropriate, or filler words. A list of such words is specified in the flagWords property. If we unknowingly use a word from this list, it will be marked as an error.

{
  // ...
  "flagWords": [
    "foo",
    "bar",
    "baz"
  ]
}

Checking Configuration into Version Control

With an existing CSpell configuration, we can start adding unknown words step by step into one or more custom dictionaries. Once we have added a first set of words, it would be advisable to make the configuration and dictionaries available to colleagues by committing the created files. Additionally, it would also make sense to include the VS Code extensions installed in the first step in the .vscode\extensions.json file. This allows VS Code to suggest the appropriate extensions for installation to colleagues.

In our example, this file looks as follows:

{
  "recommendations": [
    "streetsidesoftware.code-spell-checker",
    "streetsidesoftware.code-spell-checker-german"
  ]
}

Before we can commit, we may need to adjust the .gitignore file, as the entire .vscode folder is often ignored. If we want to keep this strict restriction, we can still create an exception for the CSpell configuration. We can achieve this as follows:

.vscode/**
!.vscode/cspell.json
!.vscode/custom-words.de.txt
!.vscode/custom-words.en.txt
!.vscode/extensions.json

The Next Step

If you follow all these steps, you can set up a spell checker for VS Code. Start with one repository and gradually expand it to all "your" repositories.