languagetool.el

Introduction

LanguageTool is a free and open-source multilingual grammar, style, and spell checker with support for more than 30 languages. So, why not use it as your Emacs grammar and spell check tool. That is what this package is for.

languagetool.el is a tool written for Emacs keeping in mind integrity and display. In a way that you can see all the issues which LanguageTool generates for your text and which kind of issue is, by following a colour key.

LanguageTool standalone version comes with tree different executables written in Java:

• The first is the GUI, to use LanguageTool directly.
• The other is the Command Line Interface, to check text in this way.
• And the final one is the Server, to create an HTTP server to check text via requests.

languagetool.el creates a wrapper for two of these three tools, the CLI (console module) and the Server (server module).

Installation

Obtaining the prerequisites

As LanguageTool is code in Java, you need to install that on your system. LanguageTool requires Java 8 or later to work.

You’ll need (obviously) LanguageTool itself, you can download it in this link or, if available, with your package manager.

If you download LanguageTool Zip file, extract the contents in a folder you want; for example /home/pillfall/.languagetool/, if you use LanguageTool with other tools could be a great option.

In case you use your package manager, find out if it download the class files or the standalone executable and where it put them, this is useful for later configuration. For example ArchLinux download the class files and puts them in the /usr/share/languagetool and /usr/share/java/languagetool directories.

Obtaining the package

You can install the package using the MELPA repository or via use-package.

In case you use the latter and get the LanguageTool Zip, one default configuration, enabling all current features, would be:

(use-package languagetool
  :ensure t
  :defer t
  :commands (languagetool-check
             languagetool-clear-suggestions
             languagetool-correct-at-point
             languagetool-correct-buffer
             languagetool-set-language
             languagetool-server-mode
             languagetool-server-start
             languagetool-server-stop)
  :config
  (setq languagetool-java-arguments '("-Dfile.encoding=UTF-8")
        languagetool-console-command "~/.languagetool/languagetool-commandline.jar"
        languagetool-server-command "~/.languagetool/languagetool-server.jar"))

If you want to install it from source, you can clone this repository and do all the configuration manually (create a package.el, generate autoloads.el, etc.). Right now, there are no installation steps following this approach, so you’ll need to know what you are doing, but there is a handy makefile which byte compiles all the elisp files.

Configuring the package

To get this package to work, you’ll need to configure some variables.

First you must configure Java to accept files in UTF-8, for that purpose, set languagetool-java-arguments using customize interface or with elisp like follows:

(setq languagetool-java-arguments '("-Dfile.encoding=UTF-8"))

Then you need to tell the package how do you plan to call LanguageTool.

If you download, extracted and plan to use the LanguageTool Zip, set languagetool-console-command and languagetool-server-command using customize interface or with elisp like follows:

(setq languagetool-console-command "~/.languagetool/languagetool-commandline.jar"
      languagetool-server-command "~/.languagetool/languagetool-server.jar")

If you are going to use a package manager, and it download the class files, you will call LanguageTool from its class, so set languagetool-java-arguments, languagetool-console-command and languagetool-server-command using customize interface or with elisp like follows:

(setq languagetool-java-arguments '("-Dfile.encoding=UTF-8"
                                    "-cp" "/usr/share/languagetool:/usr/share/java/languagetool/*")
      languagetool-console-command "org.languagetool.commandline.Main"
      languagetool-server-command "org.languagetool.server.HTTPServer")

If you pay for LanguageTool Premium features, you can add the keys for the LanguageTool api as follows:

(setq languagetool-api-key "xxxxxxxxxxxx"
      languagetool-username "[email protected]")

By default, the correction language is auto and it is buffer local, meaning that you could check in different languages different files, if you want to change the language, you could use local file variables to define the language to use in that buffer, setting the variable languagetool-correction-language, or call languagetool-set-language.

If you want to know more customization options you can find those at the customize interface.

Quick Usage

When you end customizing the packages (faces, languages, etc.). You can now start checking your text. So, you can use either console mode or server mode.

console Mode

In this mode, when you start checking, the first thing you need to do is call languagetool-check. This will invoke LanguageTool in the current region, if any, and then highlight all the suggestions made by the tool. If there is no region, the whole available portion of the buffer will check.

This function is synchronous. Therefore, it blocks Emacs until LanguageTool done with your text. This is the right behaviour, as LanguageTool is a bit slow checking text in this mode, so it prevents you from changing the text while checking.

After LanguageTool highlights all its suggestions, now you can correct your text, then put your cursor on the underlined word and call languagetool-correct-at-point, this will pop up a transient minibuffer with all the suggestions, choose the one fits your needs, and you are ready to go. There is also a buffer wide correction function, called languagetool-correct-buffer, you can call it if you want to check all the buffer, suggestion by suggestion.

If you finish, and don’t want to see any more suggestions, call languagetool-clear-suggestions and all the highlighting will disappear.

server Mode

In this mode, you first start having a running the server. To initialize it, you can call languagetool-server-start, then you’ll have a running server attached to Emacs (If you close Emacs, it’s over). This server starts to listen in port 8081 by default. You can change it by setting languagetool-server-port to another value.

If you are going to use a server with another configuration, like servers not located in your localhost, you must set languagetool-server-host and languagetool-server-port to whatever adjust your needs. These variables play in the communication to the LanguageTool HTTP API.

After your server is running, you can toggle on the languagetool-server-mode. LanguageTool then starts to highlight all its suggestions in the available portion of the buffer. You use the same method as in ~console~ mode to correct your text.

If you finish, just toggle off the languagetool-server-mode, it will take all the LanguageTool suggestions with itself.