docs: publish translated docs in twelve languages and the tool that maintains them (#3280)

pyproject.toml

@@ -96,13 +96,19 @@ docs = [
     # unregistered-autorefs KeyError under Zensical.
     "mkdocstrings==1.0.4",
     "mkdocstrings-python==2.0.5",
-    # scripts/docs/build_config.py and llms_txt.py read mkdocs.yml directly.
+    # scripts/docs/build_config.py, llms_txt.py and translations.py read
+    # mkdocs.yml directly; translations.py also drives Zensical's own Markdown
+    # stack (its `markdown`/`pymdownx` dependencies) to compute heading ids.
     "pyyaml>=6.0.2",
     # gen_ref_pages.py imports griffe directly. griffelib is not a typo: it is
     # griffe's successor distribution (same author) and still imports as
     # `griffe`; the old `griffe` distribution is the incompatible 1.x line.
     "griffelib==2.1.0",
 ]
+# Only `scripts/docs/translations.py translate` calls the Claude API; kept out
+# of the default groups so no other environment installs the client (or the
+# legacy httpx it depends on). See i18n/README.md.
+translate = ["anthropic>=0.121.0"]
 codegen = ["datamodel-code-generator==0.57.0"]
 
 [build-system]
@@ -160,6 +166,8 @@ include = [
     "examples/servers",
     "examples/snippets",
     "examples/clients",
+    "scripts/docs/build_config.py",
+    "scripts/docs/translations.py",
 ]
 venvPath = "."
 venv = ".venv"
@@ -175,6 +183,7 @@ executionEnvironments = [
     { root = "tests", extraPaths = [
         ".",
         "examples",
+        "scripts/docs",
     ], reportUnusedFunction = false, reportPrivateUsage = false },
     { root = "examples/stories", extraPaths = [
         "examples",
@@ -222,6 +231,8 @@ max-complexity = 24 # Default is 10
 # Generated by scripts/gen_surface_types.py: raw datamodel-codegen output (TID251 lifts the repo-wide RootModel ban for these generated validators).
 "src/mcp-types/mcp_types/_v*/__init__.py" = ["D212", "E501", "I001", "TID251", "UP007", "UP037"]
 "tests/server/mcpserver/test_func_metadata.py" = ["E501"]
+# Inline snapshots of the translation tool's output carry long status/prompt lines verbatim.
+"tests/docs/test_translations.py" = ["E501"]
 "tests/shared/test_progress_notifications.py" = ["PLW0603"]
 
 [tool.ruff.lint.pylint]
@@ -243,6 +254,8 @@ strict-no-cover = { git = "https://github.com/pydantic/strict-no-cover" }
 [tool.pytest.ini_options]
 log_cli = true
 xfail_strict = true
+# tests/docs/ imports the docs tooling, top-level modules under scripts/docs/.
+pythonpath = ["scripts/docs"]
 markers = [
     "requirement(id): links a test to the entry in tests/interaction/_requirements.py it exercises",
 ]