From 1e3f112d2689be96d617d1b62e1c22ee9b2eeeca Mon Sep 17 00:00:00 2001
From: Yurii Motov <yurii.motov.monte@gmail.com>
Date: Tue, 3 Feb 2026 15:40:30 +0100
Subject: [PATCH] Add banner to translated pages

---
 docs/en/mkdocs.yml            |  1 +
 docs/en/translation-banner.md |  7 +++++++
 docs/ru/translation-banner.md |  7 +++++++
 scripts/mkdocs_hooks.py       | 26 +++++++++++++++++++++++++-
 4 files changed, 40 insertions(+), 1 deletion(-)
 create mode 100644 docs/en/translation-banner.md
 create mode 100644 docs/ru/translation-banner.md

diff --git a/docs/en/mkdocs.yml b/docs/en/mkdocs.yml
index 1c2954619..d90c2ece6 100644
--- a/docs/en/mkdocs.yml
+++ b/docs/en/mkdocs.yml
@@ -294,6 +294,7 @@ markdown_extensions:
     - info
     - check
   pymdownx.blocks.details: null
+  pymdownx.details: null
   pymdownx.blocks.tab:
     alternate_style: true
   mdx_include: null
diff --git a/docs/en/translation-banner.md b/docs/en/translation-banner.md
new file mode 100644
index 000000000..fb99cce5d
--- /dev/null
+++ b/docs/en/translation-banner.md
@@ -0,0 +1,7 @@
+??? note "🌐 Translation by AI and humans"
+
+    This translation was made by AI guided by humans. 🤝
+
+    It could have mistakes of misunderstanding the original meaning, or looking unnatural, etc. 🤖
+
+    You can improve this translation by [helping us guide the AI LLM better](https://fastapi.tiangolo.com/contributing/#translations).
diff --git a/docs/ru/translation-banner.md b/docs/ru/translation-banner.md
new file mode 100644
index 000000000..f96fc8b20
--- /dev/null
+++ b/docs/ru/translation-banner.md
@@ -0,0 +1,7 @@
+??? note "🌐 Перевод выполнен с помощью ИИ и людей"
+
+    Этот перевод был сделан ИИ под руководством людей. 🤝
+
+    В нем могут быть ошибки из-за неправильного понимания оригинального смысла или неестественности и т. д. 🤖
+
+    Вы можете улучшить этот перевод, [помогая нам лучше направлять ИИ LLM](https://fastapi.tiangolo.com/contributing/#translations).
diff --git a/scripts/mkdocs_hooks.py b/scripts/mkdocs_hooks.py
index 4b781270a..a88c229e5 100644
--- a/scripts/mkdocs_hooks.py
+++ b/scripts/mkdocs_hooks.py
@@ -26,6 +26,17 @@ def get_missing_translation_content(docs_dir: str) -> str:
     return missing_translation_path.read_text(encoding="utf-8")
 
 
+@lru_cache
+def get_translation_banner_content(docs_dir: str) -> str:
+    docs_dir_path = Path(docs_dir)
+    translation_banner_path = docs_dir_path.parent / "translation-banner.md"
+    if not translation_banner_path.is_file():
+        translation_banner_path = (
+            docs_dir_path.parent.parent / "en" / "translation-banner.md"
+        )
+    return translation_banner_path.read_text(encoding="utf-8")
+
+
 @lru_cache
 def get_mkdocs_material_langs() -> list[str]:
     material_path = Path(material.__file__).parent
@@ -151,4 +162,17 @@ def on_page_markdown(
         if markdown.startswith("#"):
             header, _, body = markdown.partition("\n\n")
         return f"{header}\n\n{missing_translation_content}\n\n{body}"
-    return markdown
+
+    docs_dir_path = Path(config.docs_dir)
+    en_docs_dir_path = docs_dir_path.parent.parent / "en/docs"
+
+    if docs_dir_path == en_docs_dir_path:
+        return markdown
+
+    # For translated pages add translation banner
+    translation_banner_content = get_translation_banner_content(config.docs_dir)
+    header = ""
+    body = markdown
+    if markdown.startswith("#"):
+        header, _, body = markdown.partition("\n\n")
+    return f"{header}\n\n{translation_banner_content}\n\n{body}"