Skip to content

Latest commit

 

History

History

korean-prose

Folders and files

README.md

korean-prose

Reviews Korean writing for one thing: whether it reads like Korean somebody wrote, or like English wearing Korean words.

한국어 문서는 README-ko.md를 참고하세요.

In Claude Code:

/plugin marketplace add somaz94/claude-plugins
/plugin install korean-prose@somaz94

Or from your shell, without an interactive session:

claude plugin marketplace add somaz94/claude-plugins
claude plugin install korean-prose@somaz94

Why this exists

A spell-checker reads one word. A grammar checker reads one sentence. Both pass the sentence 본 문서는 마이그레이션에 있어서 중요성을 가진다 without a complaint, because every word is spelled correctly and the grammar is intact. It is still not Korean anybody writes.

That gap is where translated documentation lives. A README written in English and rendered into Korean keeps the English skeleton — the possessive chains, the passive voice, the "it is important to" frame — and the result reads like a document you have to decode rather than read. Nothing flags it, because nothing is wrong at the level any tool checks.

The newer half of the problem is not translation at all. Text that was generated carries its own tells: the filler discourse marker, the mechanical 첫째 … 둘째 …, the contrast frame used three times in one paragraph. Those are invisible to a translation-aware eye, because nothing was translated.


What it catches

Pattern Why it reads wrong What it should be
~에 있어서 Japanese-syntax residue, near-dead in modern Korean ~에서, or drop it
중요성을 가지다 English "to have importance" 중요하다
검토 진행, 구축 진행 Nominalize a word that is already a verb 검토했다, 구축했다
압력을 완화 pressure translated to the word for air pressure 부하를 완화
간접화 indirection rendered as a word that does not exist 분리
~하는 것이 가능하다 Calque of "it is possible to" ~할 수 있다
되어지다, 보여지다 Passive applied twice 되다, 보이다
무변경, 무사고 A stiff 無X back-translation of "zero-/no-X" 변경 없이, 사고 없이

The middle rows are the ones worth the install. 압력, 정렬, 수렴, 재활용, 함정, 완주 are all real Korean words that a dictionary will happily offer for the English term — and all six point somewhere else once they land in a technical sentence. The translation happened, and destroyed the meaning on the way. The plugin ships that substitution dictionary with the reason each one fails.

The patterns are data, not prompt text: lexicon/patterns.tsv holds one awkward word or construction per row — its regex, a severity, an example it must match, why it reads wrong, what to write instead, and optionally the natural sentences it must leave alone — and lexicon/terms.tsv holds one referent and its spellings. A standard-library scanner, scripts/scan.py, runs both before the agent reads anything, so every review starts from the same candidates. It reads only Korean prose: code, links and markup are blanked, the en: half of a bilingual YAML file is skipped, a Korean YAML with no ko: key is read whole instead, an HTML page or slide deck is read for its visible text at the original line numbers, and a line with no Hangul is left alone. Headings, and in HTML table headers and lead / strip lines, are tagged as titles so that title-only rows fire on them alone. A new pattern is one row, and python3 scripts/scan.py --check-lexicon refuses a row whose example does not match its own regex, or whose counterexample does. Run by hand on a long document, --severity red or --category spelling narrows the report.


The pass a token scan cannot do

Every pattern above is visible inside one line. The findings that survive a clean sweep are only visible when a line is read against its neighbours, and they are the ones a human reviewer notices last:

  • 형제 구조 이탈 — one bullet in a list is two sentences where the rest are one, or leads with a verb where the rest lead with the outcome. It is fine alone and wrong in place.
  • 이웃 중복 — two items in the same block say the same thing. Not every overlap is a defect: a technology name repeated across an approach line and an outcome line is required, not redundant. The plugin sorts the three kinds and reports only the one that is a finding.
  • 과장 드리프트 — 차단 where the evidence says 방지, or a condition that never existed described as a defect that was fixed.
  • 표기 일관성 — Pod in one paragraph and 파드 in the next, or Canary beside canary, usually because a later edit followed the writer's habit rather than the file's. The scanner counts every spelling, including English words written in two letter cases; whether two spellings name the same thing — Helm the product, helm the CLI — is still a reading job.
  • 용어 도입 관례 — a bare fail-fast in prose that writes 부분 장애(gray failure) everywhere else. Spelling-consistency passes it trivially; the document's own convention does not.
  • 제목 장르 — a title is a label, not a sentence. A slide headline that ends in ~했습니다, drops its verb and ends on a particle (스케줄 · 스크립트로), or turns into a slogan (A가 곧 B) is rewritten to a noun phrase. When every title in a deck shares the defect there is no outlier to compare against, so each title is judged on its own shape and the shared defect is reported once.

Each is reported with its evidence — the sibling lines compared, or the two counts. A finding you cannot check is not a finding.


Two modes, and picking the wrong one is the usual disappointment

감사 is a sweep: point it at a file, a directory, or nothing, and get every finding categorized. Read-only, always — a bulk apply you have not read line by line is exactly what that restriction exists to prevent.

판정 is a verdict on one thing: you rewrote a sentence and want to know whether it is better. It reads the item in place with its siblings, keeps the improvements your version already made and says which ones it kept, and returns the merged line as one ready-to-apply edit. The agent has no Edit tool; the /korean-prose:review command shows you 전/후 in full and applies the edit itself only after you say yes. A sub-agent cannot ask you, and an approval relayed through another agent is not yours.

Somebody holding one rewritten sentence does not want a forty-finding file audit. When the invocation is ambiguous the plugin asks in one line and defaults to 판정, because that is the cheaper wrong answer.


Scope

In scope: any .md whose body is predominantly Korean prose, the visible text of a Korean HTML page or slide deck (reviewed, never edited), and the ko: half of a YAML file whose strings are { ko, en } pairs.

Out of scope: the en: half, *-en.md, English .md, code blocks, inline code, URLs, file paths, and comments in source files. Korean-only, in both directions — it will not rewrite your English to match a Korean change, and it will say so if a fix puts the pair out of parity.

In a bilingual file it reads the en: sibling first. These documents are usually authored EN → KO, so the Korean half is the degraded one: the object, the qualifier, or the unit fell out in translation while English still states it. QA delivery-time became QA 전달 90% 단축 — the unit vanished, and what actually shrank was the time. Restoring from the English half makes the rewrite verifiable instead of creative.


What it never does

  • Changes what the text claims. Numbers, technology labels, dates, and arrows survive every rewrite; a fact that looks wrong is flagged, never silently corrected.
  • Edits in 감사 mode, however obvious the fix looks.
  • Edits a file itself. In 판정 mode the edit goes back to the main session, which applies it only after showing 전/후 in full and being told yes — and one approval covers one item, never the file.
  • Touches the en: half or any English document.
  • Adds, removes, reorders, merges, or splits a heading, section, list item, or table row.
  • Flags a spaced em-dash. It is deliberate in technical prose, and a rule against it buries every real finding.

Releases

Each plugin in this marketplace is versioned and released on its own. Every change to korean-prose — with the commits scoped to this directory — is at korean-prose releases.


License

MIT — see LICENSE.