modelcontextprotocol
diff --git a/.gitattributes b/.gitattributes
@@ -1,2 +1,5 @@
 # Generated
 uv.lock  linguist-generated=true
+i18n/languages/*/pages/**  linguist-generated=true
+i18n/languages/*/state.json  linguist-generated=true
+i18n/languages/*/nav.yml  linguist-generated=true
diff --git a/.github/ISSUE_TEMPLATE/translation.yaml b/.github/ISSUE_TEMPLATE/translation.yaml
@@ -0,0 +1,57 @@
+name: 🌐 Translation problem
+description: Report a wrong, awkward, or misleading passage in a translated docs page
+labels: ["translation"]
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        The translated docs are machine-generated from the English pages; https://py.sdk.modelcontextprotocol.io/translations/ explains how.
+        Fixes never go into the translated text directly. They go into that language's glossary or style guide under `i18n/languages/`, so you can also open a PR there instead of an issue.
+
+  - type: dropdown
+    id: language
+    attributes:
+      label: Language
+      options:
+        - Simplified Chinese (zh-CN)
+        - Japanese (ja)
+        - Korean (ko)
+        - Brazilian Portuguese (pt-BR)
+    validations:
+      required: true
+
+  - type: input
+    id: page
+    attributes:
+      label: Page URL
+      description: The translated page where you found the problem.
+      placeholder: https://py.sdk.modelcontextprotocol.io/ja/servers/tools/
+    validations:
+      required: true
+
+  - type: textarea
+    id: passage
+    attributes:
+      label: The passage
+      description: Quote the translated text that's wrong, and the English it corresponds to if you have it.
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What's wrong, or how it should read
+      description: A wrong term, awkward phrasing, meaning that drifted from the English, tone that's off. If you know the better rendering, give it.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: native-speaker
+    attributes:
+      label: Are you a native or fluent speaker of this language?
+      options:
+        - "Yes"
+        - "No"
+    validations:
+      required: true
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
@@ -12,6 +12,8 @@ on:
       # docs pages include their code blocks from these files via `--8<--`, so a
       # change here changes the rendered site even when no .md file moves.
       - docs_src/**
+      # translated pages, banners and the language registry ship in the site
+      - i18n/**
       - mkdocs.yml
       - src/mcp/**
       - src/mcp-types/**

diff --git a/.github/workflows/docs-preview.yml b/.github/workflows/docs-preview.yml
@@ -21,6 +21,7 @@ on:
     paths:
       - docs/**
       - docs_src/**
+      - i18n/**
       - mkdocs.yml
       - scripts/docs/**
       - pyproject.toml
@@ -137,7 +138,16 @@ jobs:
       # /preview-docs, still build with MkDocs. Both arms must write the site
       # to site/. Keep the detection in sync with build_site() in
       # scripts/build-docs.sh.
-      - run: |
+      #
+      # DOCS_SITE_URL is the preview's Cloudflare branch-alias host (deploy
+      # publishes to `--branch=pr-<N>`, served at pr-<N>.<project>.pages.dev),
+      # so the absolute links the build bakes point at the preview instead of
+      # production; empty when no Pages project is configured, which makes
+      # build.sh fall back to the production site_url.
+      - env:
+          DOCS_SITE_URL: >-
+            ${{ vars.CLOUDFLARE_PAGES_PROJECT && format('https://pr-{0}.{1}.pages.dev', needs.authorize.outputs.pr_number, vars.CLOUDFLARE_PAGES_PROJECT) || '' }}
+        run: |
           if [ -f scripts/docs/build.sh ]; then
             bash scripts/docs/build.sh
           else

diff --git a/.github/workflows/shared.yml b/.github/workflows/shared.yml
@@ -139,7 +139,9 @@ jobs:
       - name: Check README snippets are up to date
         run: uv run --frozen scripts/update_readme_snippets.py --check
 
-  # `scripts/docs/build.sh` is the whole gauntlet: build_config.py fails on
+  # `scripts/docs/build.sh` is the whole gauntlet: it opens with the fast,
+  # no-network gates (a prose heading without a pinned anchor, an invalid
+  # translation config or committed translation), then build_config.py fails on
   # nav entries without a page and pages without a nav entry, `zensical build
   # --strict` fails on broken .md links, `pymdownx.snippets: check_paths:
   # true` fails on a deleted `docs_src/` include, and the post-build steps

diff --git a/.gitignore b/.gitignore
@@ -144,10 +144,15 @@ venv.bak/
 # documentation
 /site
 /.worktrees/
-# Generated at build time by scripts/docs/ (the API reference tree and the
-# concrete Zensical config spliced from mkdocs.yml).
+# Local scratch notes are never part of the repo.
+/notes/
+# Generated at build time by scripts/docs/ (the API reference tree, the
+# concrete Zensical configs spliced from mkdocs.yml, and the staged per-language
+# docs trees).
 /docs/api/
 /mkdocs.gen.yml
+/mkdocs.*.gen.yml
+/.build/
 
 # mypy
 .mypy_cache/

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -11,6 +11,9 @@ repos:
     hooks:
       - id: prettier
         types_or: [yaml, json5]
+        # The translation tool writes each language's state.json and nav.yml
+        # in its own stable format; a formatter rewrite would fight the generator.
+        exclude: ^i18n/languages/[^/]+/(state\.json|nav\.yml)$
 
   - repo: https://github.com/igorshubovych/markdownlint-cli
     rev: v0.45.0
@@ -25,6 +28,10 @@ repos:
             "/tool/markdown/lint",
           ]
         types: [markdown]
+        # Machine-translated pages are generated artefacts: corrections flow
+        # through i18n/languages/<code>/{instructions.md,glossary.json}, never
+        # through hand or linter edits to the pages themselves.
+        exclude: ^i18n/languages/[^/]+/pages/
 
   - repo: local
     hooks:

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -126,6 +126,10 @@ pre-commit run --all-files
 - Add type hints to all functions
 - Include docstrings for public APIs
 
+## Documentation and Translations
+
+Documentation contributions are English only: the pages under `docs/` are the source of truth, and the translated documentation sites are generated from them, guided by the per-language style guides and glossaries under `i18n/languages/<lang>/`. Never edit the generated pages under `i18n/languages/<lang>/pages/`—the next translation run overwrites them. To fix a translation, change that language's `instructions.md` or `glossary.json` (or the English page, if that's where the problem is), and the fix carries into every future run. See [`i18n/README.md`](i18n/README.md) for the details.
+
 ## Pull Requests
 
 By the time you open a PR, the "what" and "why" should already be settled in an issue. This keeps reviews focused on implementation.

diff --git a/docs/advanced/apps.md b/docs/advanced/apps.md
@@ -1,4 +1,4 @@
-# MCP Apps
+# MCP Apps {#mcp-apps}
 
 An **MCP App** is a tool with a face: alongside its data, the tool points at an HTML
 document the host renders as an interactive surface.
@@ -18,7 +18,7 @@ The SDK ships this as the built-in `Apps` extension (`io.modelcontextprotocol/ui
 If [Extensions](extensions.md) are new to you, skim that page first. One minute,
 then come back.
 
-## A clock with a face
+## A clock with a face {#a-clock-with-a-face}
 
 ```python title="server.py" hl_lines="19 22 30 32"
 --8<-- "docs_src/apps/tutorial001.py"
@@ -41,7 +41,7 @@ apps, use the official [`@modelcontextprotocol/ext-apps`](https://github.com/mod
 browser SDK inside your HTML. It gives you `ontoolresult`, `callServerTool`,
 `getHostContext`, and `onhostcontextchanged` instead of raw message events.
 
-## Graceful degradation
+## Graceful degradation {#graceful-degradation}
 
 Not every client renders apps. The spec is blunt about what that means for you:
 
@@ -66,7 +66,7 @@ client half of the negotiation, and the rich answer comes back.
     fallback text is useless, the tool is useless to every text-only client and to
     the model itself. Write the sentence.
 
-## Locking the iframe down
+## Locking the iframe down {#locking-the-iframe-down}
 
 The resource side carries the security metadata: what the iframe may load, which
 browser permissions it wants, how it would like to be framed:
@@ -102,7 +102,7 @@ may refuse. Feature-detect in your JS rather than assuming a grant.
     metadata has no slot for them, and hosts ignore them there. The SDK makes the
     mistake unrepresentable: `@apps.tool()` simply has no `csp` parameter.
 
-### Visibility
+### Visibility {#visibility}
 
 `visibility=["app"]` on a tool says "this exists for the iframe, not the model":
 
@@ -113,7 +113,7 @@ may refuse. Feature-detect in your JS rather than assuming a grant.
 Filtering is the **host's** job. Your server lists app-only tools in `tools/list`
 like any other; the host hides them from the model. Don't filter server-side.
 
-## The rules the SDK enforces
+## The rules the SDK enforces {#the-rules-the-sdk-enforces}
 
 All of these fail at startup, not in production:
 
@@ -130,7 +130,7 @@ All of these fail at startup, not in production:
 Neither the TypeScript ext-apps SDK nor FastMCP catches any of these today; we'd
 rather you find out before a host does.
 
-## Beyond inline HTML
+## Beyond inline HTML {#beyond-inline-html}
 
 `add_html_resource` covers the common case: a string of HTML. For anything else,
 HTML on disk or generated content, build the resource yourself and hand it over:
@@ -149,7 +149,7 @@ under any other MIME type is one no host will render.
     `@apps.tool(resource_uri="ui://x", meta={"ui/resourceUri": "ui://x"})`.
     The nested `ui` object is the spec shape; the flat key is on its way out.
 
-## See it run
+## See it run {#see-it-run}
 
 The `apps` story in `examples/stories/` is this page as a runnable pair: a server
 with a UI-bound clock tool and a client that negotiates Apps, reads the tool's

diff --git a/docs/advanced/extensions.md b/docs/advanced/extensions.md
@@ -1,4 +1,4 @@
-# Extensions
+# Extensions {#extensions}
 
 An **extension** is an opt-in bundle of MCP behaviour behind one identifier.
 
@@ -8,7 +8,7 @@ notifications. Each side advertises under its own `capabilities.extensions`, and
 changes for anyone who didn't ask for it. That is the contract ([SEP-2133](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2133)), and
 it has one golden rule: **extensions are off by default**.
 
-## Using an extension
+## Using an extension {#using-an-extension}
 
 Pass instances at construction:
 
@@ -30,11 +30,11 @@ The capability map rides `server/discover`, which is a **2026-07-28** path. A le
 the extension. Design for that: an extension *augments* a server, it must not be the
 only way the server is usable.
 
-## Writing your own
+## Writing your own {#writing-your-own}
 
 Subclass `Extension` and override only what you need. Every method has a default.
 
-### The identifier
+### The identifier {#the-identifier}
 
 ```python
 --8<-- "docs_src/extensions/tutorial002.py"
@@ -53,7 +53,7 @@ TypeError: Stamps.identifier must be a `vendor-prefix/name` string
 Use a domain you control as the prefix. `io.modelcontextprotocol/*` is for extensions
 specified by the MCP project itself.
 
-### Contributing tools
+### Contributing tools {#contributing-tools}
 
 The smallest useful extension is one tool and a settings map:
 
@@ -75,7 +75,7 @@ And `main()` is the proof, an in-memory client straight against `mcp`:
 --8<-- "docs_src/extensions/tutorial003.py"
 ```
 
-### Serving your own methods
+### Serving your own methods {#serving-your-own-methods}
 
 An extension can register **new request methods**: its own verbs, served next to the
 spec's:
@@ -105,7 +105,7 @@ runtime:
 * An empty `protocol_versions` set raises too: a method that can never be served
   is a bug, not a configuration.
 
-### The client side
+### The client side {#the-client-side}
 
 The same file's `main()` is the whole client story, both halves of it:
 
@@ -123,7 +123,7 @@ The same file's `main()` is the whole client story, both halves of it:
   only grows first-class methods for spec verbs. `send_request` accepts any
   `Request` subclass, so the vendor request passes as-is.
 
-### Intercepting `tools/call`
+### Intercepting `tools/call` {#intercepting-toolscall}
 
 The one interceptive hook. Override `intercept_tool_call` to observe, short-circuit,
 or veto a tool call:
@@ -152,7 +152,7 @@ or veto a tool call:
 The hook wraps `tools/call` and nothing else. For every-message concerns, use
 [Middleware](middleware.md). That is what it is for.
 
-## Using a client extension
+## Using a client extension {#using-a-client-extension}
 
 A **client extension** is the same contract from the consuming side: a bundle of
 client-side behaviour behind one identifier. Pass instances to
@@ -183,7 +183,7 @@ from mcp.client import advertise
 client = Client(mcp, extensions=[advertise("com.example/search")])
 ```
 
-## Writing a client extension
+## Writing a client extension {#writing-a-client-extension}
 
 Subclass `ClientExtension` and override only what you need. Three contribution
 kinds, each with a default: `settings()`, `claims()`, and `notifications()`.
@@ -223,7 +223,7 @@ would reject. And when you want the claimed shape yourself instead of the resolv
 call `client.session.call_tool(..., allow_claimed=True)`; without that flag, a
 claimed shape reaching a session-tier caller raises `UnexpectedClaimedResult`.
 
-### Extension verbs
+### Extension verbs {#extension-verbs}
 
 An extension's own request methods need no client-side registration. A vendor request
 type subclasses `mcp.types.Request` and goes through `client.session.send_request`,
@@ -238,7 +238,7 @@ this for their verbs), the request type declares `name_param`:
 The session mirrors `params["jobId"]` into `Mcp-Name` on every send path, and a
 missing value fails loudly rather than silently omitting a required header.
 
-## What an extension cannot do
+## What an extension cannot do {#what-an-extension-cannot-do}
 
 The contribution surface is **closed** on purpose. On the server: settings, tools,
 resources, methods, one `tools/call` interceptor. On the client: settings, result

diff --git a/docs/advanced/index.md b/docs/advanced/index.md
@@ -1,4 +1,4 @@
-# Advanced
+# Advanced {#advanced}
 
 Everything an ordinary server or client needs has a topical home in the sections above.
 This section is the escape hatches you reach for when `MCPServer`'s convenience