LanguageTool Ukrainian — Docker

🇺🇦 Українська | 🇬🇧 English

---

Українська

Локальний LanguageTool сервер із 300+ кастомними правилами для перевірки нативності українського тексту. Виявляє русизми, кальки, стилістичні помилки, проблеми зі сполучуваністю, пунктуацією та прийменниковим керуванням. Кастомні правила інжектуються в офіційний LanguageTool на етапі збірки Docker-образу.

Що це робить

Офіційний LanguageTool для української мови має ~1250 правил, але значні прогалини у виявленні:

• Калькованих конструкцій з російської (являється, слідуючий, на протязі)
• Порушень сполучуваності (грає роль замість відіграє роль)
• Помилок керування (по закінченню замість після закінчення)
• Пунктуації вставних слів (наприклад, безперечно, ймовірно)
• Узгодження і/й/та у складних фонетичних контекстах
• Омонімії (вставне слово vs. прислівник)

Цей проєкт додає ~207 граматичних + 96 дизамбігуаційних правил, які закривають ці прогалини.

Швидкий старт

# Збілдити та запустити (порт 8010)
docker compose up -d --build

# Перевірити правила
./test.sh

# Тільки валідація XML (без сервера)
./test.sh --validate

Правила

Файл	Кількість	Категорії
grammar-fluency-ua.xml	~100	Кальки, сполучуваність, плавність, стиль
agreement-yi.xml	56	Узгодження і/й/та (POS, частотне, дистантне)
grammar-punctuation-ua.xml	20	Вставні слова, парні конструкції, типографіка
grammar-government-ua.xml	17	Прийменникове керування (по + Дав.)
russisms-yi.xml	14	Русизми и→і (сами→самі, которий→котрий)
disambiguation-ua.xml	96	Дизамбігуація вставних слів vs. прислівників

Приклади правил

Тип	Помилка	Виправлення
Калька	на протязі року	протягом року
Калька	являється спеціалістом	є спеціалістом
Сполучуваність	грає роль	відіграє роль
Плавність	прийняти міри	вжити заходів
Керування	по закінченню роботи	після закінчення роботи
Пунктуація	Наприклад можна зробити	Наприклад**,** можна зробити
Русизм	сами зробили	самі зробили

Як це працює

rules/*.xml  →  Docker build  →  Інжекція в офіційний LT  →  Єдиний сервер

1. Кастомні XML-файли лежать у rules/
2. При збірці Docker-образу <category> блоки витягуються та інжектуються у grammar-barbarism.xml
3. Дизамбігуаційні правила інжектуються в disambiguation.xml
4. Сервер працює з офіційними + кастомними правилами

Налаштування клієнтів

Браузерне розширення (Chrome / Firefox / Edge)

1. Розширення LanguageTool → ⚙️ Settings
2. Advanced settings → Other server
3. URL: http://localhost:8010/v2

LibreOffice

1. Tools → LanguageTool → Settings
2. Server URL: http://localhost:8010/v2

API

# Перевірити текст
curl -s "http://localhost:8010/v2/check" \
  -d "language=uk" \
  --data-urlencode "text=Він являється головним спеціалістом." | python3 -m json.tool

# З конкретними категоріями
curl -s "http://localhost:8010/v2/check" \
  -d "language=uk" \
  -d "enabledCategories=UA_GEC_CALQUE,UA_GEC_STYLE,UA_GEC_COLLOCATION,UA_GEC_POORFLOW" \
  --data-urlencode "text=Ваш текст тут"

Тестування

./test.sh --validate    # Валідація XML (без сервера)
./test.sh --regression  # Регресійні тести (потрібен сервер)
./test.sh               # Повний набір тестів (потрібен сервер)

Додавання правил

Відредагуйте відповідний файл у rules/ та перебілдіть:

docker compose up -d --build

Формат правила:

<rule id="UA_GEC_MY_RULE" name="моє правило">
  <pattern>
    <token>помилкове</token>
    <token>слово</token>
  </pattern>
  <message>Краще: <suggestion>правильний варіант</suggestion></message>
  <example correction="правильний варіант">Це <marker>помилкове слово</marker>.</example>
  <example>Це правильний варіант.</example>
</rule>

Параметри Docker

Змінна	Значення	Опис
Java_Xms	512m	Мінімальна пам'ять JVM
Java_Xmx	2g	Максимальна пам'ять JVM
langtool_pipelinePrewarming	true	Прогрів pipeline при старті

---

English

Local LanguageTool server with 300+ custom rules for checking Ukrainian text nativeness. Detects calques (loan translations from Russian), collocations, stylistic issues, prepositional government errors, punctuation problems, and conjunction agreement. Custom rules are injected into official LanguageTool at Docker build time.

What it does

Official LanguageTool for Ukrainian has ~1250 rules but significant gaps in detecting:

• Calques from Russian (являється, слідуючий, на протязі)
• Collocation errors (грає роль → відіграє роль)
• Government errors (по закінченню → після закінчення)
• Parenthetical word punctuation (наприклад, безперечно, ймовірно)
• Conjunction agreement (і/й/та in complex phonetic contexts)
• Ambiguity resolution (parenthetical word vs. adverb)

This project adds ~207 grammar + 96 disambiguation rules to fill these gaps.

Quick start

# Build and start (port 8010)
docker compose up -d --build

# Test the rules
./test.sh

# XML validation only (no server needed)
./test.sh --validate

Rules

File	Count	Categories
grammar-fluency-ua.xml	~100	Calques, collocations, flow, style
agreement-yi.xml	56	і/й/та conjunction agreement (POS, frequency, distant)
grammar-punctuation-ua.xml	20	Parenthetical words, paired constructions, typography
grammar-government-ua.xml	17	Prepositional government (по + Dative)
russisms-yi.xml	14	и→і russisms (сами→самі, которий→котрий)
disambiguation-ua.xml	96	Parenthetical words vs. adverbs disambiguation

Rule examples

Type	Error	Correction
Calque	на протязі року	протягом року
Calque	являється спеціалістом	є спеціалістом
Collocation	грає роль	відіграє роль
Flow	прийняти міри	вжити заходів
Government	по закінченню роботи	після закінчення роботи
Punctuation	Наприклад можна зробити	Наприклад**,** можна зробити
Russism	сами зробили	самі зробили

How it works

rules/*.xml  →  Docker build  →  Inject into official LT  →  Single server

1. Custom XML files live in rules/
2. During Docker build, <category> blocks are extracted and injected into grammar-barbarism.xml
3. Disambiguation rules are injected into disambiguation.xml
4. Server runs with official + custom rules merged

Client setup

Browser extension (Chrome / Firefox / Edge)

1. LanguageTool extension → ⚙️ Settings
2. Advanced settings → Other server
3. URL: http://localhost:8010/v2

LibreOffice

1. Tools → LanguageTool → Settings
2. Server URL: http://localhost:8010/v2

API usage

# Check text
curl -s "http://localhost:8010/v2/check" \
  -d "language=uk" \
  --data-urlencode "text=Він являється головним спеціалістом." | python3 -m json.tool

# Check with specific categories
curl -s "http://localhost:8010/v2/check" \
  -d "language=uk" \
  -d "enabledCategories=UA_GEC_CALQUE,UA_GEC_STYLE,UA_GEC_COLLOCATION,UA_GEC_POORFLOW" \
  --data-urlencode "text=Your Ukrainian text here"

Testing

./test.sh --validate    # XML validation (no server)
./test.sh --regression  # Regression tests (needs running server)
./test.sh               # Full test suite (needs running server)

Adding rules

Edit the appropriate file in rules/ and rebuild:

docker compose up -d --build

Rule format:

<rule id="UA_GEC_MY_RULE" name="my rule">
  <pattern>
    <token>wrong</token>
    <token>phrase</token>
  </pattern>
  <message>Better: <suggestion>correct phrase</suggestion></message>
  <example correction="correct phrase">This <marker>wrong phrase</marker>.</example>
  <example>This correct phrase.</example>
</rule>

Docker parameters

Variable	Default	Description
Java_Xms	512m	Minimum JVM memory
Java_Xmx	2g	Maximum JVM memory
langtool_pipelinePrewarming	true	Prewarm pipeline on startup

Management

docker compose up -d          # Start
docker compose down           # Stop
docker compose logs -f        # Logs
docker compose up -d --build  # Rebuild after rule changes

License

Custom rules in rules/ are licensed under MIT.

The Docker image includes LanguageTool, which is licensed under LGPL 2.1. Reference copies of official LanguageTool files in reference/official-lt/ retain their original LGPL 2.1 license. Copyright for official LanguageTool Ukrainian rules belongs to their respective authors (see file headers).