Skip to content

Commit e8d97ff

Browse files
Jeonghyeockclaude
andcommitted
docs(ko): apply native-speaker review to the Korean glossary and instructions
- 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>
1 parent 2af9e30 commit e8d97ff

2 files changed

Lines changed: 97 additions & 14 deletions

File tree

‎i18n/ko/glossary.json‎

Lines changed: 71 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -89,13 +89,14 @@
8989
},
9090
{
9191
"source": "elicitation",
92-
"target": "엘리시테이션",
93-
"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."
92+
"target": "사용자 입력 요청",
93+
"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).",
94+
"avoid": ["엘리시테이션", "요청 요청"]
9495
},
9596
{
9697
"source": "capability",
97-
"target": "기능",
98-
"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."
98+
"target": "지원 기능",
99+
"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)."
99100
},
100101
{
101102
"source": "transport",
@@ -169,7 +170,8 @@
169170
{
170171
"source": "deprecated",
171172
"target": "지원 중단 예정",
172-
"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."
173+
"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).",
174+
"avoid": ["지원 중단 경고"]
173175
},
174176
{
175177
"source": "round-trip",
@@ -181,6 +183,70 @@
181183
"target": "lifespan",
182184
"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\" (생명 주기)."
183185
},
186+
{
187+
"source": "era (2025-era, 2026-era, handshake era, modern era)",
188+
"target": "프로토콜 버전",
189+
"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).",
190+
"avoid": ["년대"]
191+
},
192+
{
193+
"source": "wire (on the wire, wire name, wire format)",
194+
"target": "실제로 주고받는 메시지",
195+
"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).",
196+
"avoid": ["와이어"]
197+
},
198+
{
199+
"source": "server-initiated request",
200+
"target": "서버가 시작하는 요청",
201+
"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).",
202+
"avoid": ["서버 시작 요청"]
203+
},
204+
{
205+
"source": "Completions (the MCP primitive)",
206+
"target": "자동 완성",
207+
"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)."
208+
},
209+
{
210+
"source": "completion (what a model generates)",
211+
"target": "completion",
212+
"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).",
213+
"avoid": ["컴플리션", "완성 결과"]
214+
},
215+
{
216+
"source": "provider",
217+
"target": "provider",
218+
"note": "OAuth and identity providers: keep the English word in Korean prose (OAuth provider, identity provider), as with lifespan. Not 프로바이더 or 공급자. Native review (#3732).",
219+
"avoid": ["프로바이더", "공급자"]
220+
},
221+
{
222+
"source": "argument",
223+
"target": "인자",
224+
"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).",
225+
"avoid": ["인수"]
226+
},
227+
{
228+
"source": "parameter",
229+
"target": "매개변수",
230+
"note": "A function or tool parameter; matches the Korean glossary of the Python documentation. Not 파라미터. Native review (#3732).",
231+
"avoid": ["파라미터"]
232+
},
233+
{
234+
"source": "annotation",
235+
"target": "어노테이션",
236+
"note": "Type annotations and tool annotations; matches the Korean glossary of the Python documentation. Not 애너테이션. Native review (#3732).",
237+
"avoid": ["애너테이션"]
238+
},
239+
{
240+
"source": "docstring",
241+
"target": "독스트링",
242+
"note": "Matches the Korean glossary of the Python documentation; not left in Latin script in prose. Native review (#3732)."
243+
},
244+
{
245+
"source": "spec (specification)",
246+
"target": "사양",
247+
"note": "The MCP specification; one rendering everywhere, not 명세 on some pages. Native review (#3732).",
248+
"avoid": ["명세"]
249+
},
184250
{
185251
"source": "Get started",
186252
"target": "시작하기",

‎i18n/ko/instructions.md‎

Lines changed: 26 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -15,17 +15,27 @@ register for the whole page.
1515
-ㅂ니다: "The SDK does the rest." → SDK가 나머지를 처리합니다.
1616
- Short imperatives (steps, instructions, calls to action) use -세요:
1717
"Create a file `server.py`" → `server.py` 파일을 만드세요. Never -십시오, never
18-
the bare 해요체 (-어요 / -예요 / -해요), and never plain-style -다 endings.
18+
-ㅂ시다 ("Let's change it" → 바꿔 보세요, not 바꿔 봅시다), never the bare
19+
해요체 (-어요 / -예요 / -해요), and never plain-style -다 endings.
1920
- Headings are noun phrases where the English heading is a noun phrase
2021
("Installation" → 설치). An English heading phrased as a sentence or a
2122
question becomes a noun phrase too: "What's new in v2" → v2에서 달라진 점.
22-
Do not write -나요? or -습니까? headings.
23+
A heading never ends in a verb ending of any kind: not -나요? or -습니까?,
24+
not -ㄹ까 or -는가, and not a -습니다 sentence. "It costs nothing until you
25+
want it" → 필요할 때까지 비용 없음; "Which one to raise" → 발생시킬 예외 고르기.
2326
- Never address the reader with 당신, 여러분 or 우리. Korean drops the
2427
subject: "you can pass a URL" → URL을 전달할 수 있습니다. Where a subject is
2528
unavoidable, name the role — 클라이언트, 서버, 사용자 — never a pronoun.
2629
"Your server" is 서버 or, when the contrast matters, 작성한 서버.
2730
- One page, one register. Mixing -습니다 with -어요, or -세요 with -십시오, is
2831
wrong even when each sentence is correct on its own.
32+
- The shared rules keep the strength of a requirement; in Korean each level
33+
has a fixed ending: must → -해야 합니다, must not → -해서는 안 됩니다,
34+
should → -하는 것이 좋습니다, should not → -하지 않는 것이 좋습니다,
35+
may → -할 수 있습니다. "Should not" is advice: "New code should not be
36+
built on these" → 새 코드는 이 기능을 기반으로 하지 않는 것이 좋습니다,
37+
never -해서는 안 됩니다, -면 안 됩니다 or -지 않아야 합니다, which read as
38+
must not.
2939

3040
## 2. Voice
3141

@@ -105,9 +115,12 @@ Translate the information, not the joke.
105115
3개, 30초, 8000번 포트, 5MB. Version numbers and the protocol's date-shaped
106116
revision strings are identifiers and are copied byte-for-byte (they are in
107117
the glossary's keep list). A calendar date written out in prose, if any,
108-
becomes 2026년 7월 28일.
118+
becomes 2026년 7월 28일. When a revision string marks the point at which
119+
something changes, add 사양부터: "deprecated at `2026-07-28`" →
120+
`2026-07-28` 사양부터 지원 중단 예정입니다. Never `2026-07-28`에서, which reads
121+
as a calendar date.
109122
- Parenthetical originals use ASCII parentheses with no space before them:
110-
엘리시테이션(elicitation).
123+
사용자 입력 요청(elicitation).
111124

112125
## 5. Terminology pointer
113126

@@ -130,14 +143,18 @@ glossary does not pin:
130143
line, a log message, a UI label) stays exactly as the code emits it,
131144
usually English.
132145
- 한글(English) 병기: the glossary marks a few MCP-specific nouns for a
133-
parenthetical original on first mention only — 엘리시테이션(elicitation) once,
134-
then 엘리시테이션. Class names never get a Hangul gloss.
146+
parenthetical original on first mention only — 사용자 입력 요청(elicitation)
147+
once, then 사용자 입력 요청. Class names never get a Hangul gloss.
135148
- One term, one rendering, throughout the page. Do not alternate between
136149
객체 and 오브젝트, or between 컨텍스트 and 맥락, for the same source term.
137150
- Abbreviations stay Latin and lose the English plural "s": "the APIs" → API.
138151

139152
## 6. Provisional note
140153

141-
Every decision in this file is provisional pending review by native Korean
142-
speakers. To propose a change, edit this file (or `glossary.json`) in a pull
143-
request — never edit the generated pages under `pages/`.
154+
A native Korean speaker compared 45 of the 52 generated pages with the
155+
English (#3732; `advanced/` was not covered). That review added the
156+
requirement-strength, heading and -ㅂ시다 rules in §1 and the 사양부터 rule in
157+
§4, and the glossary entries it changed or added are marked "Native review
158+
(#3732)". Every other decision is still provisional pending native review.
159+
To propose a change, edit this file (or `glossary.json`) in a pull request
160+
— never edit the generated pages under `pages/`.

0 commit comments

Comments
 (0)