Esperanto - Code Comment Linter

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)

1. npm install
2. Press F5 to launch the Extension Development Host.
3. 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.
4. Open a source file and write an Esperanto comment, e.g.:

   // Mi ŝatas programi en Esperanto
   function saluton() {}
   

5. 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.*:

Commands

• Esperanto: Lint Current Document
• Esperanto: Clear Diagnostics
• Esperanto: Show Detection Details for Current Document
• Esperanto: Download LanguageTool

Status

See STATUS.md for the current phase, PROGRESS.md for the roadmap, and ARCHITECTURE.md for the design.

License

MIT