SEP: Internationalization via Per-Request Language Negotiation#2792
Open
SamMorrowDrums wants to merge 7 commits into
Open
SEP: Internationalization via Per-Request Language Negotiation#2792SamMorrowDrums wants to merge 7 commits into
SamMorrowDrums wants to merge 7 commits into
Conversation
Adds a draft SEP proposing a transport-agnostic i18n mechanism using _meta['io.modelcontextprotocol/acceptLanguage'] on every request and _meta['io.modelcontextprotocol/contentLanguage'] on every response, mirrored into HTTP Accept-Language / Content-Language headers on the Streamable HTTP transport. Converts the docs-only approach from modelcontextprotocol#2355 into a cross-transport SEP, addressing reviewer feedback (@pja-ant, @kurtisvg) and citing SEP-2243 (header/payload mirroring) and SEP-2575 (stateless-by-default) as motivating precedents. Proposes subsuming the locale aspect of SEP-1809. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ing scope - Expand the motivation to explicitly enumerate the existing standards, libraries, infrastructure, and translation tooling MCP gets for free by adopting Accept-Language verbatim. 'No reinventing the wheel' is now the lead message of the SEP. - Add an explicit Scope subsection clarifying that only user-facing content is expected to be translated (title, description, text content, human-readable error messages, log notifications), with a normative rule that servers MAY translate any/all content in the selected locale but MUST NOT translate identifiers, tool names, URIs, schema field names, enum tokens, or any value whose semantics depend on the literal string. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…f scope The bulk of payload content from tools/call, resources/read, and prompts/get is consumed by the model rather than rendered directly to the user. Whether a server localizes it is a product decision the protocol does not speak to. The SEP now scopes negotiation to genuinely user-facing fields (titles, descriptions, UI-bound errors and notifications) and stays silent on model-facing payload translation rather than blessing it as a MAY. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Servers SHOULD translate user-facing strings (titles, descriptions, UI errors, notifications) and MAY also translate body content returned from tools/call, resources/read, and prompts/get. The latter is primarily model-facing but is often valuable to localize (verbatim quoting, legal text, dates, currency, units); the choice is the server's. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Lead the Specification with an explicit note that clients MAY send the field and servers MAY ignore it entirely, no capability advertisement required. Soften the Scope language so participating servers are not implicitly required to localize any specific set of fields; the SEP just defines the negotiation primitive and what is in scope IF a server opts in. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Draft SEP proposing a transport-agnostic i18n mechanism for MCP:
_meta['io.modelcontextprotocol/acceptLanguage']on every request — value matches the HTTPAccept-Languagefield syntax verbatim (BCP 47 ranges + quality values)._meta['io.modelcontextprotocol/contentLanguage']on every response — server echoes the language actually used.Accept-Language/Content-LanguageHTTP headers, with the same strict mismatch rule established by SEP-2243.Motivation
This SEP converts the docs-only proposal in #2355 into a cross-transport SEP, directly addressing the reviewer feedback there:
_metafirst, with HTTP headers as a mirror.Motivating precedents
initializehandshake as a place to negotiate persistent state. Per-request language preference is the natural fit.request.params._meta) — establishes_metaas the conventional carrier for per-request metadata.io.modelcontextprotocol/vendor prefix used for the field names.Relationship to SEP-1809
SEP-1809 (SCCP) proposes a
clientContextobject ontools/callthat includeslocale. This SEP proposes to subsume the language aspect of SEP-1809 in favor of the cross-cuttingacceptLanguagedefined here, leavingtimezone,currentTimestamp, anduserLocationto SEP-1809. Will coordinate with the author.Supersedes
This SEP supersedes (and proposes closing) #2355.
Status
seps/0000-i18n-language-negotiation.md; will be renamed to use the PR number and rendered docs regenerated (npm run prep) once the number is known.Checklist
seps/{PR-number}-i18n-language-negotiation.mdand regenerate docs after PR number is assignedAI Disclosure
This PR was authored with assistance from GitHub Copilot CLI.