Configuration

Tip

The configuration format is still evolving. Backwards compatibility is maintained where possible, but some keys may change between minor versions. Check the release notes when upgrading.

Language Check is configured via a .languagecheck.yaml file in your workspace root. YAML is preferred; .languagecheck.yml and .languagecheck.json are also supported.

Where the config is read from

Language Check reads one config per workspace, from the root of the workspace folder. It does not search up or down from the file being checked, so the closest config to a file is not necessarily the one that applies to it.

  • Only the root counts. A .languagecheck.yaml in a subfolder is not read, not even for the files inside that subfolder, and nothing from it is merged into the root config. To treat part of a project differently, use exclude, the per-language settings and rules in the root config.

  • One file wins, with no merging. If more than one config sits at the root, .languagecheck.yaml is used, then .languagecheck.yml, then .languagecheck.json. The others are ignored completely.

  • Multi-root workspaces use the config of the first folder, for every folder.

  • The command line reads the config from the directory it runs in. language-check check docs/ from the repository root uses the root config; running the same check from inside docs/ uses the config there, if there is one.

This is the model pyright and mypy use (one config per run), not the nearest-config-wins model of Prettier or ESLint’s flat config.

The editor says so when you open a config that is not in effect: a nested one, or one shadowed by a higher-precedence name at the root. It shows a single information note naming the file that is read, and none of the gutter status marks the config in effect gets.

Language Check: Edit Config opens the config in effect, which is the first of .languagecheck.yaml, .languagecheck.yml and .languagecheck.json at the root of the first workspace folder. If there is none, it creates .languagecheck.yaml with Harper on and a pointer to this guide, and opens that. The editor then marks what each key reaches, and saving reloads the checks like any other edit of the file.

The browser extension reads a config of its own for each project, account or workspace it checks, edited with the same command in its palette. It does not read the config of a VS Code project.

Engines

Control which checking engines are active:

engines:
  # Bool shorthand — just enable/disable:
  harper: true
  languagetool: false

  # Nested config — engine-specific settings:
  harper:
    enabled: true
    dialect: "American"       # American | British | Canadian | Australian | Indian
    linters:
      LongSentences: false    # Disable specific Harper rules

  languagetool:
    enabled: true
    url: "http://localhost:8010"
    level: "picky"            # "default" or "picky" (stricter rules)
    mother_tongue: "de-DE"    # For false-friends detection
    disabled_rules:
      - WHITESPACE_RULE
    enabled_rules: []
    disabled_categories: []
    enabled_categories: []
    max_concurrent_requests: 8  # In-flight /v2/check requests; 1 = serial

  vale:
    enabled: true
    config: ".vale.ini"       # Path to Vale config (auto-detected if omitted)

  proselint:
    enabled: false
    config: "proselint.json"  # Path to proselint config (auto-detected if omitted)

  spell_language: "en-US"     # BCP-47 tag for checking language

Both bool shorthand (harper: true) and nested config (harper: { enabled: true, dialect: "British" }) are supported. Use the shorthand when you only need to toggle an engine; use the nested form when you need engine-specific settings.

Note

Harper is built in and requires no external installation. LanguageTool, Vale, and Proselint are external tools that must be installed separately and available on your $PATH. See the dedicated setup guides:

The inspector health tab in VS Code shows whether each engine’s binary was detected and provides install instructions when missing.

Enabled engines run one after another and their diagnostics overlay. (Each engine may work concurrently inside its own turn — LanguageTool overlaps its requests — but the engines themselves are sequential.)

An engine is skipped when it does not handle the language being checked, or the markup the document is written in. Harper is English-only; an external provider or WASM plugin declares both through languages and extensions, and declaring neither means it takes everything. spell_language is the document default — a passage that declares its own language is checked in that one instead, and each language group goes only to the engines that claim it.

When two engines report the same rule over the same byte range, the reports are merged into one: the highest severity wins, and the suggestions are taken round-robin, one from each engine in turn, so the top of the list is every engine’s best guess before any engine’s tail. Spans that differ even by a byte are left as separate diagnostics.

Rule Overrides

Change severity or disable individual rules:

rules:
  spelling.typo:
    severity: warning    # error | warning | info | hint | off
  grammar.article:
    severity: "off"      # Disable this rule entirely

Exclude Patterns

Glob patterns to skip during workspace checking:

exclude:
  - "node_modules/**"
  - ".git/**"
  - "vendor/**"
  - "*.min.js"

Include and file types

include and file_types narrow what is checked. exclude then removes from that selection.

include:
  - "docs/**"                   # only these paths (empty: every file)
file_types: [md, tex]           # only these extensions (empty: every type the grammars recognise)
exclude:
  - "docs/_build/**"

include is a list of workspace-relative globs. file_types takes extensions without the leading dot, matched case-insensitively, and a leading dot is accepted and ignored. The built-in exclude list stays in force, and the patterns you write are added to it.

In the browser extension a site’s documents have no files on disk. Each check carries the document’s place in its project instead, such as chapters/intro.tex on Overleaf, and these three keys match that path as they match a file in VS Code. See the sites.

Auto-Fix Rules

Define custom find-and-replace rules applied automatically:

auto_fix:
  - find: "teh"
    replace: "the"
    description: "Fix common typo"
  - find: "colour"
    replace: "color"
    context: "American"    # Only apply when "American" appears in the text

Performance

Tune performance for large workspaces:

performance:
  high_performance_mode: false  # Only use Harper (skip LT and externals)
  debounce_ms: 300              # LSP debounce delay
  max_file_size: 1048576        # Skip files larger than 1MB (0 = unlimited)

Long documents

Three VS Code settings, not keys of the config file, control how a long document is checked. They also appear on the browser extension’s options page.

Setting

Default

Meaning

languageCheck.check.progressive

false

Make a document’s first check a window at a time, the window with the cursor or the top of the view first, and show findings as each window lands. Later checks are whole, because the core keeps what it found.

languageCheck.check.windowBytes

16384

The size of one window, in bytes of text, from 1024 to 1048576.

languageCheck.check.maxBytes

0

Check only the first this many bytes of a document, 0 for all of it. Prose that starts past the limit is not checked.

An edit stops the windows, and the document’s next check starts over in windows. The benchmarks show what a progressive check costs.

Dictionaries

Five domain wordlists ship with the checker — software-terms, typescript, companies, jargon and mathematics — and all of them load by default. Turn off the ones you do not want by name:

dictionaries:
  disabled: [companies]           # keep the rest
  paths:
    - .languagecheck/project-terms.txt

Set bundled: false to switch all five off at once. See Configuration Schema for the full field reference and how hyphenated words are matched.

Morphology

One dictionary entry covers the words built on it, so you do not have to add algebra, algebras, subalgebra and algebraicity separately. This is on by default:

morphology:
  enabled: true                 # accept prefixed and derived forms
  inflections: true             # accept plurals and regular verb forms

Prefixed and derived forms are recognized by taking the flagged word apart and requiring what is left to be a real word — subalgebra yes, subxyzzy no. Inflections are generated instead, because the spelling rules only work forwards: occur plus -ed is occurred, and a checker that stripped -ed from occured would quietly accept a typo.

Misspellings stay visible because the engine’s own correction overrides the analysis: if it can suggest something one edit away from what you typed, you still get a squiggle. See Configuration Schema.

Identifiers

Code names in prose are not words, so diagnostics inside a snake_case or camelCase token are dropped: parse_json_blob, MAX_RETRIES, getElementById, GitHub. This matters most in source comments, where identifiers are rarely in backticks. It is on by default:

identifiers:
  enabled: false                # check identifiers like any other word

A typo with a stray capital, like tHe, is still reported. See Configuration Schema.

Full Example

Here’s a .languagecheck.yaml putting it all together:

engines:
  harper:
    enabled: true
    dialect: "American"
  languagetool:
    enabled: true
    url: "http://localhost:8010"
    level: "default"
  vale:
    enabled: true
    config: ".vale.ini"
  proselint: false
  spell_language: "en-US"
  external:
    - name: custom-checker
      command: ./my-checker
      extensions: [md, rst]

rules:
  spelling.typo:
    severity: warning
  grammar.article:
    severity: "off"

exclude:
  - "node_modules/**"
  - ".git/**"

auto_fix:
  - find: "teh"
    replace: "the"

performance:
  high_performance_mode: false
  debounce_ms: 300

dictionaries:
  disabled: [companies]
  paths:
    - .languagecheck/project-terms.txt