textlint-rule-ukraine

A textlint rule that detects and fixes russified spellings of Ukrainian geographical and personal names.

The corrections database is sourced from the SpellingUkraine project (MIT) and other sources.

Install

npm install --save-dev textlint textlint-rule-ukraine

Usage

Add the rule to your .textlintrc:

{
  "rules": {
    "ukraine": true
  }
}

Lint your Markdown files:

npx textlint docs/**/*.md

Auto-fix in place:

npx textlint --fix docs/**/*.md

Replacements are case-preserving:

| Input | Output | | ------------ | ----------- | | Bahmut | Bakhmut | | BAHMUT | BAKHMUT | | bahmut | bakhmut | | Artyomovsk | Artemivsk |

Text inside fenced code blocks and inline backtick spans is never touched.

Only three casing patterns are detected: ALL CAPS, all lower, and Title case. Mixed or irregular casing like aRTyOMovsK is left in canonical form (Artemivsk) instead of trying to mirror a garbled input — the fix is always clean Ukrainian orthography.

Options

The dictionary is split into tagged groups. geo is on by default; names and extra are opt-in.

| Option | Default | Covers | | --------------------- | -------- | ----------------------------------------------------------- | | geo | true | Place names (cities, regions, rivers) | | names | false | Personal names (first names, public figures) | | extra | false | Opinionated corrections (e.g. lowercase russia) | | dictionaryOverrides | [] | Additional entries appended at runtime (see below) |

To enable personal names checking:

{
  "rules": {
    "ukraine": { "names": true }
  }
}

To enable all groups:

{
  "rules": {
    "ukraine": { "names": true, "extra": true }
  }
}

To disable place names (e.g. when only personal names matter):

{
  "rules": {
    "ukraine": { "geo": false, "names": true }
  }
}

dictionaryOverrides

Append entries to the dictionary at runtime without patching data/dictionary.json inside node_modules. Each entry follows the same shape as the built-in dictionary and supports the same fields, including the exact flag (see Dictionary):

{
  "rules": {
    "ukraine": {
      "dictionaryOverrides": [
        { "wrong": ["Novoiavorivsk"], "correct": "Novoiavorivsk", "id": "novoiavorivsk", "tags": ["geo"] }
      ]
    }
  }
}

If an override declares the same wrong string as a built-in entry, the override wins (last-write-wins).

Dictionary

All entries live in data/dictionary.json. Each entry has the form:

{ "wrong": ["Bahmut", "Bahmoot"], "correct": "Bakhmut", "id": "bakhmut", "tags": ["geo"] }

By default replacements are case-preserving (Bahmut→Bakhmut, BAHMUT→BAKHMUT). Add "exact": true to always output correct verbatim regardless of input casing:

{ "wrong": ["Russia"], "correct": "russia", "id": "example", "exact": true, "tags": ["extra"] }

Override entries follow the same format — use tags to control which option group activates them.

Contributing

Dictionary improvements go directly in data/dictionary.json. Rule improvements (casing logic, AST handling, performance) go in src/.

License

MIT