From e8d97ffc3eb8fb56fc8260aea6f588e4df6f3015 Mon Sep 17 00:00:00 2001
From: Jeonghyeock <52453875+Jeonghyeock@users.noreply.github.com>
Date: Thu, 22 Oct 2026 07:22:00 +0900
Subject: [PATCH] docs(ko): apply native-speaker review to the Korean glossary
 and instructions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- capability → 지원 기능, keeping 기능 for "feature"
- elicitation → 사용자 입력 요청 (no transliteration)
- era: name the protocol versions instead of a time word (no 2025년대)
- deprecated: "`2026-07-28` 사양부터 지원 중단 예정", never shortened to 지원 중단
- new entries for terms rendered inconsistently across pages: argument,
  parameter, annotation, docstring, spec, server-initiated request,
  provider, completion, Completions, wire
- instructions: requirement strength (must/should/may) endings, headings
  never end in a verb ending, no -ㅂ시다

Fixes #3732

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 i18n/ko/glossary.json   | 76 ++++++++++++++++++++++++++++++++++++++---
 i18n/ko/instructions.md | 35 ++++++++++++++-----
 2 files changed, 97 insertions(+), 14 deletions(-)

diff --git a/i18n/ko/glossary.json b/i18n/ko/glossary.json
index ca64f0916b..18bdd9fdfb 100644
--- a/i18n/ko/glossary.json
+++ b/i18n/ko/glossary.json
@@ -89,13 +89,14 @@
     },
     {
       "source": "elicitation",
-      "target": "엘리시테이션",
-      "note": "Transliteration; write 엘리시테이션(elicitation) at the first occurrence on a page, 엘리시테이션 alone afterwards. The verb \"elicit\" in prose is 사용자에게 입력을 요청하다; `ctx.elicit(...)` stays code. Provisional pending native review — the least settled term in this file; 유도 is the candidate alternative to confirm against, so it is noted here rather than banned; 도출 is not a candidate."
+      "target": "사용자 입력 요청",
+      "note": "The server asking the user for input through the client. Write 사용자 입력 요청(elicitation) at the first occurrence on a page, 사용자 입력 요청 alone afterwards. Compounds: form elicitation → 폼 입력 요청, URL-mode elicitation → URL 모드 입력 요청, push elicitation → 푸시 입력 요청. An \"elicitation request\" is just 사용자 입력 요청, never 사용자 입력 요청 요청. The verb \"elicit\" in prose is 사용자에게 입력을 요청하다; `ctx.elicit(...)` and `elicitation/create` stay code. Not the transliteration 엘리시테이션, which carries no meaning for Korean readers, and not 유도, which reads as nudging the user. Native review (#3732).",
+      "avoid": ["엘리시테이션", "요청 요청"]
     },
     {
       "source": "capability",
-      "target": "기능",
-      "note": "A negotiated protocol feature (\"capability negotiation\" → 기능 협상), not 역량 or 능력; the `capabilities` wire field and `client.server_capabilities` stay Latin in code. Provisional pending native review — 기능 doubles as \"feature\"; native review should confirm the collision is acceptable."
+      "target": "지원 기능",
+      "note": "What a client or server declares that it supports, negotiated when the connection starts (\"capability negotiation\" → 지원 기능 협상). Plain 기능 stays reserved for \"feature\", so the two remain distinct even in adjacent sentences: \"A callback is a capability\" → 콜백 등록이 곧 지원 기능 선언. Not 역량 or 능력; the `capabilities` wire field and `client.server_capabilities` stay Latin in code. Native review (#3732)."
     },
     {
       "source": "transport",
@@ -169,7 +170,8 @@
     {
       "source": "deprecated",
       "target": "지원 중단 예정",
-      "note": "Advisory status: still works but discouraged. First occurrence on a page may add the original: 지원 중단 예정(deprecated). \"Removed\" is a different word (제거됨); the corpus contrasts the two, so never render deprecated as 폐기됨 or 제거됨. Provisional pending native review."
+      "note": "Advisory status: still works but discouraged. First occurrence on a page may add the original: 지원 중단 예정(deprecated). Never shorten it to 지원 중단, which reads as already unsupported: \"deprecation warning\" → 지원 중단 예정 경고. When a protocol revision marks the point of deprecation, write 사양부터: \"deprecated at `2026-07-28`\" → `2026-07-28` 사양부터 지원 중단 예정, never `2026-07-28`에서, which reads as a calendar date. \"Removed\" is a different word (제거됨); the corpus contrasts the two, so never render deprecated as 폐기됨 or 제거됨. Native review (#3732).",
+      "avoid": ["지원 중단 경고"]
     },
     {
       "source": "round-trip",
@@ -181,6 +183,70 @@
       "target": "lifespan",
       "note": "Keep the English word in Korean prose (lifespan 함수, 호스트 앱의 lifespan), matching the `lifespan=` parameter it names. Provisional pending native review — 수명 주기 was rejected because it collides with \"lifecycle\" (생명 주기)."
     },
+    {
+      "source": "era (2025-era, 2026-era, handshake era, modern era)",
+      "target": "프로토콜 버전",
+      "note": "An era is a group of protocol revisions, not a period of time, so it gets no Korean noun of its own: name the versions instead. 2025-era and handshake-era → `2025-11-25` 이하 버전; 2026-era and modern era → `2026-07-28`; pre-2026 → `2026-07-28` 이전 버전; a generic \"era\" (\"any era of server\", \"MCP has two eras\") → 프로토콜 버전. Never a time word: not -년대 (a decade, so 2025년대 is not Korean), 시대, 시절 or 세대. Native review (#3732).",
+      "avoid": ["년대"]
+    },
+    {
+      "source": "wire (on the wire, wire name, wire format)",
+      "target": "실제로 주고받는 메시지",
+      "note": "No single noun; render by context. On or across the wire → 실제로 주고받는 메시지에서; a wire name, key or format → 프로토콜상 이름 / 키 / 형식; the wire as the channel (stdout under stdio) → 통신 채널; the verb \"wire\" (to connect) → 연결하다. Never the transliteration 와이어. Native review (#3732).",
+      "avoid": ["와이어"]
+    },
+    {
+      "source": "server-initiated request",
+      "target": "서버가 시작하는 요청",
+      "note": "A request the server sends to the client (sampling, elicitation, roots). Not 서버 시작 요청, which reads as a request to start the server, and not 서버 주도. Native review (#3732).",
+      "avoid": ["서버 시작 요청"]
+    },
+    {
+      "source": "Completions (the MCP primitive)",
+      "target": "자동 완성",
+      "note": "The argument-completion primitive and the title of its page; the same rendering in link text pointing to that page. `completion/complete` stays code. Native review (#3732)."
+    },
+    {
+      "source": "completion (what a model generates)",
+      "target": "completion",
+      "note": "The text an LLM produces (\"sampling asks the client's model for a completion\"). Keep the English word in Korean prose, as with lifespan. Not 완성, 완성 결과 or 컴플리션; the Completions primitive is the separate entry above (자동 완성). Native review (#3732).",
+      "avoid": ["컴플리션", "완성 결과"]
+    },
+    {
+      "source": "provider",
+      "target": "provider",
+      "note": "OAuth and identity providers: keep the English word in Korean prose (OAuth provider, identity provider), as with lifespan. Not 프로바이더 or 공급자. Native review (#3732).",
+      "avoid": ["프로바이더", "공급자"]
+    },
+    {
+      "source": "argument",
+      "target": "인자",
+      "note": "A function, tool or prompt argument; matches the Korean glossary of the Python documentation (docs.python.org/ko/3/glossary.html). Not 인수. Native review (#3732).",
+      "avoid": ["인수"]
+    },
+    {
+      "source": "parameter",
+      "target": "매개변수",
+      "note": "A function or tool parameter; matches the Korean glossary of the Python documentation. Not 파라미터. Native review (#3732).",
+      "avoid": ["파라미터"]
+    },
+    {
+      "source": "annotation",
+      "target": "어노테이션",
+      "note": "Type annotations and tool annotations; matches the Korean glossary of the Python documentation. Not 애너테이션. Native review (#3732).",
+      "avoid": ["애너테이션"]
+    },
+    {
+      "source": "docstring",
+      "target": "독스트링",
+      "note": "Matches the Korean glossary of the Python documentation; not left in Latin script in prose. Native review (#3732)."
+    },
+    {
+      "source": "spec (specification)",
+      "target": "사양",
+      "note": "The MCP specification; one rendering everywhere, not 명세 on some pages. Native review (#3732).",
+      "avoid": ["명세"]
+    },
     {
       "source": "Get started",
       "target": "시작하기",
diff --git a/i18n/ko/instructions.md b/i18n/ko/instructions.md
index 92f41c472d..1c7536a457 100644
--- a/i18n/ko/instructions.md
+++ b/i18n/ko/instructions.md
@@ -15,17 +15,27 @@ register for the whole page.
   -ㅂ니다: "The SDK does the rest." → SDK가 나머지를 처리합니다.
 - Short imperatives (steps, instructions, calls to action) use -세요:
   "Create a file `server.py`" → `server.py` 파일을 만드세요. Never -십시오, never
-  the bare 해요체 (-어요 / -예요 / -해요), and never plain-style -다 endings.
+  -ㅂ시다 ("Let's change it" → 바꿔 보세요, not 바꿔 봅시다), never the bare
+  해요체 (-어요 / -예요 / -해요), and never plain-style -다 endings.
 - Headings are noun phrases where the English heading is a noun phrase
   ("Installation" → 설치). An English heading phrased as a sentence or a
   question becomes a noun phrase too: "What's new in v2" → v2에서 달라진 점.
-  Do not write -나요? or -습니까? headings.
+  A heading never ends in a verb ending of any kind: not -나요? or -습니까?,
+  not -ㄹ까 or -는가, and not a -습니다 sentence. "It costs nothing until you
+  want it" → 필요할 때까지 비용 없음; "Which one to raise" → 발생시킬 예외 고르기.
 - Never address the reader with 당신, 여러분 or 우리. Korean drops the
   subject: "you can pass a URL" → URL을 전달할 수 있습니다. Where a subject is
   unavoidable, name the role — 클라이언트, 서버, 사용자 — never a pronoun.
   "Your server" is 서버 or, when the contrast matters, 작성한 서버.
 - One page, one register. Mixing -습니다 with -어요, or -세요 with -십시오, is
   wrong even when each sentence is correct on its own.
+- The shared rules keep the strength of a requirement; in Korean each level
+  has a fixed ending: must → -해야 합니다, must not → -해서는 안 됩니다,
+  should → -하는 것이 좋습니다, should not → -하지 않는 것이 좋습니다,
+  may → -할 수 있습니다. "Should not" is advice: "New code should not be
+  built on these" → 새 코드는 이 기능을 기반으로 하지 않는 것이 좋습니다,
+  never -해서는 안 됩니다, -면 안 됩니다 or -지 않아야 합니다, which read as
+  must not.
 
 ## 2. Voice
 
@@ -105,9 +115,12 @@ Translate the information, not the joke.
   3개, 30초, 8000번 포트, 5MB. Version numbers and the protocol's date-shaped
   revision strings are identifiers and are copied byte-for-byte (they are in
   the glossary's keep list). A calendar date written out in prose, if any,
-  becomes 2026년 7월 28일.
+  becomes 2026년 7월 28일. When a revision string marks the point at which
+  something changes, add 사양부터: "deprecated at `2026-07-28`" →
+  `2026-07-28` 사양부터 지원 중단 예정입니다. Never `2026-07-28`에서, which reads
+  as a calendar date.
 - Parenthetical originals use ASCII parentheses with no space before them:
-  엘리시테이션(elicitation).
+  사용자 입력 요청(elicitation).
 
 ## 5. Terminology pointer
 
@@ -130,14 +143,18 @@ glossary does not pin:
   line, a log message, a UI label) stays exactly as the code emits it,
   usually English.
 - 한글(English) 병기: the glossary marks a few MCP-specific nouns for a
-  parenthetical original on first mention only — 엘리시테이션(elicitation) once,
-  then 엘리시테이션. Class names never get a Hangul gloss.
+  parenthetical original on first mention only — 사용자 입력 요청(elicitation)
+  once, then 사용자 입력 요청. Class names never get a Hangul gloss.
 - One term, one rendering, throughout the page. Do not alternate between
   객체 and 오브젝트, or between 컨텍스트 and 맥락, for the same source term.
 - Abbreviations stay Latin and lose the English plural "s": "the APIs" → API.
 
 ## 6. Provisional note
 
-Every decision in this file is provisional pending review by native Korean
-speakers. To propose a change, edit this file (or `glossary.json`) in a pull
-request — never edit the generated pages under `pages/`.
+A native Korean speaker compared 45 of the 52 generated pages with the
+English (#3732; `advanced/` was not covered). That review added the
+requirement-strength, heading and -ㅂ시다 rules in §1 and the 사양부터 rule in
+§4, and the glossary entries it changed or added are marked "Native review
+(#3732)". Every other decision is still provisional pending native review.
+To propose a change, edit this file (or `glossary.json`) in a pull request
+— never edit the generated pages under `pages/`.