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.yamlin 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, useexclude, the per-language settings andrulesin the root config.One file wins, with no merging. If more than one config sits at the root,
.languagecheck.yamlis 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 insidedocs/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 |
|---|---|---|
|
|
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. |
|
|
The size of one window, in bytes of text, from 1024 to 1048576. |
|
|
Check only the first this many bytes of a document, |
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