Skip to content
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
2 changes: 2 additions & 0 deletions .github/workflows/deploy-docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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 and the language registry feed the site/<code>/ sites
- i18n/**
- mkdocs.yml
- src/mcp/**
- src/mcp-types/**
Expand Down
1 change: 1 addition & 0 deletions .github/workflows/docs-preview.yml
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ on:
paths:
- docs/**
- docs_src/**
- i18n/**
- mkdocs.yml
- scripts/docs/**
- pyproject.toml
Expand Down
7 changes: 5 additions & 2 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -144,10 +144,13 @@ 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).
# Generated at build time by scripts/docs/ (the API reference tree, the
# concrete Zensical configs spliced from mkdocs.yml, and the staged docs tree
# of each translated site).
/docs/api/
/mkdocs.gen.yml
/mkdocs.*.gen.yml
/.build/

# mypy
.mypy_cache/
Expand Down
4 changes: 4 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<lang>/`. Never edit the generated pages under `i18n/<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.
Comment thread
maxisbey marked this conversation as resolved.
Resolved

## 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.
Expand Down
18 changes: 18 additions & 0 deletions docs/js/language-switch.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
// The theme links each language-switcher entry to that language's home page.
// Point the entries at the current page on each language's site instead: every
// prose page exists at the same path on all of them. The API reference is
// English-only, so from there the entries keep pointing at the site roots.
// Instant navigation swaps the page but keeps the header, so re-run on every
// page the theme loads (`document$`) rather than once.
const base = JSON.parse(document.getElementById("__config").textContent).base;
// The site root as a directory path; `base` lacks the trailing slash on 404 pages.
const site = new URL(base.replace(/\/?$/, "/"), location).pathname;

document$.subscribe(() => {
let page = location.pathname.slice(site.length);
if (page.startsWith("api/")) page = "";
for (const entry of document.querySelectorAll(".md-select__link[hreflang]")) {
entry.dataset.site ??= entry.getAttribute("href"); // the language root the theme rendered
entry.href = entry.dataset.site + page;
}
});

Check warning on line 18 in docs/js/language-switch.js

View check run for this annotation

Claude / Claude Code Review

language-switch.js drops the URL fragment (and query) when switching languages

The language switcher rewrites each entry using only `location.pathname`, so `location.hash` (and `location.search`) are dropped — a reader deep-linked to a section like `/servers/tools/#structured-output` who switches language lands at the top of the target page. Since the translation pipeline pins identical heading ids across all language sites, appending the hash (read at click time) would keep the reader on the same section.
Comment thread
maxisbey marked this conversation as resolved.
Resolved
Comment thread
maxisbey marked this conversation as resolved.
Resolved
25 changes: 25 additions & 0 deletions docs/translations.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Translations

This documentation is written in English. To make it useful to more people, we also publish machine-translated editions of it, and this page explains what that means for you and how to help improve them.

## What's available

Translated documentation is currently a **preview** in twelve languages: Deutsch, español, français, हिन्दी, 日本語, 한국어, português (Brasil), русский язык, Türkçe, українська мова, 简体中文 and 繁體中文. Pick one from the language switcher at the top of any page. More languages may follow once these have proved themselves.

The API reference is not translated: the translated site links to the single English one.

## English is the source of truth

If a translated page and its English original disagree, the English page is correct. Every page of a translated site opens with one of three notes saying where it stands:

- **Machine translation** — the page was translated automatically and links to its English original.
- **Translation behind the English page** — the English original changed after the page was translated, so parts of it may be out of date until the translation catches up.

Check warning on line 16 in docs/translations.md

View check run for this annotation

Claude / Claude Code Review

stage/serve() pairs a stale translation positionally with reordered English, cross-wiring fences and heading anchors

A pure reorder of `##` sections on an English page makes `classify()` keep the stale translation (status='outdated', changed=[]), and `serve()` in scripts/docs/translations.py then reimposes today's English onto that stale body purely positionally — splicing each code fence under the wrong section's prose and cross-wiring the pinned heading anchors ({#install}/{#test} swapped) — instead of the documented 'served in English until refreshed' fallback. Fix: reorder the stored sections by their reco
Comment thread
maxisbey marked this conversation as resolved.
Resolved
- **Shown in English** — there is no current translation of the page, so you are reading the English text.
Comment thread
maxisbey marked this conversation as resolved.
Resolved

## How the translations are made

Translated pages are machine-generated by a tool in this repository from the English pages under `docs/`, guided by two human-written inputs per language: a style guide (register, tone, typography, how to handle jokes and idioms) and a glossary (which terms stay in English, and the required and forbidden renderings for the rest). The generated text is never edited by hand. Every improvement goes into those inputs instead, so it survives the next time the pages are regenerated.
Comment thread
maxisbey marked this conversation as resolved.
Resolved

## Reporting a translation problem

Found a wrong term, an awkward sentence, or a translation that says something the English doesn't? [Open an issue](https://github.com/modelcontextprotocol/python-sdk/issues) with the language, the page and the passage; reports from native speakers are especially valuable. If you know the fix, propose it directly as a pull request against that language's style guide (`instructions.md`) or glossary (`glossary.json`) under [`i18n/`](https://github.com/modelcontextprotocol/python-sdk/tree/main/i18n) — the correction then reaches every affected page the next time the translations are regenerated. Problems with the English text itself are fixed in the pages under `docs/`, like any other documentation change.
20 changes: 20 additions & 0 deletions i18n/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Documentation translations

The English pages under `docs/` are the source. This directory holds what steers their machine translation and the generated result; [`docs/translations.md`](../docs/translations.md) is the reader-facing explanation.

- `languages.yml` — the registry: one entry per translated site (served at `/<code>/`), the model id, and the nav pages that stay in English.
Comment thread
maxisbey marked this conversation as resolved.
Resolved
- `general-prompt.md` — translation rules shared by every language. `notices.md` — English source of the three notes staged onto the pages of a translated site.
Comment thread
maxisbey marked this conversation as resolved.
Resolved
- `<code>/instructions.md` (register, voice, typography, terminology) and `<code>/glossary.json` (`keep`: terms that stay in English; `terms`: required renderings, each with an optional `note` and banned `avoid` renderings, which are checked) — human-authored, sent with every request.
Comment thread
claude[bot] marked this conversation as resolved.
Resolved
- `<code>/pages/**` and `<code>/notices.md` — **generated**, never edited by hand: a correction goes into that language's `instructions.md` or `glossary.json` (or the English page), and the affected pages are re-run.

Check warning on line 8 in i18n/README.md

View check run for this annotation

Claude / Claude Code Review

[quality] 204 committed generated pages (ja/ko/pt/zh) carry a legacy 'inputs:' provenance key the shipped tool no longer writes

The 200 generated pages under i18n/ja/, i18n/ko/, i18n/pt/ and i18n/zh/ (49 pages + notices.md per language) still carry a legacy `inputs: <hash>` front-matter key from intermediate commit c65a026, which the shipped tool's `with_provenance()` no longer writes — the other eight languages have no such key. Nothing breaks (`read_provenance()` tolerates it), but half the committed corpus isn't reproducible by the shipped tool, and the first translate run touching each of these pages silently drops t
Comment thread
maxisbey marked this conversation as resolved.
Resolved

## The tool

```text
uv run --frozen python scripts/docs/translations.py status [--lang CODE]
uv run --frozen --group translate python scripts/docs/translations.py translate --lang CODE [--pages PATH ...]

Check warning on line 14 in i18n/README.md

View check run for this annotation

Claude / Claude Code Review

[quality] translate constructs the API client (credentials + anthropic package) even for runs that make zero model calls

`command_translate` constructs the Anthropic client (`translator = translator or anthropic_translator()`, scripts/docs/translations.py:869) before the job loop, so a run whose jobs are all no-call reassembly jobs (English sections only reordered/removed) still exits 2 with ConfigError when the `translate` dependency group or `ANTHROPIC_API_KEY` is absent — even though it would make zero API requests. Constructing the client lazily, e.g. `if any(job.open for job in jobs): translator = translator
Comment thread
maxisbey marked this conversation as resolved.
Resolved
uv run --frozen python scripts/docs/translations.py stage --lang CODE

Check warning on line 15 in i18n/README.md

View check run for this annotation

Claude / Claude Code Review

[quality] translations.py re-declares llms_txt.py's code-span and front-matter regexes instead of importing them

scripts/docs/translations.py re-declares two subtle regexes that already exist in llms_txt.py, from which it already imports: CODE_SPAN is byte-identical to llms_txt._CODE_SPAN, and FRONT_MATTER differs from llms_txt._FRONTMATTER only in the capture-group name. Consider exporting the two patterns from llms_txt (or a small shared module) and importing them, as page_url already is, so a future fix to either pattern cannot silently diverge between the translation tool and the llms.txt pipeline.
Comment thread
maxisbey marked this conversation as resolved.
Resolved
Comment thread
maxisbey marked this conversation as resolved.
Resolved
```

Check warning on line 16 in i18n/README.md

View check run for this annotation

Claude / Claude Code Review

stage() leaves a stale titles.json behind, breaking build_config.py's completeness check after a failed run

stage() deletes only the staged docs tree at the top and writes titles.json only at the very end, so a stage run that fails partway leaves the previous run's titles.json behind — and build_config.py --lang treats that file's presence as "the tree beside it is complete". A subsequent manual build_config then either dies with a confusing nav-validation error or silently builds a half-staged tree. One-line fix: unlink the titles file next to the rmtree at the top of stage() (e.g. staged_titles_file
Comment thread
maxisbey marked this conversation as resolved.
Resolved
Comment thread
claude[bot] marked this conversation as resolved.
Resolved

`status` is offline: per language it lists missing, outdated (with the sections that changed), current and removable pages (translations whose English page is gone — `git rm` them). `translate` calls the Claude API (`ANTHROPIC_API_KEY` in the environment; the registry's model, or `DOCS_TRANSLATE_MODEL` to trial another) for the missing and outdated pages, retranslating only the English sections that changed and keeping the rest byte for byte; `--pages` instead re-translates exactly the named pages from scratch, which is also how a glossary or instructions change reaches existing pages (each generated page records the English section hashes it reflects, so editing those inputs invalidates nothing). `stage` assembles the tree a language site is built from; `scripts/docs/build.sh` runs it for every language. Commit the generated pages in an ordinary pull request.

Check warning on line 18 in i18n/README.md

View check run for this annotation

Claude / Claude Code Review

Code-fence placement validated only page-wide: cross-section fence moves publish silently wrong or abort updates without repair turns

In `scripts/docs/translations.py` (anchored here because the tool's contract is documented on this line), code-fence placement is validated only page-wide: `_restore_fences` compares fence *counts* across the whole page and restores English fences positionally, while links get per-section checks. A model reply that keeps the fence count but moves a fence across a `##` section boundary is therefore (a) published silently with code under the wrong section on a fresh translation, and (b) on a parti
Comment thread
maxisbey marked this conversation as resolved.
Resolved
Comment thread
maxisbey marked this conversation as resolved.
Resolved

To add a language, add an entry to `languages.yml`, write `<code>/instructions.md` (the sections the `pt` file has) and `<code>/glossary.json`, then run `translate --lang <code>`.
Loading
Loading