A Visual Studio Code extension that reviews code comments written in Esperanto and reports grammatical issues as diagnostics, using LanguageTool.
Non-Esperanto comments are skipped automatically — you can use this alongside your existing English/other linters without noise.
Features
- Extracts comments from TypeScript, JavaScript, Python, Go, Rust, C/C++, Java, C#, Ruby, Shell, Lua, Haskell, HTML, XML, and Markdown.
- Auto-detects whether each comment is likely Esperanto (using diacritics, x-sistemo/h-sistemo surrogates, and common-word frequency).
- Sends detected Esperanto comments to LanguageTool (
eo ruleset) and surfaces matches as VS Code diagnostics.
- Manages LanguageTool for you: in
local mode the extension downloads the JAR on demand and spawns the server itself — no manual setup.
- Fails silently if Java is not installed: the status bar reports the reason and the linter simply does nothing. It never blocks the editor.
- Never auto-fixes — v1 is advisory.
Requirements
- Java (JRE) on
PATH — required by LanguageTool. If Java is missing, the status bar shows Esperanto: Java not installed and the linter does nothing (no errors, no popups). Install a JRE (e.g. brew install openjdk on macOS) and reload the window to enable.
Getting started (local mode — the default)
npm install- Press
F5 to launch the Extension Development Host.
- In the host, open the command palette and run Esperanto: Download LanguageTool. The extension downloads
LanguageTool-stable.zip (~240 MB) into its global storage directory, extracts it, and starts the server. You can also click the $(cloud-download) Esperanto: not set up item in the status bar to trigger the same flow.
- Open a source file and write an Esperanto comment, e.g.:
// Mi ŝatas programi en Esperanto
function saluton() {}
- Diagnostics from LanguageTool appear in the Problems panel and as squigglies.
On subsequent activations the JAR is reused — no re-download.
Remote mode (no Java required)
If you'd rather not install Java or download 240 MB, set:
"esperanto.serverMode": "remote",
"esperanto.serverUrl": "https://api.languagetool.org"
The public endpoint is free, rate-limited (~20 req/min per IP), and sends your comments off-machine. For private code, point serverUrl at a self-hosted LanguageTool server instead.
Configuration
All keys live under esperanto.*:
| Setting |
Default |
Purpose |
esperanto.serverMode |
"local" |
"local" = extension manages a Java server; "remote" = call serverUrl. |
esperanto.serverUrl |
http://localhost:8081 |
LanguageTool endpoint in remote mode. |
esperanto.localJarPath |
"" |
Optional explicit path to a languagetool-server.jar you already have. If blank, the extension uses its own cached copy. |
esperanto.localPort |
8081 |
Port for the managed local server. |
esperanto.detectionThreshold |
0.6 |
Confidence cutoff for "this comment is Esperanto". |
esperanto.minTokensForDetection |
3 |
Minimum token count before a comment is classified. |
esperanto.debounceMs |
500 |
Delay after last keystroke before re-linting. |
esperanto.severity.grammar |
"warning" |
Severity for grammar matches. |
esperanto.severity.style |
"info" |
Severity for style matches. |
Commands
Esperanto: Lint Current DocumentEsperanto: Clear DiagnosticsEsperanto: Show Detection Details for Current DocumentEsperanto: Download LanguageTool
Status
See STATUS.md for the current phase, PROGRESS.md for the roadmap, and ARCHITECTURE.md for the design.
License
MIT
