Custom Providers¶
Language Check supports external checker binaries that communicate via stdin/stdout JSON.
Note
Vale has built-in first-class support — use engines.vale: true
instead of registering it as a custom provider. See Vale Setup.
Configuration¶
Register external providers in .languagecheck.yaml:
engines:
external:
- name: custom-checker
command: ./my-checker
- name: another-tool
command: /usr/bin/another-tool
args: ["--format", "json"]
extensions: [md, rst] # markup it parses
languages: ["en", "de"] # languages it checks
extensions and languages are different questions, and a provider is skipped
when either excludes the document. Leaving one out means “all of them”.
Declaring languages matters more than it looks: a provider that claims every
language makes the checker believe the passage was checked, which suppresses
the report saying nothing could read it — so a provider that only speaks
English silently hides the fact that a Hebrew paragraph went unchecked.
Protocol¶
Request (stdin)¶
The provider receives a JSON object on stdin:
{
"text": "The prose to check.",
"language_id": "en-US"
}
language_id is the natural language being checked as a BCP-47 tag, not
the markup format — en-US, de-DE, fr. The document’s markup is not sent;
declare extensions if the provider needs to know it.
text is one extracted prose range, not the whole file. A document is checked
range by range, so a provider is invoked once per range and its byte offsets
are relative to the text it was given.
Response (stdout)¶
The provider must return a JSON array of diagnostics on stdout:
[
{
"start_byte": 4,
"end_byte": 8,
"message": "Consider using 'complete' instead of 'full'.",
"suggestions": ["complete", "entire"],
"rule_id": "style.word-choice",
"severity": 2,
"confidence": 0.8
}
]
Diagnostic Fields¶
Field |
Type |
Required |
Description |
|---|---|---|---|
|
|
Yes |
Start byte offset (UTF-8) |
|
|
Yes |
End byte offset (UTF-8) |
|
|
Yes |
Human-readable description |
|
|
No |
Replacement suggestions (default: |
|
|
No |
Rule identifier (default: provider name) |
|
|
No |
1=Info, 2=Warning, 3=Error, 4=Hint (default: 2) |
|
|
No |
0.0–1.0 confidence score (default: 0.7) |
An optional field that is left out or set to null takes the default. An
output of null instead of an array means no diagnostics.
Rule IDs are automatically prefixed with external.<provider-name>. for namespacing.
Error Handling¶
A provider that fails is reported as failed, not as having found nothing. Each of these is an error:
The binary cannot be started (not found, not executable).
The binary exits non-zero. The first line of its
stderrgoes into the error.The binary is killed after 30 seconds, or once it writes more than 16 MiB to
stdout.Its output is not a JSON array of diagnostics.
The error is logged and counted against the provider’s health. If no other engine reported anything for the passage, it shows a notice that it went unchecked rather than looking clean.
High Performance Mode¶
External providers are skipped when performance.high_performance_mode is enabled.