Skip to main content

Grammar and Prose Check with LanguageTool

Last updated on by cernus76

When you open a pull request, a grammar and prose check reads the English text in your changed pages and offers gentle suggestions: a stray double word, a missing comma, an awkward construction. It is powered by reviewdog and LanguageTool, and it complements the spell check rather than replacing it.

What this check does​

LanguageTool is a mature open-source proofreading engine. In our setup it runs bundled inside the reviewdog action's container image. There are no calls out to any external grammar API, so your prose never leaves the GitHub Actions runner. reviewdog then takes LanguageTool's findings and surfaces them where you can act on them.

Think of it as a friendly editor reading over your shoulder:

  • Spelling is handled elsewhere, by cspell and its custom dictionaries.
  • Grammar and style (word repetition, agreement, punctuation flow) is what this check looks at.
Two layers, one goal

Spelling and grammar are deliberately split across two checks. That keeps SAP product names you have already allowed in the custom dictionaries from being re-flagged here, and it keeps each check's output focused and easy to read.

Scope: what gets checked​

The check runs on pull requests that target the dev branch and that touch Markdown prose:

AspectValue
File types.md files under docs/ and news/
TriggerPull requests targeting dev
Languageen-US only
.mdx filesIntentionally excluded for now
# From .github/workflows/check-grammar.yml
patterns: docs/**/*.md news/**/*.md
language: en-US
Why .mdx is skipped

.mdx pages mix Markdown with JSX and import lines. Those lines look like broken sentences to a prose checker and generate the most false positives, so they are left out until the rules are tuned further. Plain .md pages (the vast majority of content, including everything the Quick Start editor produces) are fully covered.

LanguageTool scans the tracked docs/ and news/ .md files on each run, and reviewdog then narrows the visible annotations down to the lines you actually changed in the PR. You will not be shown pre-existing issues in parts of a file you never touched.

It never fails your PR​

This is the most important thing to understand as a contributor: the grammar check is non-blocking by design. It can surface warnings, but it can never turn red and it can never stop your pull request from merging.

Two independent safeguards guarantee this:

  1. The action is run without reviewdog's fail-on-error flag (and exposes no input to turn it on), so reviewdog exits successfully no matter how many findings it reports.
  2. The step also carries continue-on-error, so even a hiccup (a read-only token on a fork PR, or the bundled server being slow to boot) cannot make the check fail.

The reported level is warning, which only sets the severity label on the comments; it does not change the pass/fail outcome.

This one is advisory

If you see grammar suggestions, treat them as a helpful second read, not a gate. You are free to apply the ones that improve your text and ignore the ones that do not fit (technical phrasing, intentional style, product terminology).

Where the suggestions appear​

Where you see the findings depends on how you opened the PR:

Your situationWhere suggestions show up
Branch on the main repository (core contributors)Annotations on the Checks tab, inline on your changed lines (github-pr-check)
Pull request from a forkGitHub issues a read-only token, so the Checks-tab annotations cannot be posted. Open the grammar step's Actions run log to see the raw output, and a maintainer can relay any grammar suggestions on the pull request if needed

If you contributed through a fork (the recommended path for most community members) and do not see inline annotations, that is expected. Open the workflow run from the Actions tab and read the grammar step's log to see the same suggestions.

What it does not flag​

To keep the signal clean, several categories and rules are switched off on purpose:

Turned offWhy
TYPOS categorySpelling is owned by cspell and the custom dictionaries; this avoids re-flagging allowed SAP terms.
TYPOGRAPHY categoryCurly quotes, fancy dashes, and arrows are noisy against code and Markdown.
A set of Markdown-noise rulesRules like whitespace, underscores in words, and bracket pairing misfire on Markdown and code; they are disabled individually.
# From .github/workflows/check-grammar.yml
disabled_categories: TYPOS,TYPOGRAPHY
disabled_rules: WHITESPACE_RULE,EN_QUOTES,DASH_RULE,WORD_CONTAINS_UNDERSCORE,...

As a contributor​

Here is the short version of how to work with this check:

  • Read the suggestions, apply what helps. A flagged repeated word or missing comma is usually worth a quick fix.
  • Do not chase a green check. There is nothing to turn green here. The check is informational.
  • Found a false positive? Maintainers tune the check by appending the offending rule id to the disabled_rules list in the workflow. If a legitimate phrasing keeps getting flagged, mention it in your PR and a maintainer can silence that specific rule.
warning

Because the check only reads .md files, prose inside .mdx pages is not proofread automatically today. Give those pages an extra manual read before you submit.