Korean (ko) docs: native-speaker review notes for glossary.json and instructions.md · Issue #3732 · modelcontextprotocol/python-sdk · GitHub
Skip to content

Korean (ko) docs: native-speaker review notes for glossary.json and instructions.md #3732

Open

Description

@Jeonghyeock

Every term in i18n/ko/glossary.json is marked "provisional pending native review", and #3280 mentions that only Portuguese had a reviewer lined up. I'm a native Korean speaker and compared the generated Korean pages with the English source. Below are only the problems that come from the inputs (glossary.json / instructions.md), not one-off sentences. Paths are under i18n/ko/pages/, and line numbers refer to those Korean files on main at 2af9e30.

AI disclosure: I used Claude Code to compare 45 of the 52 Korean pages with the English source and collect examples. I read and confirmed every example below myself, and the proposed renderings are my choices. advanced/ was not reviewed.

1. capability → 기능 collides with "feature"

The glossary note already anticipated this collision; the pages confirm it.

  • handlers/dependencies.md:148 "선언되지 않은 기능은 …" (capability) and :150 "독립적인 샘플링 및 루트 기능은" (features): two lines apart, and the English contrast is lost.
  • client/callbacks.md:73 ## A callback is a capability → ## 콜백이 곧 기능, which reads as "a callback is a feature".
  • whats-new.md:192: the English italicizes capabilities to separate them from features, but the next paragraph uses 기능 for features too.

Proposal: render capability (what a side declares it supports) as 지원 기능, and keep 기능 for feature. Example: ## 콜백 등록이 곧 지원 기능 선언.

2. era has no entry, and "2025년대" is wrong

  • handlers/sampling-and-roots.md:41 "On 2025-era connections" → "2025년대 연결에서". -년대 means a decade (as in 2020년대), so "2025년대" / "2026년대" is not a valid expression. It occurs 4 times (also servers/media.md:123, client/session-groups.md:72).
  • Elsewhere the same word is 시대 (protocol-versions.md), 세대 (handlers/multi-round-trip.md) or 시절 (deprecated.md).

An era is a group of protocol revisions, not a period of time, so any time word misleads in Korean. Proposal: no noun for era; name the versions instead.

  • 2025-era → 2025-11-25 이하 버전
  • 2026-era → 2026-07-28
  • pre-2026 → 2026-07-28 이전 버전
  • a generic "protocol era" → 프로토콜 버전
  • never -년대, -년, 시대, 시절 or 세대

3. Revision strings read as calendar dates

  • "deprecated at 2026-07-28" became "2026-07-28에서 지원 중단 예정" (handlers/sampling-and-roots.md:49, handlers/dependencies.md:150). This reads as "support ends on July 28, 2026", while the English means "deprecated as of the 2026-07-28 revision".
  • The term is also shortened to 지원 중단 ("호출하면 지원 중단 경고가 발생합니다", handlers/sampling-and-roots.md:43), which reads as "already unsupported".

Proposal:

  • In instructions.md §4, when a revision string is the point in time, write 사양부터: "2026-07-28 사양부터 지원 중단 예정입니다".
  • In the deprecated note, say that "deprecation warning" is 지원 중단 예정 경고 and that the term is never shortened.

4. elicitation → 엘리시테이션 is opaque

The glossary calls this the least settled term. The transliteration carries no meaning for Korean readers, and the candidate 유도 reads as "nudging the user".

Proposal: 사용자 입력 요청, written 사용자 입력 요청(elicitation) at first mention.

  • form elicitation → 폼 입력 요청
  • URL-mode elicitation → URL 모드 입력 요청
  • push elicitation → 푸시 입력 요청
  • code such as ctx.elicit() and elicitation/create stays as is

5. Terms with no entry, rendered differently across pages

Counts are approximate (grep over i18n/ko/pages).

English Renderings found Proposal
argument 인자 (94) / 인수 (48) 인자
annotation 어노테이션 (38) / 애너테이션 (5) 어노테이션
docstring 독스트링 / "docstring" left in Latin (servers/prompts.md) 독스트링
parameter 매개변수 / 파라미터 (handlers/elicitation.md) 매개변수
spec 사양 (45) / 명세 (8) 사양
server-initiated request 서버 시작 요청 / 서버가 시작하는 요청 / 서버 주도 서버가 시작하는 요청 ("서버 시작 요청" reads as "a request to start the server")
provider (OAuth, identity) 프로바이더 (20) / 공급자 (16) / 아이덴티티 공급자 keep "provider" in Latin script
completion (an LLM's output) 완성, 완성 결과, 컴플리션 keep "completion" in Latin script
Completions (the primitive) 자동 완성 / 완성 (servers/index.md:21) 자동 완성

The argument, parameter, annotation and docstring proposals follow the Python documentation's own Korean glossary (https://docs.python.org/ko/3/glossary.html).

"wire" (와이어 ×35, 전송 구간, 통신) needs a rule by context rather than one word:

  • on / across the wire → 실제로 주고받는 메시지에서
  • wire name, key or format → 프로토콜상 이름 / 키 / 형식
  • the wire as the channel (stdout under stdio) → 통신 채널
  • the verb "wire" → 연결하다 (already right)
  • never 와이어

6. Gaps in instructions.md

  • Requirement strength. There is no mapping, and "should not" came out at must-not strength ("-해서는 안 됩니다", "-면 안 되는지", "-지 않아야 합니다") in deprecated.md:155, client/identity-assertion.md:119 and handlers/sampling-and-roots.md:13. Proposal: must → -해야 합니다, should → -하는 것이 좋습니다, should not → -하지 않는 것이 좋습니다, may → -할 수 있습니다.
  • Headings. §1 bans -나요? / -습니까? headings, but other sentence endings appear: "루트: 어디에 두어야 할까" (handlers/sampling-and-roots.md:28), "## 무엇을 발생시킬 것인가" (servers/handling-errors.md:78), "## 원할 때까지는 비용이 들지 않습니다" (run/opentelemetry.md:38). Proposal: say that a heading never ends in a verb ending.
  • -ㅂ시다. It appears 3 times in servers/handling-errors.md (e.g. "바꿔 봅시다."). §1 could list it next to -십시오.

If this is useful and you assign me, I can open a PR with the glossary.json / instructions.md changes. I also have a list of one-off mistranslations (e.g. "crash" → 충돌 in client/index.md:142) that I can file separately.

Activity

  1. added
    documentationImprovements or additions to documentation
    v2Affects the v2 line (2.x on main)
    on Oct 21, 2026
  2. maxisbey commented on Oct 21, 2026

    @maxisbey
    Contributor

    Thank you for the writeup @Jeonghyeock ! I have assigned you the issue, so feel free to make a PR

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationv2Affects the v2 line (2.x on main)

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions