✅ Add LLM test file

"Unit testing" and documentation of LLM instructions in the general and in language specific prompts for the translations of the documentation.

Prompt designers add tests here, other prompt designers can test for them while creating prompts.

This was previously part of #14015.

@@ -0,0 +1,503 @@
+# LLM-Testdatei { #llm-test-file }
+
+[NAME_REDACTED] testet, ob das LLM, das die Dokumentation übersetzt, den `general_prompt` in `scripts/translate.py` und den sprachspezifischen Prompt in `docs/{language code}/llm-prompt.md` versteht. Der sprachspezifische Prompt wird an `general_prompt` angehängt.
+
+Hier hinzugefügte Tests werden von allen Erstellern sprachspezifischer Prompts gesehen.
+
+So verwenden:
+
+* Einen sprachspezifischen Prompt haben – `docs/{language code}/llm-prompt.md`.
+* Eine frische Übersetzung dieses Dokuments in die gewünschte Zielsprache durchführen (siehe z. B. das Kommando `translate-page` der `translate.py`). Dadurch wird die Übersetzung unter `docs/{language code}/docs/_llm-test.md` erstellt.
+* Prüfen Sie, ob in der Übersetzung alles in Ordnung ist.
+* [NAME_REDACTED] bei [NAME_REDACTED] sprachsspezifischen Prompt, den allgemeinen Prompt oder das englische Dokument.
+* [NAME_REDACTED] anschließend manuell die verbleibenden Probleme in der Übersetzung, sodass es eine gute Übersetzung ist.
+* Übersetzen Sie erneut, nachdem die gute Übersetzung vorliegt. Das ideale Ergebnis wäre, dass das LLM an der Übersetzung keine Änderungen mehr vornimmt. Das bedeutet, dass der allgemeine Prompt und Ihr sprachsspezifischer Prompt so gut sind, wie sie sein können (Es wird manchmal ein paar scheinbar zufällige Änderungen machen, der Grund ist, dass LLMs keine deterministischen Algorithmen sind).
+
+[NAME_REDACTED]:
+
+## Codeschnipsel { #code-snippets}
+
+//// tab | Test
+
+Dies ist ein Codeschnipsel: `foo`. Und dies ist ein weiteres Codeschnipsel: `bar`. Und noch eins: `baz quux`.
+
+////
+
+//// tab | Info
+
+[NAME_REDACTED] von Codeschnipseln sollte unverändert bleiben.
+
+[NAME_REDACTED] `### Content of code snippets` im allgemeinen Prompt in `scripts/translate.py`.
+
+////
+
+## Anführungszeichen { #quotes }
+
+//// tab | Test
+
+Gestern schrieb mein Freund: „Wenn man unkorrekt korrekt schreibt, hat man es unkorrekt geschrieben“. Worauf ich antwortete: „Korrekt, aber ‚unkorrekt‘ ist unkorrekterweise nicht ‚„unkorrekt“‘“.
+
+/// note | Hinweis
+
+Das LLM wird dies wahrscheinlich falsch übersetzen. Interessant ist nur, ob es die korrigierte Übersetzung bei einer erneuten Übersetzung beibehält.
+
+///
+
+////
+
+//// tab | Info
+
+[NAME_REDACTED] kann entscheiden, ob neutrale Anführungszeichen in typografische Anführungszeichen umgewandelt werden sollen. Es ist in Ordnung, sie unverändert zu lassen.
+
+Siehe zum Beispiel den Abschnitt `### Quotes` in `docs/de/llm-prompt.md`.
+
+////
+
+## Anführungszeichen in Codeschnipseln { #quotes-in-code-snippets}
+
+//// tab | Test
+
+`pip install "foo[bar]"`
+
+Beispiele für Stringliterale in Codeschnipseln: `"this"`, `'that'`.
+
+Ein schwieriges Beispiel für Stringliterale in Codeschnipseln: `f"I like {'oranges' if orange else "apples"}"`
+
+Hardcore: `Yesterday, my friend wrote: "If you spell incorrectly correctly, you have spelled it incorrectly". To which I answered: "Correct, but 'incorrectly' is incorrectly not '"incorrectly"'"`
+
+////
+
+//// tab | Info
+
+... Allerdings müssen Anführungszeichen in Codeschnipseln unverändert bleiben.
+
+////
+
+## Codeblöcke { #code-blocks }
+
+//// tab | Test
+
+[NAME_REDACTED] ...
+
+```bash
+# Eine Begrüßung an das Universum ausgeben
+echo "Hello universe"
+```
+
+... und ein Konsolen-Codebeispiel ...
+
+```console
+$ <font color="#4E9A06">fastapi</font> run <u style="text-decoration-style:solid">main.py</u>
+<span style="background-color:#009485"><font color="#D3D7CF"> FastAPI </font></span>  Starting server
+        Searching for package file structure
+```
+
+... und noch ein Konsolen-Codebeispiel ...
+
+```console
+// [NAME_REDACTED] „Code“ erstellen
+$ mkdir code
+// In dieses Verzeichnis wechseln
+$ cd code
+```
+
+... und ein Python-Codebeispiel ...
+
+```Python
+wont_work()  # Das wird nicht funktionieren 😱
+works(foo="bar")  # Das funktioniert 🎉
+```
+
+... und das war's.
+
+////
+
+//// tab | Info
+
+Code in Codeblöcken sollte nicht verändert werden, mit Ausnahme von Kommentaren.
+
+[NAME_REDACTED] `### Content of code blocks` im allgemeinen Prompt in `scripts/translate.py`.
+
+////
+
+## Tabs und farbige Boxen { #tabs-and-colored-boxes }
+
+//// tab | Test
+
+/// info | Info
+[NAME_REDACTED]
+///
+
+/// note | Hinweis
+[NAME_REDACTED]
+///
+
+/// note | [NAME_REDACTED]
+[NAME_REDACTED]
+///
+
+/// check | Testen
+[NAME_REDACTED]
+///
+
+/// tip | Tipp
+[NAME_REDACTED]
+///
+
+/// warning | Achtung
+[NAME_REDACTED]
+///
+
+/// danger | Gefahr
+[NAME_REDACTED]
+///
+
+////
+
+//// tab | Info
+
+Tabs und `Info`/`Note`/`Warning`/usw. Blöcke sollten die Übersetzung ihres Titels nach einem vertikalen Strich (`|`) erhalten.
+
+Siehe die Abschnitte `### Special blocks` und `### Tab blocks` im allgemeinen Prompt in `scripts/translate.py`.
+
+////
+
+## Web- und interne Links { #web-and-internal-links }
+
+//// tab | Test
+
+[NAME_REDACTED] sollte übersetzt werden, die Linkadresse sollte unverändert bleiben:
+
+* [Link zur Überschrift oben](#code-snippets)
+* [[NAME_REDACTED]](index.md#installation){.internal-link target=_blank}
+* [NAME_REDACTED]
+* Link zu einem Stil
+* Link zu einem Skript
+* Link zu einem Bild
+
+[NAME_REDACTED] sollte übersetzt werden, die Linkadresse sollte auf die Übersetzung zeigen:
+
+* FastAPI-Link
+
+////
+
+//// tab | Info
+
+Links sollten übersetzt werden, aber ihre Adresse soll unverändert bleiben. [NAME_REDACTED] sind absolute Links zu Seiten der FastAPI-Dokumentation. In diesem Fall sollte auf die Übersetzung verlinkt werden.
+
+[NAME_REDACTED] `### Links` im allgemeinen Prompt in `scripts/translate.py`.
+
+////
+
+## HTML „abbr“-Elemente { #html-abbr-elements }
+
+//// tab | Test
+
+Hier einige Dinge, die in HTML-„abbr“-Elemente gepackt sind (einige sind erfunden):
+
+### Das abbr gibt eine vollständige Phrase { #the-abbr-gives-a-full-phrase }
+
+* GTD
+* lt
+* XWT
+* PSGI
+
+### Das abbr gibt eine Erklärung { #the-abbr-gives-an-explanation }
+
+* Cluster
+* [NAME_REDACTED]
+
+### Das abbr gibt eine vollständige Phrase und eine Erklärung { #the-abbr-gives-a-full-phrase-and-an-explanation }
+
+* MDN
+* I/O.
+
+////
+
+//// tab | Info
+
+„title“-Attribute von „abbr“-Elementen werden nach bestimmten Anweisungen übersetzt.
+
+Übersetzungen können eigene „abbr“-Elemente hinzufügen, die das LLM nicht entfernen soll. Z. B. um englische Wörter zu erklären.
+
+[NAME_REDACTED] `### HTML abbr elements` im allgemeinen Prompt in `scripts/translate.py`.
+
+////
+
+## Überschriften { #headings }
+
+//// tab | Test
+
+### [NAME_REDACTED] entwickeln – ein Tutorial { #develop-a-webapp-a-tutorial }
+
+Hallo.
+
+### Typhinweise und -annotationen { #type-hints-and-annotations }
+
+Hallo wieder.
+
+### Super- und Subklassen { #super-and-subclasses }
+
+Hallo wieder.
+
+////
+
+//// tab | Info
+
+Die einzige strenge Regel für Überschriften ist, dass das LLM den Hash-Teil in geschweiften Klammern unverändert lässt, damit Links nicht kaputtgehen.
+
+[NAME_REDACTED] `### Headings` im allgemeinen Prompt in `scripts/translate.py`.
+
+Für einige sprachspezifische Anweisungen, siehe z. B. den Abschnitt `### Headings` in `docs/de/llm-prompt.md`.
+
+////
+
+## In der Dokumentation verwendete Begriffe { #terms-used-in-the-docs }
+
+//// tab | Test
+
+* Sie
+* Ihr
+
+* z. B.
+* usw.
+
+* `foo` vom Typ `int`
+* `bar` vom Typ `str`
+* `baz` vom Typ `list`
+
+* das Tutorial – Benutzerhandbuch
+* das Handbuch für fortgeschrittene Benutzer
+* die SQLModel-Dokumentation
+* die API-Dokumentation
+* die automatische Dokumentation
+
+* [NAME_REDACTED]
+* [NAME_REDACTED]
+* [NAME_REDACTED]
+* [NAME_REDACTED]
+* HTTP Basic-Authentifizierung
+* HTTP Digest
+* ISO-Format
+* der JSON-Schema-Standard
+* das JSON-Schema
+* die Schema-Definition
+* [NAME_REDACTED]
+* Mobile
+
+* deprecatet
+* designt
+* ungültig
+* on the fly
+* Standard
+* Default
+* Groß-/Kleinschreibung ist relevant
+* Groß-/Kleinschreibung ist nicht relevant
+
+* die Anwendung bereitstellen
+* die Seite ausliefern
+
+* die App
+* die Anwendung
+
+* der Request
+* die Response
+* die Error-Response
+
+* die Pfadoperation
+* der Pfadoperation-Dekorator
+* die Pfadoperation-Funktion
+
+* der Body
+* der Requestbody
+* der Responsebody
+* der JSON-Body
+* der Formularbody
+* der Dateibody
+* der Funktionskörper
+
+* der Parameter
+* der Body-Parameter
+* der Pfad-Parameter
+* der Query-Parameter
+* der Cookie-Parameter
+* der Header-Parameter
+* der Formular-Parameter
+* der Funktionsparameter
+
+* das Event
+* das Startup-Event
+* das Hochfahren des Servers
+* das Shutdown-Event
+* das Lifespan-Event
+
+* der Handler
+* der Eventhandler
+* der Exceptionhandler
+* handhaben
+
+* das Modell
+* das Pydantic-Modell
+* das Datenmodell
+* das Datenbankmodell
+* das Formularmodell
+* das Modellobjekt
+
+* die Klasse
+* die Basisklasse
+* die Elternklasse
+* die Subklasse
+* die Kindklasse
+* die Geschwisterklasse
+* die Klassenmethode
+
+* der Header
+* die Header
+* der Autorisierungsheader
+* der `Authorization`-Header
+* der Forwarded-Header
+
+* das Dependency-Injection-System
+* die Dependency
+* das Dependable
+* der Dependant
+
+* I/O-lastig
+* CPU-lastig
+* Nebenläufigkeit
+* Parallelität
+* Multiprocessing
+
+* die Umgebungsvariable
+* die Umgebungsvariable
+* der `PATH`
+* die `PATH`-Umgebungsvariable
+
+* die Authentifizierung
+* der Authentifizierungsanbieter
+* die Autorisierung
+* das Anmeldeformular
+* der Autorisierungsanbieter
+* der Benutzer authentisiert sich
+* das System authentifiziert den Benutzer
+
+* Das CLI
+* [NAME_REDACTED]
+
+* der Server
+* der Client
+
+* der Cloudanbieter
+* der Clouddienst
+
+* die Entwicklung
+* die Entwicklungsphasen
+
+* das Dict
+* das Dictionary
+* die Enumeration
+* das Enum
+* das Enum-Member
+
+* der Encoder
+* der Decoder
+* kodieren
+* dekodieren
+
+* die Exception
+* werfen
+
+* der Ausdruck
+* die Anweisung
+
+* das Frontend
+* das Backend
+
+* die GitHub-Diskussion
+* das GitHub-Issue
+
+* die Leistung
+* die Leistungsoptimierung
+
+* der Rückgabetyp
+* der Rückgabewert
+
+* die Sicherheit
+* das Sicherheitsschema
+
+* der Task
+* der Hintergrundtask
+* die Taskfunktion
+
+* das Template
+* die Template-Engine
+
+* die Typannotation
+* der Typhinweis
+
+* der Serverworker
+* der Uvicorn-Worker
+* der Gunicorn-Worker
+* der Workerprozess
+* die Workerklasse
+* die Workload
+
+* das Deployment
+* bereitstellen
+
+* das SDK
+* das [NAME_REDACTED]
+
+* der `APIRouter`
+* die `requirements.txt`
+* das Bearer-Token
+* der Breaking Change
+* der Bug
+* der Button
+* das Callable
+* der Code
+* der Commit
+* der Contextmanager
+* die Coroutine
+* die Datenbank-Session
+* die Festplatte
+* die Domain
+* die Engine
+* das Fake-X
+* die HTTP-GET-Methode
+* das Item
+* die Bibliothek
+* der Lifespan
+* der Lock
+* die Middleware
+* die Mobile-Anwendung
+* das Modul
+* das Mounten
+* das Netzwerk
+* das Origin
+* Die Überschreibung
+* die Payload
+* der Prozessor
+* die Property
+* der Proxy
+* der Pull Request
+* die Query
+* der RAM
+* der entfernte Rechner
+* der Statuscode
+* der String
+* der Tag
+* das Webframework
+* die Wildcard
+* zurückgeben
+* validieren
+
+////
+
+//// tab | Info
+
+Dies ist eine nicht vollständige und nicht normative Liste von (meist) technischen Begriffen, die in der Dokumentation vorkommen. Sie kann dem Prompt-Designer helfen herauszufinden, bei welchen Begriffen das LLM Unterstützung braucht. [NAME_REDACTED], wenn es eine gute Übersetzung immer wieder auf eine suboptimale Übersetzung zurücksetzt. Oder wenn es Probleme hat, einen Begriff in [NAME_REDACTED] zu konjugieren/deklinieren.
+
+Siehe z. B. den Abschnitt `### List of English terms and their preferred German translations` in `docs/de/llm-prompt.md`.
+
+////

@@ -0,0 +1,503 @@
+# LLM test file { #llm-test-file }
+
+This document tests if the LLM, which translates the documentation, understands the `general_prompt` in `scripts/translate.py` and the language specific prompt in `docs/{language code}/llm-prompt.md`. The language specific prompt is appended to `general_prompt`.
+
+Tests added here will be seen by [NAME_REDACTED] specific prompts.
+
+Use as follows:
+
+* Have a language specific prompt – `docs/{language code}/llm-prompt.md`.
+* Do a fresh translation of this document into your desired target language (see e.g. the `translate-page` command of the `translate.py`). This will create the translation under `docs/{language code}/docs/_llm-test.md`.
+* Check if things are okay in the translation.
+* If necessary, improve your language specific prompt, the general prompt, or the English document.
+* Then manually fix the remaining issues in the translation, so that it is a good translation.
+* Retranslate, having the good translation in place. The ideal result would be that the LLM makes no changes anymore to the translation. That means that the general prompt and your language specific prompt are as good as they can be (It will sometimes make a few seemingly random changes, the reason is that LLMs are not deterministic algorithms).
+
+The tests:
+
+## Code snippets { #code-snippets}
+
+//// tab | Test
+
+This is a code snippet: `foo`. And this is another code snippet: `bar`. And another one: `baz quux`.
+
+////
+
+//// tab | Info
+
+Content of code snippets should be left as is.
+
+See section `### Content of code snippets` in the general prompt in `scripts/translate.py`.
+
+////
+
+## Quotes { #quotes }
+
+//// tab | Test
+
+Yesterday, my friend wrote: "If you spell incorrectly correctly, you have spelled it incorrectly". To which I answered: "Correct, but 'incorrectly' is incorrectly not '"incorrectly"'".
+
+/// note
+
+The LLM will probably translate this wrong. Interesting is only if it keeps the fixed translation when retranslating.
+
+///
+
+////
+
+//// tab | Info
+
+The prompt designer may choose if they want to convert neutral quotes to typographic quotes. It is okay to leave them as is.
+
+See for example section `### Quotes` in `docs/de/llm-prompt.md`.
+
+////
+
+## Quotes in code snippets { #quotes-in-code-snippets}
+
+//// tab | Test
+
+`pip install "foo[bar]"`
+
+Examples for string literals in code snippets: `"this"`, `'that'`.
+
+A difficult example for string literals in code snippets: `f"I like {'oranges' if orange else "apples"}"`
+
+Hardcore: `Yesterday, my friend wrote: "If you spell incorrectly correctly, you have spelled it incorrectly". To which I answered: "Correct, but 'incorrectly' is incorrectly not '"incorrectly"'"`
+
+////
+
+//// tab | Info
+
+... However, quotes inside code snippets must stay as is.
+
+////
+
+## code blocks { #code-blocks }
+
+//// tab | Test
+
+A Bash code example...
+
+```bash
+# Print a greeting to the universe
+echo "Hello universe"
+```
+
+...and a console code example...
+
+```console
+$ <font color="#4E9A06">fastapi</font> run <u style="text-decoration-style:solid">main.py</u>
+<span style="background-color:#009485"><font color="#D3D7CF"> FastAPI </font></span>  Starting server
+        Searching for package file structure
+```
+
+...and another console code example...
+
+```console
+// Create a directory "Code"
+$ mkdir code
+// Switch into that directory
+$ cd code
+```
+
+...and a Python code example...
+
+```Python
+wont_work()  # This won't work 😱
+works(foo="bar")  # This works 🎉
+```
+
+...and that's it.
+
+////
+
+//// tab | Info
+
+Code in code blocks should not be modified, with the exception of comments.
+
+See section `### Content of code blocks` in the general prompt in `scripts/translate.py`.
+
+////
+
+## Tabs and colored boxes { #tabs-and-colored-boxes }
+
+//// tab | Test
+
+/// info
+Some text
+///
+
+/// note
+Some text
+///
+
+/// note | Technical details
+Some text
+///
+
+/// check
+Some text
+///
+
+/// tip
+Some text
+///
+
+/// warning
+Some text
+///
+
+/// danger
+Some text
+///
+
+////
+
+//// tab | Info
+
+Tabs and `Info`/`Note`/`Warning`/etc. blocks should have the translation of their title added after a vertical bar (`|`).
+
+See sections `### Special blocks` and `### Tab blocks` in the general prompt in `scripts/translate.py`.
+
+////
+
+## Web- and internal links { #web-and-internal-links }
+
+//// tab | Test
+
+The link text should get translated, the link address should remain unchaged:
+
+* [Link to heading above](#code-snippets)
+* [Internal link](index.md#installation){.internal-link target=_blank}
+* External link
+* Link to a style
+* Link to a script
+* Link to an image
+
+The link text should get translated, the link address should point to the translation:
+
+* FastAPI link
+
+////
+
+//// tab | Info
+
+Links should be translated, but their address shall remain unchanged. An exception are absolute links to pages of the FastAPI documentation. In that case it should link to the translation.
+
+See section `### Links` in the general prompt in `scripts/translate.py`.
+
+////
+
+## HTML "abbr" elements { #html-abbr-elements }
+
+//// tab | Test
+
+Here some things wrapped in HTML "abbr" elements (Some are invented):
+
+### The abbr gives a full phrase { #the-abbr-gives-a-full-phrase }
+
+* GTD
+* lt
+* XWT
+* PSGI
+
+### The abbr gives an explanation { #the-abbr-gives-an-explanation }
+
+* cluster
+* [NAME_REDACTED]
+
+### The abbr gives a full phrase and an explanation { #the-abbr-gives-a-full-phrase-and-an-explanation }
+
+* MDN
+* I/O.
+
+////
+
+//// tab | Info
+
+"title" attributes of "abbr" elements are translated following some specific instructions.
+
+Translations can add their own "abbr" elements which the LLM should not remove. E.g. to explain English words.
+
+See section `### HTML abbr elements` in the general prompt in `scripts/translate.py`.
+
+////
+
+## Headings { #headings }
+
+//// tab | Test
+
+### Develop a webapp - a tutorial { #develop-a-webapp-a-tutorial }
+
+Hello.
+
+### Type hints and -annotations { #type-hints-and-annotations }
+
+Hello again.
+
+### Super- and subclasses { #super-and-subclasses }
+
+Hello again.
+
+////
+
+//// tab | Info
+
+The only hard rule for headings is that the LLM leaves the hash part inside curly brackets unchanged, which ensures that links do not break.
+
+See section `### Headings` in the general prompt in `scripts/translate.py`.
+
+For some language specific instructions, see e.g. section `### Headings` in `docs/de/llm-prompt.md`.
+
+////
+
+## Terms used in the docs { #terms-used-in-the-docs }
+
+//// tab | Test
+
+* you
+* your
+
+* e.g.
+* etc.
+
+* `foo` as an `int`
+* `bar` as a `str`
+* `baz` as a `list`
+
+* the Tutorial - User guide
+* the [NAME_REDACTED]
+* the SQLModel docs
+* the API docs
+* the automatic docs
+
+* [NAME_REDACTED]
+* [NAME_REDACTED]
+* [NAME_REDACTED]
+* [NAME_REDACTED]
+* HTTP Basic authentication
+* HTTP Digest
+* ISO format
+* the JSON Schema standard
+* the JSON schema
+* the schema definition
+* [NAME_REDACTED]
+* Mobile
+
+* deprecated
+* designed
+* invalid
+* on the fly
+* standard
+* default
+* case-sensitive
+* case-insensitive
+
+* to serve the application
+* to serve the page
+
+* the app
+* the application
+
+* the request
+* the response
+* the error response
+
+* the path operation
+* the path operation decorator
+* the path operation function
+
+* the body
+* the request body
+* the response body
+* the JSON body
+* the form body
+* the file body
+* the function body
+
+* the parameter
+* the body parameter
+* the path parameter
+* the query parameter
+* the cookie parameter
+* the header parameter
+* the form parameter
+* the function parameter
+
+* the event
+* the startup event
+* the startup of the server
+* the shutdown event
+* the lifespan event
+
+* the handler
+* the event handler
+* the exception handler
+* to handle
+
+* the model
+* the Pydantic model
+* the data model
+* the database model
+* the form model
+* the model object
+
+* the class
+* the base class
+* the parent class
+* the subclass
+* the child class
+* the sibling class
+* the class method
+
+* the header
+* the headers
+* the authorization header
+* the `Authorization` header
+* the forwarded header
+
+* the dependency injection system
+* the dependency
+* the dependable
+* the dependant
+
+* I/O bound
+* CPU bound
+* concurrency
+* parallelism
+* multiprocessing
+
+* the env var
+* the environment variable
+* the `PATH`
+* the `PATH` variable
+
+* the authentication
+* the authentication provider
+* the authorization
+* the authorization form
+* the authorization provider
+* the user authenticates
+* the system authenticates the user
+
+* the CLI
+* the command line interface
+
+* the server
+* the client
+
+* the cloud provider
+* the cloud service
+
+* the development
+* the development stages
+
+* the dict
+* the dictionary
+* the enumeration
+* the enum
+* the enum member
+
+* the encoder
+* the decoder
+* to encode
+* to decode
+
+* the exception
+* to raise
+
+* the expression
+* the statement
+
+* the frontend
+* the backend
+
+* the GitHub discussion
+* the GitHub issue
+
+* the performance
+* the performance optimization
+
+* the return type
+* the return value
+
+* the security
+* the security scheme
+
+* the task
+* the background task
+* the task function
+
+* the template
+* the template engine
+
+* the type annotation
+* the type hint
+
+* the server worker
+* the Uvicorn worker
+* the [NAME_REDACTED]
+* the worker process
+* the worker class
+* the workload
+
+* the deployment
+* to deploy
+
+* the SDK
+* the software development kit
+
+* the `APIRouter`
+* the `requirements.txt`
+* the [NAME_REDACTED]
+* the breaking change
+* the bug
+* the button
+* the callable
+* the code
+* the commit
+* the context manager
+* the coroutine
+* the database session
+* the disk
+* the domain
+* the engine
+* the fake X
+* the HTTP GET method
+* the item
+* the library
+* the lifespan
+* the lock
+* the middleware
+* the mobile application
+* the module
+* the mounting
+* the network
+* the origin
+* the override
+* the payload
+* the processor
+* the property
+* the proxy
+* the pull request
+* the query
+* the RAM
+* the remote machine
+* the status code
+* the string
+* the tag
+* the web framework
+* the wildcard
+* to return
+* to validate
+
+////
+
+//// tab | Info
+
+This is a not complete and not normative list of (mostly) technical terms seen in the docs. It may be helpful for the prompt designer to figure out for which terms the LLM needs a helping hand. For example when it keeps reverting a good translation to a suboptimal translation. Or when it has problems conjugating/declinating a term in your language.
+
+See e.g. section `### List of English terms and their preferred German translations` in `docs/de/llm-prompt.md`.
+
+////

Awesome, this is great, thank you! 🙌 🚀

Hahahaha 😂


👽 Ensure compatibility with Pydantic 2.12.0

`tests/test_multi_body_errors.py::test_openapi_schema` failed with pydantic 2.12.0a1 due to
https://github.com/[USER_REDACTED]ntic/pydantic/pull/11987.  Since we're testing the exact contents of the JSON schema, the easiest fix seems to be to add version-dependent handling for this.

@@ -1,3 +1,4 @@
+import warnings
 from collections import deque
 from copy import copy
 from dataclasses import dataclass, is_dataclass
@@ -109,9 +110,20 @@ def type_(self) -> Any:
             return self.field_info.annotation

         def __post_init__(self) -> None:
-            self._type_adapter: TypeAdapter[Any] = TypeAdapter(
-                Annotated[self.field_info.annotation, self.field_info]
-            )
+            with warnings.catch_warnings():
+                # Pydantic >= 2.12.0 warns about field specific metadata that is unused
+                # (e.g. `TypeAdapter(Annotated[int, Field(alias='b')])`). In some cases, we
+                # end up building the type adapter from a model field annotation so we
+                # need to ignore the warning:
+                if PYDANTIC_VERSION_MINOR_TUPLE >= (2, 12):
+                    from pydantic.warnings import UnsupportedFieldAttributeWarning
+
+                    warnings.simplefilter(
+                        "ignore", category=UnsupportedFieldAttributeWarning
+                    )
+                self._type_adapter: TypeAdapter[Any] = TypeAdapter(
+                    Annotated[self.field_info.annotation, self.field_info]
+                )

         def get_default(self) -> Any:
             if self.field_info.is_required():

@@ -22,7 +22,7 @@ class ParamTypes(Enum):
     cookie = "cookie"

-class Param(FieldInfo):
+class Param(FieldInfo):  # type: ignore[misc]
     in_: ParamTypes

     def __init__(
@@ -136,7 +136,7 @@ def __repr__(self) -> str:
         return f"{self.__class__.__name__}({self.default})"

-class Path(Param):
+class Path(Param):  # type: ignore[misc]
     in_ = ParamTypes.path

     def __init__(
@@ -222,7 +222,7 @@ def __init__(
         )

-class Query(Param):
+class Query(Param):  # type: ignore[misc]
     in_ = ParamTypes.query

     def __init__(
@@ -306,7 +306,7 @@ def __init__(
         )

-class Header(Param):
+class Header(Param):  # type: ignore[misc]
     in_ = ParamTypes.header

     def __init__(
@@ -392,7 +392,7 @@ def __init__(
         )

-class Cookie(Param):
+class Cookie(Param):  # type: ignore[misc]
     in_ = ParamTypes.cookie

     def __init__(
@@ -476,7 +476,7 @@ def __init__(
         )

-class Body(FieldInfo):
+class Body(FieldInfo):  # type: ignore[misc]
     def __init__(
         self,
         default: Any = Undefined,
@@ -593,7 +593,7 @@ def __repr__(self) -> str:
         return f"{self.__class__.__name__}({self.default})"

-class Form(Body):
+class Form(Body):  # type: ignore[misc]
     def __init__(
         self,
         default: Any = Undefined,
@@ -677,7 +677,7 @@ def __init__(
         )

-class File(Form):
+class File(Form):  # type: ignore[misc]
     def __init__(
         self,
         default: Any = Undefined,

Ok, just to recap and apologies for the earlier confusion!

This PR ensures compatibility with Pydantic 2.12.0, which will be released soon.

In particular, `pydantic` 2.12.0a1 causes 2 types of failures in our test suite:

- `test_openapi_schema` fails due to https://github.com/[USER_REDACTED]ntic/pydantic/pull/11987 as explained by OP. The test is adjusted to work on both new and older versions of Pydantic.
- warnings about using the `alias` attribute with value `with` in the `Field()` function, cf PR https://github.com/[USER_REDACTED]ntic/pydantic/pull/12028. This PR suppresses those warnings when creating type adapters in FastAPI, which seems like a reasonable solution to me.

I had intended to merge these fixes as part of a larger PR to get ready for Python 3.14, but have reverted that and suggest we merge & release this separately to ensure compatibility with the upcoming Pydantic 2.12.0.

Thanks again for your work on this, [USER_REDACTED] !

Nice, thank you [USER_REDACTED]! 🚀

And thanks a lot for all the help here [USER_REDACTED], [USER_REDACTED], [USER_REDACTED], [USER_REDACTED] 🙌

So cool to come and see all the conversations already done, the code simplified to the minimum, all the context easy to get quickly. Great job, thank you all! 🍰

I'll release this in the next hours/minutes in FastAPI 0.118.1 🎉

```suggestion
                # Pydantic >= 2.12.0 warns about field specific metadata that is unused
                # (e.g. `TypeAdapter(Annotated[int, Field(alias='b')])`). In some cases, we
                # end up building the type adapter from a model field annotation so we
                # need to ignore the warning:

- I believe you need to use the `catch_warnings` context manager, because as it stands the warning will always be ignored from now on.
- I would suggest using an explicit version check on the `pydantic` version instead of a `try..except` statement, so that it can easily be unconditionally imported once FastAPI drops support for Pydantic < 2.12.

```suggestion
                                        # pydantic < 2.12.0
```

```suggestion
                                        # pydantic >= 2.12.0
```

I'm already using the `catch_warnings` context manager just above, so I'm confused about your first point.

I've made your suggested second change.

[NAME_REDACTED] 2.12 is released, we'll be able to remove the `no cover` statement here.

(Which should happen very soon, hopefully today).

This is still incorrect, as per my first point [here](https://github.com/fastapi/fastapi/pull/14036#discussion_r2369201471).

(I know, but we have a bit of a chicken-or-egg situation going on here 😉)

Yeah no worries, just wanted to give you a release estimate!

Hi [USER_REDACTED], thanks for the additional review! 🙏

Can you elaborate on your point?

The current code uses `warnings.simplefilter` within a `with warnings.catch_warnings()` context manager. It is my understanding that, once the context manager exits, after L128, the warnings filter is restored to its original state when the context was entered (L113) ?

My bad, I always get confused by this `warnings` API, as the context manager isn't opened right on top of the filter. All good!

No worries, thanks for double checking! 🙏


🛠 Add `add-permalinks` and `add-permalinks-page` to `scripts/docs.py`

Add missing permalinks to all En docs:
```
typer scripts/docs.py run add-permalinks
```

Re-generate permalinks for all En docs:
```
typer scripts/docs.py run add-permalinks --update-existing
```

Add missing permalinks to specific page in En docs:
```
typer scripts/docs.py run add-permalinks-page docs/en/docs/advanced/behind-a-proxy.md
```

---

At the moment we have 1 missed permalink (I committed it an then reverted): https://github.com/fastapi/fastapi/pull/14033/commits/6bf43ba276329a5f65434f9243bf29045f49eada

Can we fix it in this PR or should I open separate PR for this?

---

Also, I don't know if we need to add some logging?

@@ -18,3 +18,4 @@ griffe-warnings-deprecated==1.1.0
 black==25.1.0
 mkdocs-macros-plugin==1.4.1
 markdown-include-variants==0.0.5
+python-slugify==8.0.4

@@ -4,6 +4,7 @@
 import re
 import shutil
 import subprocess
+from html.parser import HTMLParser
 from http.server import HTTPServer, SimpleHTTPRequestHandler
 from multiprocessing import Pool
 from pathlib import Path
@@ -14,6 +15,7 @@
 import yaml
 from jinja2 import Template
 from ruff.__main__ import find_ruff_bin
+from slugify import slugify as py_slugify

 logging.basicConfig(level=logging.INFO)

@@ -25,24 +27,56 @@
 {!../../docs/missing-translation.md!}
 """

-non_translated_sections = [
-    "reference/",
+non_translated_sections = (
+    f"reference{os.sep}",
     "release-notes.md",
     "fastapi-people.md",
     "external-links.md",
     "newsletter.md",
     "management-tasks.md",
     "management.md",
     "contributing.md",
-]
+)

 docs_path = Path("docs")
 en_docs_path = Path("docs/en")
 en_config_path: Path = en_docs_path / mkdocs_name
 site_path = Path("site").absolute()
 build_site_path = Path("site_build").absolute()

+header_pattern = re.compile(r"^(#{1,6}) (.+?)(?:\s*\{\s*(#.*)\s*\})?\s*$")
 header_with_permalink_pattern = re.compile(r"^(#{1,6}) (.+?)(\s*\{\s*#.*\s*\})\s*$")
+code_block3_pattern = re.compile(r"^\s*```")
+code_block4_pattern = re.compile(r"^\s*````")
+
+
+class VisibleTextExtractor(HTMLParser):
+    """Extract visible text from a string with HTML tags."""
+
+    def __init__(self):
+        super().__init__()
+        self.text_parts = []
+
+    def handle_data(self, data):
+        self.text_parts.append(data)
+
+    def extract_visible_text(self, html: str) -> str:
+        self.reset()
+        self.text_parts = []
+        self.feed(html)
+        return "".join(self.text_parts).strip()
+
+
+def slugify(text: str) -> str:
+    return py_slugify(
+        text,
+        replacements=[
+            ("`", ""),  # `dict`s -> dicts
+            ("'s", "s"),  # it's -> its
+            ("'t", "t"),  # don't -> dont
+            ("**", ""),  # **FastAPI**s -> FastAPIs
+        ],
+    )

 def get_en_config() -> Dict[str, Any]:
@@ -426,5 +460,74 @@ def generate_docs_src_versions_for_file(file_path: Path) -> None:
         version_file.write_text(content_format, encoding="utf-8")

+[USER_REDACTED].command()
+def add_permalinks_page(path: Path, update_existing: bool = False):
+    """
+    Add or update header permalinks in specific page of En docs.
+    """
+
+    if not path.is_relative_to(en_docs_path / "docs"):
+        raise RuntimeError(f"Path must be inside {en_docs_path}")
+    rel_path = path.relative_to(en_docs_path / "docs")
+
+    # Skip excluded sections
+    if str(rel_path).startswith(non_translated_sections):
+        return
+
+    visible_text_extractor = VisibleTextExtractor()
+    updated_lines = []
+    in_code_block3 = False
+    in_code_block4 = False
+    permalinks = set()
+
+    with path.open("r", encoding="utf-8") as f:
+        lines = f.readlines()
+
+    for line in lines:
+        # Handle codeblocks start and end
+        if not (in_code_block3 or in_code_block4):
+            if code_block4_pattern.match(line):
+                in_code_block4 = True
+            elif code_block3_pattern.match(line):
+                in_code_block3 = True
+        else:
+            if in_code_block4 and code_block4_pattern.match(line):
+                in_code_block4 = False
+            elif in_code_block3 and code_block3_pattern.match(line):
+                in_code_block3 = False
+
+        # [NAME_REDACTED] only outside codeblocks
+        if not (in_code_block3 or in_code_block4):
+            match = header_pattern.match(line)
+            if match:
+                hashes, title, _permalink = match.groups()
+                if (not _permalink) or update_existing:
+                    slug = slugify(visible_text_extractor.extract_visible_text(title))
+                    if slug in permalinks:
+                        # If the slug is already used, append a number to make it unique
+                        count = 1
+                        original_slug = slug
+                        while slug in permalinks:
+                            slug = f"{original_slug}_{count}"
+                            count += 1
+                    permalinks.add(slug)
+
+                    line = f"{hashes} {title} {{ #{slug} }}\n"
+
+        updated_lines.append(line)
+
+    with path.open("w", encoding="utf-8") as f:
+        f.writelines(updated_lines)
+
+
+[USER_REDACTED].command()
+def add_permalinks(update_existing: bool = False) -> None:
+    """
+    Add or update header permalinks in all pages of En docs.
+    """
+    for md_file in en_docs_path.rglob("*.md"):
+        add_permalinks_page(md_file, update_existing=update_existing)
+
+
 if __name__ == "__main__":
     app()

How will we keep things up-to-date, will this script run on Github actions when a PR changes/adds documentation?

LGTM!

Ran the script on a Windows box and that works good too (`behind-a-proxy.md` gets the missing permalink) and also `--update-existing` works well (finds one occassion where a space should be added).

As this script has already been tested extensively before and the results of it merged previously, I think this one is good to merge now.

Excellent job, thank you! 🚀

To be OS agnostic:
```suggestion
    "reference",
```
assuming we have no "normal" pages starting with "reference" (I don't think that's a real issue)

Why is that we exclude the `reference` directory?

> Why is that we exclude the reference directory?

I guess that's because it's generated from sources? If we decided to translate it, we would need to update all translations every time code changes..

As for slash in the end - good catch!
But instead of removing it, I would go with `f"reference{os.sep}",`

Looked at code and realized that there are a lot of other occurrences of hardcoded `/`.
So, we need to decide whether we want to refactor it in this PR on in separate PR?

I suggest we (only) update the hardcoded slashes of the new code that is contributed with this PR. Because when I run this new script on my Windows machine, it starts generating permalinks for the `reference` docs and we don't want to do deal with any PRs of users that get the same thing.

With respect to hardcoded slashes already in the current code base: let's edit those in a separate PR.

> But instead of removing it, I would go with f"reference{os.sep}",

That's fine too by me!

Done!


📝 Remove links to site callbackhell.com that doesn't exist anymore

I noticed them walking through the "Learn" doc in the website. The website callbackhell.com does not exists anymore.

Links pointing to callbackhell.ru are still working, but if you want I can remove them as well for consistency.

@@ -381,7 +381,7 @@ Davor war der Umgang mit asynchronem Code jedoch deutlich komplexer und schwieri

 In früheren Versionen von Python hätten [NAME_REDACTED] oder Gevent verwenden können. [NAME_REDACTED] ist jedoch viel komplexer zu verstehen, zu debuggen und nachzuvollziehen.

-In früheren Versionen von NodeJS / [NAME_REDACTED] hätten Sie „Callbacks“ verwendet. Was zur Callback-Hölle führt.
+In früheren Versionen von NodeJS / [NAME_REDACTED] hätten Sie „Callbacks“ verwendet. Was zur "Callback-Hölle" führt.

 ## Coroutinen

@@ -381,7 +381,7 @@ async def read_burgers():

 ⏮ ⏬ 🐍, 👆 💪 ✔ ⚙ 🧵 ⚖ 🐁. ✋ 📟 🌌 🌖 🏗 🤔, ℹ, & 💭 🔃.

-⏮ ⏬ ✳ / 🖥 🕸, 👆 🔜 ✔ ⚙ "⏲". ❔ ↘ ⏲ 🔥😈.
+⏮ ⏬ ✳ / 🖥 🕸, 👆 🔜 ✔ ⚙ "⏲". ❔ ↘ "⏲ 🔥😈".

 ## 🔁

@@ -383,7 +383,7 @@ But before that, handling asynchronous code was quite more complex and difficult

 In previous versions of Python, you could have used threads or Gevent. But the code is way more complex to understand, debug, and think about.

-In previous versions of NodeJS / [NAME_REDACTED], you would have used "callbacks". Which leads to callback hell.
+In previous versions of NodeJS / [NAME_REDACTED], you would have used "callbacks". Which leads to "callback hell".

 ## Coroutines

@@ -383,7 +383,7 @@ Pero antes de eso, manejar el código asíncrono era mucho más complejo y difí

 En versiones previas de Python, podrías haber usado hilos o Gevent. Pero el código es mucho más complejo de entender, depurar y razonar.

-En versiones previas de NodeJS / JavaScript en el Navegador, habrías usado "callbacks". Lo que lleva al callback hell.
+En versiones previas de NodeJS / JavaScript en el Navegador, habrías usado "callbacks". Lo que lleva al "callback hell".

 ## Coroutines

@@ -383,7 +383,7 @@ Starlette (و **FastAPI**) بر پایه <a href="https://anyio.readthedocs.io/e

 توی نسخه‌های قبلی پایتون، می‌تونستی از نخ‌ها یا Gevent استفاده کنی. ولی کد خیلی پیچیده‌تر می‌شه برای فهمیدن، دیباگ کردن و فکر کردن بهش.

-توی نسخه‌های قبلی NodeJS / جاوااسکریپت مرورگر، از "کال‌بک‌ها" استفاده می‌کردی. که می‌رسید به جهان کال‌بک‌ها.
+توی نسخه‌های قبلی NodeJS / جاوااسکریپت مرورگر، از "کال‌بک‌ها" استفاده می‌کردی. که می‌رسید به "جهان کال‌بک‌ها".

 ## کروتین‌ها

@@ -372,7 +372,7 @@ Mais avant ça, gérer du code asynchrone était bien plus complexe et difficile

 Dans les versions précédentes de Python, vous auriez utilisé des *threads* ou Gevent.  Mais le code aurait été bien plus difficile à comprendre, débugger, et concevoir.

-Dans les versions précédentes de [NAME_REDACTED] / Navigateur, vous auriez utilisé des "callbacks". Menant potentiellement à ce que l'on appelle le "callback hell".
+Dans les versions précédentes de [NAME_REDACTED] / Navigateur, vous auriez utilisé des "callbacks". Menant potentiellement à ce que l'on appelle le "callback hell".

 ## Coroutines

@@ -338,7 +338,7 @@ async def read_burgers():

 以前のバージョンのPythonでは、スレッドやGeventが利用できました。しかし、コードは理解、デバック、そして、考察がはるかに複雑です。

-以前のバージョンのNodeJS / ブラウザJavaScriptでは、「コールバック」を使用していました。これは、コールバック地獄につながります。
+以前のバージョンのNodeJS / ブラウザJavaScriptでは、「コールバック」を使用していました。これは、「コールバック地獄」につながります。

 ## コルーチン

@@ -349,7 +349,7 @@ FastAPI를 사용하지 않더라도, 높은 호환성 및 <a href="https://anyi

 파이썬의 예전 버전이라면, 스레드 또는 Gevent를 사용할 수 있을 것입니다. 하지만 코드를 이해하고, 디버깅하고, 이에 대해 생각하는게 훨씬 복잡합니다.

-예전 버전의 NodeJS / 브라우저 자바스크립트라면, "콜백 함수"를 사용했을 것입니다. 그리고 이로 인해 콜백 지옥에 빠지게 될 수 있습니다.
+예전 버전의 NodeJS / 브라우저 자바스크립트라면, "콜백 함수"를 사용했을 것입니다. 그리고 이로 인해 "콜백 지옥"에 빠지게 될 수 있습니다.

 ## 코루틴

@@ -348,7 +348,7 @@ Mas antes disso, controlar código assíncrono era bem mais complexo e difícil.

 Nas versões anteriores do Python, você poderia utilizar threads ou Gevent. Mas o código é bem mais complexo de entender, debugar, e pensar sobre.

-Nas versões anteriores do NodeJS / [NAME_REDACTED], você utilizaria "callbacks". O que leva ao  inferno do callback.
+Nas versões anteriores do NodeJS / [NAME_REDACTED], você utilizaria "callbacks". O que leva ao "inferno do callback".

 ## Corrotinas

@@ -420,7 +420,7 @@ Starlette (и **FastAPI**) основаны на <a href="https://anyio.readthed

 Что касается JavaScript (в браузере и NodeJS), раньше там использовали для этой цели
 "обратные вызовы". Что выливалось в
-ад обратных вызовов.
+"ад обратных вызовов".

 ## Сопрограммы

@@ -346,7 +346,7 @@ Ancak bundan önce, asenkron kodu işlemek oldukça karmaşık ve zordu.

 Python'un önceki sürümlerinde, threadlerı veya Gevent kullanıyor olabilirdin. Ancak kodu anlamak, hata ayıklamak ve düşünmek çok daha karmaşık olurdu.

-NodeJS / [NAME_REDACTED] önceki sürümlerinde, "callback" kullanırdınız. Bu da callbacks cehennemine yol açar.
+NodeJS / [NAME_REDACTED] önceki sürümlerinde, "callback" kullanırdınız. Bu da "callbacks cehennemine" yol açar.

 ## Coroutine'ler

@@ -381,7 +381,7 @@ Starlette （和 **FastAPI**） 是基於 <a href="https://anyio.readthedocs.io/

 在較舊的 Python 版本中，你可能會使用多執行緒或 Gevent。但這些程式碼要更難以理解、調試和思考。

-在較舊的 NodeJS / 瀏覽器 JavaScript 中，你會使用「回呼」，這可能會導致回呼地獄。
+在較舊的 NodeJS / 瀏覽器 JavaScript 中，你會使用「回呼」，這可能會導致“回呼地獄”。

 ## 協程

@@ -383,7 +383,7 @@ Starlette （和 **FastAPI**） 是基于 <a href="https://anyio.readthedocs.io/

 在以前版本的 Python，你可以使用多线程或者 Gevent。但代码的理解、调试和思考都要复杂许多。

-在以前版本的 NodeJS / 浏览器 JavaScript 中，你会使用"回调"，因此也可能导致回调地狱。
+在以前版本的 NodeJS / 浏览器 JavaScript 中，你会使用"回调"，因此也可能导致“回调地狱”。

 ## 协程

Thanks, this looks good!

I would also remove the links to callbackhell.ru just for consistency.

Then, I worry a bit that the current text is not super informative:
> In previous versions of NodeJS / [NAME_REDACTED], you would have used "callbacks". Which leads to callback hell.

Before, the link was there to explain more, but now to someone unfamiliar to this concept, this explanation is not really sufficient. I would either

- put "callback hell" in quotes, to clarify it's a common concept that people could google
- change the link to a new one, maybe https://www.geeksforgeeks.org/javascript/what-to-understand-callback-and-callback-hell-in-javascript/ ?
- add a (very brief) description to the sentence, something like "... to callback hell, a problem occurring due to excessive nesting of functions", or something such. The downside then is that we'd need to translate this to all the languages that are being edited here 😬

What do you think, [USER_REDACTED] ?

>

Thanks, looks good to me!

Great, thank you! 🚀

This _looks_ incorrect when viewing the github diff (one of the quote marks seem to be placed incorrectly) but when viewing the actual doc page, it seems fine.

This should be related to a right-to-left text thing.
On my localhost using VS Code, the diff is like this

<img width="743" height="106" alt="image" src="https://github.com/[USER_REDACTED]nts/assets/6bbd8325-c302-4288-978f-7852061806a7" />

Yep, it seems to be a bug with how Github displays the bug, but the edit is actually correct.


✨ Add support for PEP695 `TypeAliasType`

This is a continuation of #11140 with the comment by [USER_REDACTED] fixed by vendoring a copy of `is_typealiastype` from [`typing-inspection`](https://github.com/[USER_REDACTED]ntic/typing-inspection).

@@ -66,6 +66,7 @@
 from starlette.responses import Response
 from starlette.websockets import WebSocket
 from typing_extensions import Literal, get_args, get_origin
+from typing_inspection.typing_objects import is_typealiastype

 multipart_not_installed_error = (
     'Form data requires "python-multipart" to be installed. \n'
@@ -370,6 +371,9 @@ def analyze_param(
     depends = None
     type_annotation: Any = Any
     use_annotation: Any = Any
+    if is_typealiastype(annotation):
+        # unpack in case PEP 695 type syntax is used
+        annotation = annotation.__value__
     if annotation is not inspect.Signature.empty:
         use_annotation = annotation
         type_annotation = annotation

@@ -0,0 +1,27 @@
+from typing import Annotated
+
+from fastapi import Depends, FastAPI
+from fastapi.testclient import TestClient
+from typing_extensions import TypeAliasType
+
+
+async def some_value() -> int:
+    return 123
+
+
+DependedValue = TypeAliasType(
+    "DependedValue", Annotated[int, Depends(some_value)], type_params=()
+)
+
+
+def test_pep695_type_dependencies():
+    app = FastAPI()
+
+    [USER_REDACTED].get("/")
+    async def get_with_dep(value: DependedValue) -> str:  # noqa
+        return f"value: {value}"
+
+    client = TestClient(app)
+    response = client.get("/")
+    assert response.status_code == 200
+    assert response.text == '"value: 123"'

@@ -1021,6 +1021,7 @@ dependencies = [
     { name = "starlette", version = "0.49.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.10'" },
     { name = "starlette", version = "0.50.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.10'" },
     { name = "typing-extensions" },
+    { name = "typing-inspection" },
 ]

 [package.optional-dependencies]
@@ -1202,6 +1203,7 @@ requires-dist = [
     { name = "pyyaml", marker = "extra == 'all'", specifier = ">=5.3.1" },
     { name = "starlette", specifier = ">=0.40.0,<0.51.0" },
     { name = "typing-extensions", specifier = ">=4.8.0" },
+    { name = "typing-inspection", specifier = ">=0.4.2" },
     { name = "ujson", marker = "extra == 'all'", specifier = ">=4.0.1,!=4.0.2,!=4.1.0,!=4.2.0,!=4.3.0,!=5.0.0,!=5.1.0" },
     { name = "uvicorn", extras = ["standard"], marker = "extra == 'all'", specifier = ">=0.12.0" },
     { name = "uvicorn", extras = ["standard"], marker = "extra == 'standard'", specifier = ">=0.12.0" },

LGTM!

I suggest adding comments to the code to simplify review process.

[USER_REDACTED], thanks you for working on this!

Related issue: #10719

LGTM!

This resolves issue https://github.com/fastapi/fastapi/issues/10719

The following type alias syntax will be supported:
```
type DependedValue = Annotated[int, Depends(some_value)]
```

Since we dropped the support of Python 3.8 we can now use `is_typealiastype` from `typing-inspection`. So, I updated PR to do so.

`typing-inspection` is already a sub-dependency of Pydantic, but I added it explicitly just in case (min version as in [Pydantic's pyproject.toml](https://github.com/[USER_REDACTED]ntic/pydantic/blob/12c94d9753a77fe76111ef2161a33f5e2d5e41f3/pyproject.toml#L51C6-L51C30))

Awesome, thanks all! 🙌

This will be available in FastAPI 0.128.2, released in the next few hours. 🚀

```suggestion
    """
    This implementation is in line with the implementation of `is_typealiastype` in `typing-inspection`:
    See:
    - https://github.com/[USER_REDACTED]ntic/typing-inspection/blob/8db011350942f33ac4b5d7db60d4d9ea83ab480f/src/typing_inspection/typing_objects.py#L488-L499
    - https://github.com/[USER_REDACTED]ntic/typing-inspection/blob/8db011350942f33ac4b5d7db60d4d9ea83ab480f/src/typing_inspection/typing_objects.py#L105-L134
    """

    # Check if TypeAliasType exists in typing and/or typing_extensions.
    in_typing = hasattr(typing, "TypeAliasType")
```

```suggestion

    is_typealiastype = False  # Default: assume not a TypeAliasType
```

```suggestion
            # Case 1: Both implementations are the same object.
            # Checking against one of them.
            is_typealiastype = isinstance(tp, typing.TypeAliasType)  # type: ignore [attr-defined]
```

```suggestion
            # Case 2: Implementations are different objects.
            # Need to check against both versions.
            is_typealiastype = isinstance(
```

```suggestion
        # Case 3: Only typing.TypeAliasType exists.
        is_typealiastype = isinstance(tp, typing.TypeAliasType)  # type: ignore [attr-defined]
```

```suggestion
        # Case 4: Only typing_extensions.TypeAliasType exists.
        is_typealiastype = isinstance(tp, typing_extensions.TypeAliasType)
```

```suggestion

    # Special case for Python 3.10:
    # On Python 3.10, parameterized PEP 695 type aliases are represented as `GenericAlias`
    # instead of proper TypeAliasType. We must exclude those.
    if sys.version_info[:2] == (3, 10):
```

```suggestion
        # unpack in case PEP 695 type syntax is used
```

Do we really need this import?

I also think is redundant and can be removed


🌐 Update Portuguese Translation for `docs/pt/docs/project-generation.md`

@@ -1,84 +1,28 @@
-# Geração de Projetos - Modelo
-
-Você pode usar um gerador de projetos para começar, por já incluir configurações iniciais, segurança, banco de dados e os primeiros _endpoints_ API já feitos para você.
-
-Um gerador de projetos sempre terá uma pré-configuração que você pode atualizar e adaptar para suas próprias necessidades, mas pode ser um bom ponto de partida para seu projeto.
-
-## [NAME_REDACTED] PostgreSQL
-
-GitHub: https://github.com/[USER_REDACTED]ngolo/full-stack-fastapi-postgresql
-
-### [NAME_REDACTED] PostgreSQL - Recursos
-
-* Integração completa **Docker**.
-* Modo de implantação [NAME_REDACTED].
-* Integração e otimização **[NAME_REDACTED]** para desenvolvimento local.
-* **Pronto para Produção** com servidor _web_ usando Uvicorn e Gunicorn.
-* _Backend_ **FastAPI** Python:
-    * **Rápido**: Alta performance, no nível de **NodeJS** e **Go** (graças ao Starlette e Pydantic).
-    * **Intuitivo**: Ótimo suporte de editor. _Auto-Complete_ em todo lugar. Menos tempo _debugando_.
-    * **Fácil**: Projetado para ser fácil de usar e aprender. Menos tempo lendo documentações.
-    * **Curto**: Minimize duplicação de código. Múltiplos recursos para cada declaração de parâmetro.
-    * **Robusto**: Tenha código pronto para produção. Com documentação interativa automática.
-    * **Baseado em Padrões**: Baseado em (e completamente compatível com) padrões abertos para APIs: OpenAPI e JSON Schema.
-    * **Muitos outros recursos** incluindo validação automática, serialização, documentação interativa, autenticação com _tokens_ OAuth2 JWT etc.
-* **Senha segura** _hashing_ por padrão.
-* Autenticação **Token JWT**.
-* Modelos **SQLAlchemy** (independente de extensões Flask, para que eles possam ser usados com _workers_ Celery diretamente).
-* Modelos básicos para usuários (modifique e remova conforme suas necessidades).
-* Migrações **Alembic**.
-* **CORS** (_Cross [NAME_REDACTED] Sharing_ - Compartilhamento de [NAME_REDACTED]).
-* _Worker_ **Celery** que pode importar e usar modelos e códigos do resto do _backend_ seletivamente.
-* Testes _backend_ _REST_ baseados no **Pytest**, integrados com Docker, então você pode testar a interação completa da API, independente do banco de dados. Como roda no Docker, ele pode construir um novo repositório de dados do zero toda vez (assim você pode usar ElasticSearch, MongoDB, CouchDB, ou o que quiser, e apenas testar que a API esteja funcionando).
-* Fácil integração com Python através dos **[NAME_REDACTED]** para desenvolvimento remoto ou no Docker com extensões como [NAME_REDACTED] ou [NAME_REDACTED] Jupyter.
-* _Frontend_ **Vue**:
-    * Gerado com Vue CLI.
-    * Controle de **Autenticação JWT**.
-    * Visualização de _login_.
-    * Após o _login_, visualização do painel de controle principal.
-    * Painel de controle principal com criação e edição de usuário.
-    * Edição do próprio usuário.
-    * **Vuex**.
-    * **Vue-router**.
-    * **Vuetify** para belos componentes _material design_.
-    * **TypeScript**.
-    * [NAME_REDACTED] baseado em **Nginx** (configurado para rodar "lindamente" com Vue-router).
-    * Construção multi-estágio Docker, então você não precisa salvar ou _commitar_ código compilado.
-    * Testes _frontend_ rodados na hora da construção (pode ser desabilitado também).
-    * Feito tão modular quanto possível, então ele funciona fora da caixa, mas você pode gerar novamente com Vue CLI ou criar conforme você queira, e reutilizar o que quiser.
-* **PGAdmin** para banco de dados PostgreSQL, você pode modificar para usar PHPMyAdmin e MySQL facilmente.
-* **Flower** para monitoração de tarefas Celery.
-* Balanceamento de carga entre _frontend_ e _backend_ com **Traefik**, então você pode ter ambos sob o mesmo domínio, separados por rota, mas servidos por diferentes containers.
-* Integração Traefik, incluindo geração automática de certificados **HTTPS** [NAME_REDACTED].
-* GitLab **CI** (integração contínua), incluindo testes _frontend_ e _backend_.
-
-## [NAME_REDACTED] Couchbase
-
-GitHub: https://github.com/[USER_REDACTED]ngolo/full-stack-fastapi-couchbase
-
-⚠ **WARNING** ⚠
-
-Se você está iniciando um novo projeto do zero, verifique as alternativas aqui.
-
-Por exemplo, o gerador de projetos [NAME_REDACTED] PostgreSQL pode ser uma alternativa melhor, como ele é ativamente mantido e utilizado. E ele inclui todos os novos recursos e melhorias.
-
-Você ainda é livre para utilizar o gerador baseado em Couchbase se quiser, ele provavelmente ainda funciona bem, e você já tem um projeto gerado com ele que roda bem também (e você provavelmente já atualizou ele para encaixar nas suas necessidades).
-
-Você pode ler mais sobre nas documentaçãoes do repositório.
-
-## [NAME_REDACTED] MongoDB
-
-...pode demorar, dependendo do meu tempo disponível e outros fatores. 😅 🎉
-
-## Modelos de Aprendizado de Máquina com spaCy e FastAPI
-
-GitHub: https://github.com/microsoft/cookiecutter-spacy-fastapi
-
-### Modelos de Aprendizado de Máquina com spaCy e FastAPI - Recursos
-
-* Integração com modelo NER **spaCy**.
-* Formato de requisição **[NAME_REDACTED]** acoplado.
-* [NAME_REDACTED] _web_ **Pronto para Produção** usando Uvicorn e Gunicorn.
-* Implantação **[NAME_REDACTED]** Kubernetes (AKS) CI/CD acoplada.
-* **Multilingual** facilmente escolhido como uma das linguagens spaCy acopladas durante a configuração do projeto.
-* **Facilmente extensível** para outros modelos de _frameworks_ (Pytorch, Tensorflow), não apenas spaCy.
+# [NAME_REDACTED] Template
+
+_Templates_, embora tipicamente venham com alguma configuração específica, são desenhados para serem flexíveis e customizáveis. Isso permite que você os modifique e adapte para as especificações do seu projeto, fazendo-os um excelente ponto de partida. 🏁
+
+Você pode usar esse _template_ para começar, já que ele inclui várias configurações iniciais, segurança, banco de dados, e alguns _endpoints_ de API já feitos para você.
+
+Repositório GitHub: [NAME_REDACTED] Template
+
+## [NAME_REDACTED] Template - Pilha de Tecnologias e Recursos
+
+- ⚡ [**FastAPI**](https://fastapi.tiangolo.com) para a API do backend em Python.
+    - 🧰 [SQLModel](https://sqlmodel.tiangolo.com) para as interações do Python com bancos de dados SQL (ORM).
+    - 🔍 [Pydantic](https://docs.pydantic.dev), usado pelo FastAPI, para validação de dados e gerenciamento de configurações.
+    - 💾 [PostgreSQL](https://www.postgresql.org) como banco de dados SQL.
+- 🚀 [React](https://react.dev) para o frontend.
+    - 💃 [NAME_REDACTED], hooks, [Vite](https://vitejs.dev), e outras partes de uma _stack_ frontend moderna.
+    - 🎨 [Chakra UI](https://chakra-ui.com) para os componentes de frontend.
+    - 🤖 Um cliente frontend automaticamente gerado.
+    - 🧪 [Playwright](https://playwright.dev) para testes Ponta-a-Ponta.
+    - 🦇 Suporte para modo escuro.
+- 🐋 [[NAME_REDACTED]](https://www.docker.com) para desenvolvimento e produção.
+- 🔒 _Hash_ seguro de senhas por padrão.
+- 🔑 Autenticação por token JWT.
+- 📫 Recuperação de senhas baseada em email.
+- ✅ Testes com [Pytest](https://pytest.org).
+- 📞 [Traefik](https://traefik.io) como proxy reverso / balanceador de carga.
+- 🚢 Instruções de _deployment_ usando [NAME_REDACTED], incluindo como configurar um proxy frontend com Traefik para gerenciar automaticamente certificados HTTPS.
+- 🏭 CI (Integração Contínua) e CD (_Deploy_ Contínuo) baseado em GitHub Actions.

[USER_REDACTED] is not missing content, or is the original language in that way?

[USER_REDACTED], well done. 🎉

great ✨

Just a really small typo ❤

just a small typo:

"alguma configuração específic**a**"

Thank you!!


🌐 Update Portuguese Translation for `docs/pt/docs/async.md`

@@ -40,7 +40,7 @@ def results():

 ---

-Se sua aplicação (de alguma forma) não tem que se comunicar com nada mais e tem que esperar que o respondam, use `async def`.
+Se sua aplicação (de alguma forma) não tem que se comunicar com nada mais e esperar que o respondam, use `async def`.

 ---

@@ -52,7 +52,7 @@ Se você simplesmente não sabe, use apenas `def`.

 De qualquer forma, em ambos os casos acima, FastAPI irá trabalhar assincronamente e ser extremamente rápido.

-Seguindo os passos acima, ele será capaz de fazer algumas otimizações de performance.
+Mas, seguindo os passos acima, ele será capaz de fazer algumas otimizações de performance.

 ## Detalhes Técnicos

@@ -66,36 +66,36 @@ Vamos ver aquela frase por partes na seção abaixo:

 ## Código assíncrono

-Código assíncrono apenas significa que a linguagem 💬 tem um jeito de dizer para o computador / programa 🤖 que em certo ponto, ele 🤖 terá que esperar por *algo* para finalizar em outro lugar. Vamos dizer que esse *algo* seja chamado "arquivo lento" 📝.
+Código assíncrono apenas significa que a linguagem 💬 tem um jeito de dizer para o computador / programa 🤖 que em certo ponto do código, ele 🤖 terá que esperar *algo* finalizar em outro lugar. Vamos dizer que esse *algo* seja chamado "arquivo lento" 📝.

-Então, durante esse tempo, o computador pode ir e fazer outro trabalho, enquanto o "arquivo lento" 📝 termine.
+Então, durante esse tempo, o computador pode ir e fazer outro trabalho, enquanto o "arquivo lento" 📝 termina.

-Então o computador / programa 🤖 irá voltar toda hora que tiver uma chance porquê ele ainda está esperando o "arquivo lento", ou ele 🤖 nunca irá terminar todo o trabalho que tem até esse ponto. E ele 🤖 irá ver se alguma das tarefas que estava esperando já terminaram, fazendo o que quer que tinham que fazer.
+Então o computador / programa 🤖 irá voltar sempre que tiver uma chance, seja porque ele está esperando novamente, ou quando ele 🤖 terminar todo o trabalho que tem até esse ponto. E ele 🤖 irá ver se alguma das tarefas que estava esperando já terminaram de fazer o que quer que tinham que fazer.

-Depois, ele 🤖 pega a primeira tarefa para finalizar (vamos dizer, nosso "arquivo lento" 📝) e continua o que ele tem que fazer com isso.
+Depois, ele 🤖 pega a primeira tarefa para finalizar (vamos dizer, nosso "arquivo lento" 📝) e continua o que tem que fazer com ela.

-Esse "esperar por algo" normalmente se refere a operações I/O que são relativamente "lentas" (comparadas a velocidade do processador e da memória RAM), como esperar por:
+Esse "esperar por algo" normalmente se refere a operações I/O que são relativamente "lentas" (comparadas à velocidade do processador e da memória RAM), como esperar por:

 * dados do cliente para serem enviados através da rede
-* dados enviados pelo seu programa para serem recebidos pelo clente através da rede
-* conteúdo de um arquivo no disco pra ser lido pelo sistema e entregar ao seu programa
+* dados enviados pelo seu programa serem recebidos pelo clente através da rede
+* conteúdo de um arquivo no disco ser lido pelo sistema e entregue ao seu programa
 * conteúdo que seu programa deu ao sistema para ser escrito no disco
-* uma operação remota API
-* uma operação no banco de dados para finalizar
-* uma solicitação no banco de dados esperando o retorno do resultado
+* uma operação em uma API remota
+* uma operação no banco de dados finalizar
+* uma solicitação no banco de dados retornar o resultado
 * etc.

-Enquanto o tempo de execução é consumido mais pela espera das operações I/O, essas operações são chamadas de operações "limitadas por I/O".
+Quanto o tempo de execução é consumido majoritariamente pela espera de operações I/O, essas operações são chamadas operações "limitadas por I/O".

-Isso é chamado de "assíncrono" porquê o computador / programa não tem que ser "sincronizado" com a tarefa lenta, esperando pelo exato momento que a tarefa finalize, enquanto não faz nada, para ser capaz de pegar o resultado da tarefa e dar continuidade ao trabalho.
+Isso é chamado de "assíncrono" porque o computador / programa não tem que ser "sincronizado" com a tarefa lenta, esperando pelo momento exato em que a tarefa finaliza, enquanto não faz nada, para ser capaz de pegar o resultado da tarefa e dar continuidade ao trabalho.

-Ao invés disso, sendo um sistema "assíncrono", uma vez finalizada, a tarefa pode esperar um pouco (alguns microssegundos) para que o computador / programa finalize o que quer que esteja fazendo,e então volte para pegar o resultado e continue trabalhando com ele.
+Ao invés disso, sendo um sistema "assíncrono", uma vez finalizada, a tarefa pode esperar na fila um pouco (alguns microssegundos) para que o computador / programa finalize o que quer que esteja fazendo, e então volte para pegar o resultado e continue trabalhando com ele.

-Para "síncrono" (contrário de "assíncrono") também é utilizado o termo "sequencial", porquê o computador / programa segue todos os passos, na sequência, antes de trocar para uma tarefa diferente, mesmo se alguns passos envolvam esperar.
+Para "síncrono" (contrário de "assíncrono") também é utilizado o termo "sequencial", porquê o computador / programa segue todos os passos, em sequência, antes de trocar para uma tarefa diferente, mesmo se alguns passos envolvam esperar.

 ### Concorrência e hambúrgueres

-Essa idéia de código **assíncrono** descrito acima é algo às vezes chamado de **"concorrência"**. E é diferente de **"paralelismo"**.
+Essa idéia de código **assíncrono** descrita acima é às vezes chamado de **"concorrência"**. Isso é diferente de **"paralelismo"**.

 **Concorrência** e **paralelismo** ambos são relacionados a "diferentes coisas acontecendo mais ou menos ao mesmo tempo".

@@ -105,117 +105,115 @@ Para ver essa diferença, imagine a seguinte história sobre hambúrgueres:

 ### Hambúrgueres concorrentes

-Você vai com seu _crush_ :heart_eyes: na lanchonete, fica na fila enquanto o caixa pega os pedidos das pessoas na sua frente.
+Você vai com seu _crush_ na lanchonete, e fica na fila enquanto o caixa pega os pedidos das pessoas na sua frente. 😍

-Então chega a sua vez, você pede dois saborosos hambúrgueres para você e seu _crush_ :heart_eyes:.
+Então chega a sua vez, você pede dois saborosos hambúrgueres para você e seu _crush_.  🍔🍔

-Você paga.
+O caixa diz alguma coisa para o cozinheiro na cozinha para que eles saivam que têm que preparar seus hambúrgueres (mesmo que ele esteja atualmente preparando os lanches dos outros clientes).

-O caixa diz alguma coisa para o cara na cozinha para que ele tenha que preparar seus hambúrgueres (mesmo embora ele esteja preparando os lanches dos outros clientes).
+Você paga. 💸

 O caixa te entrega seu número de chamada.

-Enquanto você espera, você vai com seu _crush_ :heart_eyes: e pega uma mesa, senta e conversa com seu _crush_ :heart_eyes: por um bom tempo (como seus hambúrgueres são muito saborosos, leva um tempo para serem preparados).
+Enquanto você espera, você vai com seu _crush_ e pega uma mesa, senta e conversa com seu _crush_ por um bom tempo (já que seus hambúrgueres são muito saborosos, e leva um tempo para serem preparados).

-Enquanto você está sentado na mesa com seu _crush_ :heart_eyes:, esperando os hambúrgueres, você pode gastar o tempo admirando como lindo, maravilhoso e esperto é seu _crush_ :heart_eyes:.
+Já que você está sentado na mesa com seu _crush_, esperando os hambúrgueres, você pode passar esse tempo admirando o quão lindo, maravilhoso e esperto é seu _crush_ ✨😍✨.

-Enquanto espera e conversa com seu _crush_ :heart_eyes:, de tempos em tempos, você verifica o número de chamada exibido no balcão para ver se já é sua vez.
+Enquanto espera e conversa com seu _crush_, de tempos em tempos, você verifica o número da chamada exibido no balcão para ver se já é sua vez.

-Então a certo ponto, é finalmente sua vez. Você vai no balcão, pega seus hambúrgueres e volta para a mesa.
+Então em algum momento, é finalmente sua vez. Você vai ao balcão, pega seus hambúrgueres e volta para a mesa.

-Você e seu _crush_ :heart_eyes: comem os hambúrgueres e aproveitam o tempo.
+Você e seu _crush_ comem os hambúrgueres e aproveitam o tempo. ✨

 ---

-Imagine que você seja o computador  / programa nessa história.
+Imagine que você seja o computador / programa nessa história.

-Enquanto você está na fila, tranquilo, esperando por sua vez, não está fazendo nada "produtivo". Mas a fila é rápida porquê o caixa só está pegando os pedidos, então está tudo bem.
+Enquanto você está na fila, você está somente ocioso 😴, esperando por sua vez, sem fazer nada muito "produtivo". Mas a fila é rápida porque o caixa só está pegando os pedidos (não os preparando), então está tudo bem.

-Então, quando é sua vez, você faz o trabalho "produtivo" de verdade, você processa o menu, decide o que quer, pega a escolha de seu _crush_ :heart_eyes:, paga, verifica se entregou o valor correto em dinheiro ou cartão de crédito, verifica se foi cobrado corretamente, verifica se seu pedido está correto etc.
+Então, quando é sua vez, você faz trabalho realmente "produtivo", você processa o menu, decide o que quer, pega a escolha de seu _crush_, paga, verifica se entregou o cartão ou a cédula correta, verifica se foi cobrado corretamente, verifica se seu pedido está correto etc.

-Mas então, embora você ainda não tenha os hambúrgueres, seu trabalho no caixa está "pausado", porquê você tem que esperar seus hambúrgueres estarem prontos.
+Mas então, embora você ainda não tenha os hambúrgueres, seu trabalho no caixa está "pausado" ⏸, porque você tem que esperar 🕙 seus hambúrgueres ficarem prontos.

-Mas enquanto você se afasta do balcão e senta na mesa com o número da sua chamada, você pode trocar sua atenção para seu _crush_ :heart_eyes:, e "trabalhar" nisso. Então você está novamente fazendo algo muito "produtivo", como flertar com seu _crush_ :heart_eyes:.
+Contudo, à medida que você se afasta do balcão e senta na mesa, com um número para sua chamada, você pode trocar 🔀 sua atenção para seu _crush_, e "trabalhar" ⏯ 🤓 nisso. Então você está novamente fazendo algo muito "produtivo", como flertar com seu _crush_ 😍.

-Então o caixa diz que "seus hambúrgueres estão prontos" colocando seu número no balcão, mas você não corre que nem um maluco imediatamente quando o número exibido é o seu. Você sabe que ninguém irá roubar seus hambúrgueres porquê você tem o número de chamada, e os outros tem os números deles.
+Então o caixa 💁 diz que "seus hambúrgueres estão prontos" colocando seu número no balcão, mas você não corre que nem um maluco imediatamente quando o número exibido é o seu. Você sabe que ninguém irá roubar seus hambúrgueres porque você tem o seu número da chamada, e os outros têm os deles.

-Então você espera que seu _crush_ :heart_eyes: termine a história que estava contando (terminar o trabalho atual / tarefa sendo processada), sorri gentilmente e diz que você está indo buscar os hambúrgueres.
+Então você espera seu _crush_ terminar a história que estava contando (terminar o trabalho atual ⏯ / tarefa sendo processada 🤓), sorri gentilmente e diz que você está indo buscar os hambúrgueres.

-Então você vai no balcão, para a tarefa inicial que agora está finalizada, pega os hambúrgueres, e leva para a mesa. Isso finaliza esse passo / tarefa da interação com o balcão. Agora é criada uma nova tarefa, "comer hambúrgueres", mas a tarefa anterior, "pegar os hambúrgueres" já está finalizada.
+Então você vai ao balcão 🔀, para a tarefa inicial que agora está finalizada⏯, pega os hambúrgueres, agradece, e leva-os para a mesa. Isso finaliza esse passo / tarefa da interação com o balcão ⏹. Isso, por sua vez, cria uma nova tarefa, a de "comer hambúrgueres" 🔀 ⏯, mas a tarefa anterior de "pegar os hambúrgueres" já está finalizada ⏹.

 ### Hambúrgueres paralelos

-Você vai com seu _crush_ :heart_eyes: em uma lanchonete paralela.
+Agora vamos imaginar que esses não são "Hambúrgueres Concorrentes", e sim "Hambúrgueres Paralelos"

-Você fica na fila enquanto alguns (vamos dizer 8) caixas pegam os pedidos das pessoas na sua frente.
+Você vai com seu _crush_ na lanchonete paralela.

-Todo mundo antes de você está esperando pelos hambúrgueres estarem prontos antes de deixar o caixa porquê cada um dos 8 caixas vai e prepara o hambúrguer antes de pegar o próximo pedido.
+Você fica na fila enquanto vários (vamos dizer 8) caixas que também são cozinheiros pegam os pedidos das pessoas na sua frente.

-Então é finalmente sua vez, e pede 2 hambúrgueres muito saborosos para você e seu _crush_ :heart_eyes:.
+Todo mundo na sua frente está esperando seus hambúrgueres ficarem prontos antes de deixar o caixa porque cada um dos 8 caixas vai e prepara o hambúrguer logo após receber o pedido, antes de pegar o próximo pedido.

-Você paga.
+Então é finalmente sua vez, você pede 2 hambúrgueres muito saborosos para você e seu _crush_.
+
+Você paga 💸.

 O caixa vai para a cozinha.

-Você espera, na frente do balcão, para que ninguém pegue seus hambúrgueres antes de você, já que não tem números de chamadas.
+Você espera, na frente do balcão 🕙, para que ninguém pegue seus hambúrgueres antes de você, já que não tem números de chamadas.

-Enquanto você e seu _crush_ :heart_eyes: estão ocupados não permitindo que ninguém passe a frente e pegue seus hambúrgueres assim que estiverem prontos, você não pode dar atenção ao seu _crush_ :heart_eyes:.
+Como você e seu _crush_ estão ocupados não permitindo que ninguém passe na frente e pegue seus hambúrgueres assim que estiverem prontos, você não pode dar atenção ao seu _crush_. 😞

-Isso é trabalho "síncrono", você está "sincronizado" com o caixa / cozinheiro. Você tem que esperar e estar lá no exato momento que o caixa / cozinheiro terminar os hambúrgueres e dá-los a você, ou então, outro alguém pode pegá-los.
+Isso é trabalho "síncrono", você está "sincronizado" com o caixa / cozinheiro👨🍳. Você tem que esperar 🕙 e estar lá no exato momento que o caixa / cozinheiro 👨🍳 terminar os hambúrgueres e os der a você, ou então, outro alguém pode pegá-los.

-Então seu caixa / cozinheiro finalmente volta com seus hambúrgueres, depois de um longo tempo esperando por eles em frente ao balcão.
+Então seu caixa / cozinheiro 👨🍳 finalmente volta com seus hambúrgueres, depois de um longo tempo esperando 🕙 por eles em frente ao balcão.

-Você pega seus hambúrgueres e vai para a mesa com seu _crush_ :heart_eyes:.
+Você pega seus hambúrgueres e vai para a mesa com seu _crush_.

-Vocês comem os hambúrgueres, e o trabalho está terminado.
+Vocês comem os hambúrgueres, e o trabalho está terminado. ⏹

-Não houve muita conversa ou flerte já que a maior parte do tempo foi gasto esperando os lanches na frente do balcão.
+Não houve muita conversa ou flerte já que a maior parte do tempo foi gasto esperando 🕙 na frente do balcão. 😞

 ---

-Nesse cenário dos hambúrgueres paralelos, você é um computador / programa com dois processadores (você e seu _crush_ :heart_eyes:), ambos esperando e dedicando a atenção de estar "esperando no balcão" por um bom tempo.
+Nesse cenário dos hambúrgueres paralelos, você é um computador / programa com dois processadores (você e seu _crush_), ambos esperando 🕙 e dedicando sua atenção ⏯ "esperando no balcão" 🕙 por um bom tempo.

-A lanchonete paralela tem 8 processadores (caixas / cozinheiros). Enquanto a lanchonete dos hambúrgueres concorrentes tinham apenas 2 (um caixa e um cozinheiro).
+A lanchonete paralela tem 8 processadores (caixas / cozinheiros), enquanto a lanchonete dos hambúrgueres concorrentes tinha apenas 2 (um caixa e um cozinheiro).

-Ainda assim, a última experiência não foi a melhor.
+Ainda assim, a experiência final não foi a melhor. 😞

 ---

-Essa poderia ser a história paralela equivalente aos hambúrgueres.
+Essa seria o equivalente paralelo à histório dos hambúrgueres. 🍔

 Para um exemplo "mais real", imagine um banco.

-Até recentemente, a maioria dos bancos tinha muitos caixas e uma grande fila.
+Até recentemente, a maioria dos bancos tinham muitos caixas 👨💼👨💼👨💼👨💼 e uma grande fila 🕙🕙🕙🕙🕙🕙🕙🕙.

-Todos os caixas fazendo todo o trabalho, um cliente após o outro.
+Todos os caixas fazendo todo o trabalho, um cliente após o outro 👨💼⏯.

-E você tinha que esperar na fila por um longo tempo ou poderia perder a vez.
+E você tinha que esperar 🕙 na fila por um longo tempo ou poderia perder a vez.

-Você provavelmente não gostaria de levar seu _crush_ :heart_eyes: com você para um rolezinho no banco.
+Você provavelmente não gostaria de levar seu _crush_ 😍 com você para um rolezinho no banco 🏦.

 ### Conclusão dos hambúrgueres

-Nesse cenário dos "hambúrgueres com seu _crush_ :heart_eyes:", como tem muita espera, faz mais sentido ter um sistema concorrente.
+Nesse cenário dos "hambúrgueres com seu _crush_", como tem muita espera, faz mais sentido ter um sistema concorrente ⏸🔀⏯.

 Esse é o caso da maioria das aplicações web.

-Geralmente são muitos usuários, e seu servidor está esperando pelas suas conexões não tão boas para enviar as requisições.
-
-E então esperando novamente pelas respostas voltarem.
-
-Essa "espera" é medida em microssegundos, e ainda assim, somando tudo, é um monte de espera no final.
+Muitos, muitos usuários, mas seu servidor está esperando 🕙 pela sua conexão não tão boa enviar suas requisições.

-Por isso que faz muito mais sentido utilizar código assíncrono para APIs web.
+E então esperando 🕙 novamente as respostas voltarem.

-A maioria dos frameworks Python existentes mais populares (incluindo Flask e Django) foram criados antes que os novos recursos assíncronos existissem em Python. Então, os meios que eles podem ser colocados em produção para suportar execução paralela mais a forma antiga de execução assíncrona não são tão poderosos quanto as novas capacidades.
+Essa "espera" 🕙 é medida em microssegundos, mas ainda assim, somando tudo, é um monte de espera no final.

-Mesmo embora a especificação principal para web assíncrono em Python (ASGI) foi desenvolvida no Django, para adicionar suporte para WebSockets.
+Por isso que faz bastante sentido utilizar código assíncrono ⏸🔀⏯ para APIs web.

-Esse tipo de assincronicidade é o que fez NodeJS popular (embora NodeJS não seja paralelo) e que essa seja a força do Go como uma linguagem de programa.
+Esse tipo de assincronicidade é o que fez NodeJS popular (embora NodeJS não seja paralelo) e essa é a força do Go como uma linguagem de programação.

 E esse é o mesmo nível de performance que você tem com o **FastAPI**.

-E como você pode ter paralelismo e sincronicidade ao mesmo tempo, você tem uma maior performance do que a maioria dos frameworks NodeJS testados e lado a lado com Go, que é uma linguagem compilada próxima ao C (tudo graças ao Starlette).
+E como você pode ter paralelismo e assincronicidade ao mesmo tempo, você tem uma maior performance do que a maioria dos frameworks NodeJS testados e lado a lado com Go, que é uma linguagem compilada, mais próxima ao C (tudo graças ao Starlette).

 ### Concorrência é melhor que paralelismo?

@@ -225,64 +223,64 @@ Concorrência é diferente de paralelismo. E é melhor em cenários **específic

 Então, para equilibrar tudo, imagine a seguinte historinha:

-> Você tem que limpar uma grande casa suja.
+> Você tem que limpar uma casa grande e suja.

 *Sim, essa é toda a história*.

 ---

-Não há espera em lugar algum, apenas um monte de trabalho para ser feito, em múltiplos cômodos da casa.
+Não há espera 🕙 em lugar algum, apenas um monte de trabalho para ser feito, em múltiplos cômodos da casa.

-Você poderia ter chamadas como no exemplo dos hambúrgueres, primeiro a sala de estar, então a cozinha, mas você não está esperando por nada, apenas limpar e limpar, as chamadas não afetariam em nada.
+Você poderia ter turnos como no exemplo dos hambúrgueres, primeiro a sala de estar, então a cozinha, mas como você não está esperando por nada, apenas limpando e limpando, as chamadas não afetariam em nada.

-Levaria o mesmo tempo para finalizar com ou sem chamadas (concorrência) e você teria feito o mesmo tanto de trabalho.
+Levaria o mesmo tempo para finalizar com ou sem turnos (concorrência) e você teria feito o mesmo tanto de trabalho.

 Mas nesse caso, se você trouxesse os 8 ex-caixas / cozinheiros / agora-faxineiros, e cada um deles (mais você) pudessem dividir a casa para limpá-la, vocês fariam toda a limpeza em **paralelo**, com a ajuda extra, e terminariam muito mais cedo.

 Nesse cenário, cada um dos faxineiros (incluindo você) poderia ser um processador, fazendo a sua parte do trabalho.

-E a maior parte do tempo de execução é tomada por trabalho (ao invés de ficar esperando), e o trabalho em um computador é feito pela CPU, que podem gerar problemas que são chamados de "limite de CPU".
+E a maior parte do tempo de execução é tomada por trabalho real (ao invés de ficar esperando), e o trabalho em um computador é feito pela CPU. Eles chamam esses problemas de "limitados por CPU".

 ---

-Exemplos comuns de limite de CPU são coisas que exigem processamento matemático complexo.
+Exemplos comuns de operações limitadas por CPU são coisas que exigem processamento matemático complexo.

 Por exemplo:

 * **Processamento de áudio** ou **imagem**
-* **Visão do Computador**: uma imagem é composta por milhões de pixels, cada pixel tem 3 valores (cores, processamento que normalmente exige alguma computação em todos esses pixels ao mesmo tempo)
+* **Visão Computacional**: uma imagem é composta por milhões de pixels, cada pixel tem 3 valores / cores, processar isso normalmente exige alguma computação em todos esses pixels ao mesmo tempo

-* **[NAME_REDACTED]**: Normalmente exige muita multiplicação de matrizes e vetores. Pense numa grande folha de papel com números e multiplicando todos eles juntos e ao mesmo tempo.
+* **[NAME_REDACTED]**: Normalmente exige muita multiplicação de matrizes e vetores. Pense numa grande planilha com números e em multiplicar todos eles juntos e ao mesmo tempo.

-* **[NAME_REDACTED]**: Esse é um subcampo do [NAME_REDACTED], então o mesmo se aplica. A diferença é que não há apenas uma grande folha de papel com números para multiplicar, mas um grande conjunto de folhas de papel, e em muitos casos, você utiliza um processador especial para construir e/ou usar modelos.
+* **[NAME_REDACTED]**: Esse é um subcampo do [NAME_REDACTED], então, o mesmo se aplica. A diferença é que não há apenas uma grande planilha com números para multiplicar, mas um grande conjunto delas, e em muitos casos, você utiliza um processador especial para construir e/ou usar esses modelos.

 ### Concorrência + Paralelismo: Web + Machine learning

 Com **FastAPI** você pode levar a vantagem da concorrência que é muito comum para desenvolvimento web (o mesmo atrativo de NodeJS).

-Mas você também pode explorar os benefícios do paralelismo e multiprocessamento (tendo múltiplos processadores rodando em paralelo) para trabalhos pesados que geram **limite de CPU** como aqueles em sistemas de [NAME_REDACTED].
+Mas você também pode explorar os benefícios do paralelismo e multiprocessamento (tendo múltiplos processadores rodando em paralelo) para trabalhos **limitados por CPU** como aqueles em sistemas de [NAME_REDACTED].

-Isso, mais o simples fato que Python é a principal linguagem para **[NAME_REDACTED]**, [NAME_REDACTED] e especialmente [NAME_REDACTED], faz do FastAPI uma ótima escolha para APIs web e aplicações com [NAME_REDACTED] / [NAME_REDACTED] (entre muitas outras).
+Isso, somado ao simples fato que Python é a principal linguagem para **[NAME_REDACTED]**, [NAME_REDACTED] e especialmente [NAME_REDACTED], faz do FastAPI uma ótima escolha para APIs web e aplicações com [NAME_REDACTED] / [NAME_REDACTED] (entre muitas outras).

 Para ver como alcançar esse paralelismo em produção veja a seção sobre [Deployment](deployment/index.md){.internal-link target=_blank}.

 ## `async` e `await`

-Versões modernas do Python tem um modo muito intuitivo para definir código assíncrono. Isso faz parecer normal o código "sequencial" e fazer o "esperar" para você nos momentos certos.
+Versões modernas do Python têm um modo muito intuitivo para definir código assíncrono. Isso faz parecer do mesmo jeito do código normal "sequencial" e fazer a "espera" para você nos momentos certos.

-Quando tem uma operação que exigirá espera antes de dar os resultados e tem suporte para esses recursos Python, você pode escrever assim:
+Quando tem uma operação que exigirá espera antes de dar os resultados e tem suporte para esses novos recursos do Python, você pode escrever assim:

 ```Python
 burgers = await get_burgers(2)
 ```

-A chave aqui é o `await`. Ele diz ao Python que ele tem que esperar por `get_burgers(2)` para finalizar suas coisas antes de armazenar os resultados em `burgers`. Com isso, o Python saberá que ele pode ir e fazer outras coisas nesse meio tempo (como receber outra requisição).
+A chave aqui é o `await`. Ele diz ao Python que ele tem que esperar por `get_burgers(2)` finalizar suas coisas 🕙 antes de armazenar os resultados em `burgers`. Com isso, o Python saberá que ele pode ir e fazer outras coisas 🔀 ⏯ nesse meio tempo (como receber outra requisição).

 Para o `await` funcionar, tem que estar dentro de uma função que suporte essa assincronicidade. Para fazer isso, apenas declare a função com `async def`:

 ```Python hl_lines="1"
 async def get_burgers(number: int):
-    # Fazer alguma coisa assíncrona para criar os hambúrgueres
+    # Faz alguma coisa assíncrona para criar os hambúrgueres
     return burgers
 ```

@@ -295,9 +293,9 @@ def get_sequential_burgers(number: int):
     return burgers
 ```

-Com `async def`, o Python sabe que, dentro dessa função, tem que estar ciente das expressões `await`, e que isso pode "pausar" a execução dessa função, e poderá fazer outra coisa antes de voltar.
+Com `async def`, o Python sabe que, dentro dessa função, ele deve estar ciente das expressões `await`, e que isso poderá "pausar" ⏸ a execução dessa função, e ir fazer outra coisa 🔀 antes de voltar.

-Quando você quiser chamar uma função `async def`, você tem que "esperar". Então, isso não funcionará:
+Quando você quiser chamar uma função `async def`, você tem que "esperar" ela. Então, isso não funcionará:

 ```Python
 # Isso não irá funcionar, porquê get_burgers foi definido com: async def
@@ -319,13 +317,24 @@ async def read_burgers():

 Você deve ter observado que `await` pode ser usado somente dentro de funções definidas com `async def`.

-Mas ao mesmo tempo, funções definidas com `async def` tem que ser aguardadas. Então, funções com `async def` pdem ser chamadas somente dentro de funções definidas com `async def` também.
+Mas ao mesmo tempo, funções definidas com `async def` têm que ser "aguardadas". Então, funções com `async def` pdem ser chamadas somente dentro de funções definidas com `async def` também.

 Então, sobre o ovo e a galinha, como você chama a primeira função async?

 Se você estivar trabalhando com **FastAPI** não terá que se preocupar com isso, porquê essa "primeira" função será a sua *função de operação de rota*, e o FastAPI saberá como fazer a coisa certa.

-Mas se você quiser usar `async` / `await` sem FastAPI, verifique a documentação oficial Python.
+Mas se você quiser usar `async` / `await` sem FastAPI, você também pode fazê-lo.
+
+### Escreva seu próprio código assíncrono
+
+Starlette (e **FastAPI**) são baseados no AnyIO, o que o torna compatível com ambos o asyncio da biblioteca padrão do Python, e o Trio.
+
+Em particular, você pode usar diretamente o AnyIO para seus casos de uso avançados de concorrência que requerem padrões mais avançados no seu próprio código.
+
+E até se você não estiver utilizando FastAPI, você também pode escrever suas próprias aplicações assíncronas com o AnyIO por ser altamente compatível e ganhar seus benefícios (e.g. *concorrência estruturada*).
+
+Eu criei outra biblioteca em cima do AnyIO, como uma fina camada acima, para melhorar um pouco as anotações de tipo e obter melhor **autocompletar**, **erros de linha**, etc. Ela também possui uma introdução amigável e um tutorial para ajudar você a **entender** e escrever **seu próprio código async**: Asyncer. Seria particularmente útil se você precisar **combinar código async com código regular** (bloqueador/síncrono).
+

 ### Outras formas de código assíncrono

@@ -337,25 +346,25 @@ Essa mesma sintaxe (ou quase a mesma) foi também incluída recentemente em vers

 Mas antes disso, controlar código assíncrono era bem mais complexo e difícil.

-Nas versões anteriores do Python, você poderia utilizar threads ou Gevent. Mas o código é um pouco mais complexo de entender, debugar, e pensar sobre.
+Nas versões anteriores do Python, você poderia utilizar threads ou Gevent. Mas o código é bem mais complexo de entender, debugar, e pensar sobre.

-Nas versões anteriores do NodeJS / [NAME_REDACTED], você poderia utilizar "callbacks". O que leva ao  inferno do callback.
+Nas versões anteriores do NodeJS / [NAME_REDACTED], você utilizaria "callbacks". O que leva ao  inferno do callback.

 ## Corrotinas

-**Corrotina** é apenas um jeito bonitinho para a coisa que é retornada de uma função `async def`. O Python sabe que é uma função que pode começar e terminar em algum ponto, mas que pode ser pausada internamente também, sempre que tiver um `await` dentro dela.
+**Corrotina** é apenas um jeito bonitinho para a coisa que é retornada de uma função `async def`. O Python sabe que é algo como uma função, que pode começar e que vai terminar em algum ponto, mas que pode ser pausada ⏸ internamente também, sempre que tiver um `await` dentro dela.

-Mas toda essa funcionalidade de código assíncrono com `async` e `await` é muitas vezes resumida como "corrotina". É comparável ao principal recurso chave do Go, a "Gorotina".
+Mas toda essa funcionalidade de código assíncrono com `async` e `await` é muitas vezes resumida como usando "corrotinas". É comparável ao principal recurso chave do Go, a "Gorrotina".

 ## Conclusão

-Vamos ver a mesma frase com o conteúdo cima:
+Vamos ver a mesma frase de cima:

-> Versões modernas do Python tem suporte para **"código assíncrono"** usando algo chamado **"corrotinas"**, com sintaxe **`async` e `await`**.
+> Versões modernas do Python têm suporte para **"código assíncrono"** usando algo chamado **"corrotinas"**, com sintaxe **`async` e `await`**.

-Isso pode fazer mais sentido agora.
+Isso pode fazer mais sentido agora. ✨

-Tudo isso é o que deixa o FastAPI poderoso (através do Starlette) e que o faz ter uma performance impressionante.
+Tudo isso é o que empodera o FastAPI (através do Starlette) e que o faz ter uma performance tão impressionante.

 ## Detalhes muito técnicos

@@ -365,25 +374,25 @@ Você pode provavelmente pular isso.

 Esses são detalhes muito técnicos de como **FastAPI** funciona por baixo do capô.

-Se você tem algum conhecimento técnico (corrotinas, threads, blocking etc) e está curioso sobre como o FastAPI controla o `async def` vs normal `def`, vá em frente.
+Se você tem certo conhecimento técnico (corrotinas, threads, blocking etc) e está curioso sobre como o FastAPI controla o `async def` vs normal `def`, vá em frente.

 ///

 ### Funções de operação de rota

-Quando você declara uma *função de operação de rota* com `def` normal ao invés de `async def`, ela é rodada em uma threadpool externa que então é aguardada, ao invés de ser chamada diretamente (ela poderia bloquear o servidor).
+Quando você declara uma *função de operação de rota* com `def` normal ao invés de `async def`, ela é rodada em uma threadpool externa que é então aguardada, ao invés de ser chamada diretamente (já que ela bloquearia o servidor).

-Se você está chegando de outro framework assíncrono que não faz o trabalho descrito acima e você está acostumado a definir triviais *funções de operação de rota* com simples `def` para ter um mínimo ganho de performance (cerca de 100 nanosegundos), por favor observe que no **FastAPI** o efeito pode ser bem o oposto. Nesses casos, é melhor usar `async def` a menos que suas *funções de operação de rota* utilizem código que performem bloqueamento IO.
+Se você está chegando de outro framework assíncrono que não funciona como descrito acima e você está acostumado a definir *funções de operação de rota* triviais somente de computação com simples `def` para ter um mínimo ganho de performance (cerca de 100 nanosegundos), por favor observe que no **FastAPI** o efeito pode ser bem o oposto. Nesses casos, é melhor usar `async def` a menos que suas *funções de operação de rota* utilizem código que performe bloqueamento IO.

-Ainda, em ambas as situações, as chances são que o **FastAPI** será [ainda mais rápido](index.md#performance){.internal-link target=_blank} do que (ou ao menos comparável a) seus frameworks antecessores.
+Ainda, em ambas as situações, as chances são que o **FastAPI** [ainda será mais rápido](index.md#performance){.internal-link target=_blank} do que (ou ao menos comparável a) seu framework anterior.

 ### Dependências

-O mesmo se aplica para as dependências. Se uma dependência tem as funções com padrão `def` ao invés de `async def`, ela é rodada no threadpool externo.
+O mesmo se aplica para as [dependências](tutorial/dependencies/index.md){.internal-link target=_blank}. Se uma dependência tem as funções com padrão `def` ao invés de `async def`, ela é rodada no threadpool externo.

 ### Sub-dependências

-Você pode ter múltiplas dependências e sub-dependências exigindo uma a outra (como parâmetros de definições de funções), algumas delas podem ser criadas com `async def` e algumas com `def` normal. Isso ainda poderia funcionar, e aquelas criadas com `def` podem ser chamadas em uma thread externa ao invés de serem "aguardadas".
+Você pode ter múltiplas dependências e [sub-dependências](tutorial/dependencies/sub-dependencies.md){.internal-link target=_blank} requisitando uma à outra (como parâmetros de definições de funções), algumas delas podem ser criadas com `async def` e algumas com `def` normal. Isso ainda funcionaria, e aquelas criadas com `def` normal seriam chamadas em uma thread externa (do threadpool) ao invés de serem "aguardadas".

 ### Outras funções de utilidade

@@ -395,6 +404,6 @@ Se sua função de utilidade é uma função normal com `def`, ela será chamada

 ---

-Novamente, esses são detalhes muito técnicos que provavelmente possam ser úteis caso você esteja procurando por eles.
+Novamente, esses são detalhes muito técnicos que provavelmente seriam úteis caso você esteja procurando por eles.

 Caso contrário, você deve ficar bem com as dicas da seção acima: Com pressa?.

Well done, we need to keep maintaining the translated documentation updated and as good as the original one, written in English.

Thanks, [USER_REDACTED], for your contribution and dedication to this project.

Just a few typos 🚀

just a typo here:

"esperando pelo momento **extato** em" should be "esperando pelo momento exato em"

"Todo mundo na sua frente **está** esperando seus hambúrgueres **ficarem** prontos antes de deixar o caixa, porque cada um dos 8 caixas vai e prepara o hambúrguer logo após receber o pedido, antes de pegar o próximo pedido.

Thank you!!


🌐 Add Russian translation for `docs/ru/docs/advanced/response-directly.md`

@@ -0,0 +1,65 @@
+# Возврат ответа напрямую
+
+Когда вы создаёте **FastAPI** *операцию пути*, вы можете возвращать из неё любые данные: `dict`, `list`, Pydantic-модель, модель базы данных и т.д.
+
+По умолчанию **FastAPI** автоматически преобразует возвращаемое значение в JSON с помощью `jsonable_encoder`, как описано в [JSON кодировщик](../tutorial/encoder.md){.internal-link target=_blank}.
+
+Затем "под капотом" эти данные, совместимые с JSON (например `dict`), помещаются в `JSONResponse`, который используется для отправки ответа клиенту.
+
+Но вы можете возвращать `JSONResponse` напрямую из ваших *операций пути*.
+
+Это может быть полезно, например, если нужно вернуть пользовательские заголовки или куки.
+
+## Возврат `Response`
+
+На самом деле, вы можете возвращать любой объект `Response` или его подкласс.
+
+/// tip | Подсказка
+
+`JSONResponse` сам по себе является подклассом `Response`.
+
+///
+
+И когда вы возвращаете `Response`, **FastAPI** передаст его напрямую.
+
+Это не приведет к преобразованию данных с помощью Pydantic-моделей, содержимое не будет преобразовано в какой-либо тип и т.д.
+
+Это даёт вам большую гибкость. Вы можете возвращать любые типы данных, переопределять любые объявления или валидацию данных и т.д.
+
+## Использование `jsonable_encoder` в `Response`
+
+Поскольку **FastAPI** не изменяет объект `Response`, который вы возвращаете, вы должны убедиться, что его содержимое готово к отправке.
+
+Например, вы не можете поместить Pydantic-модель в `JSONResponse`, не преобразовав её сначала в `dict` с помощью преобразования всех типов данных (таких как `datetime`, `UUID` и т.д.) в совместимые с JSON типы.
+
+В таких случаях вы можете использовать `jsonable_encoder` для преобразования данных перед передачей их в ответ:
+
+{* ../../docs_src/response_directly/tutorial001.py hl[6:7,21:22] *}
+
+/// note | Технические детали
+
+Вы также можете использовать `from starlette.responses import JSONResponse`.
+
+**FastAPI** предоставляет `starlette.responses` через `fastapi.responses` просто для вашего удобства, как разработчика. Но большинство доступных Response-классов поступают напрямую из Starlette.
+
+///
+
+## Возврат пользовательского `Response`
+
+Пример выше показывает все необходимые части, но он пока не очень полезен, так как вы могли бы просто вернуть `item` напрямую, и **FastAPI** поместил бы его в `JSONResponse`, преобразовав в `dict` и т.д. Всё это происходит по умолчанию.
+
+Теперь давайте посмотрим, как можно использовать это для возврата пользовательского ответа.
+
+Допустим, вы хотите вернуть ответ в формате XML.
+
+Вы можете поместить ваш XML-контент в строку, поместить её в `Response` и вернуть:
+
+{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
+
+## Примечания
+
+Когда вы возвращаете объект `Response` напрямую, его данные не валидируются, не преобразуются (не сериализуются) и не документируются автоматически.
+
+Но вы всё равно можете задокументировать это, как описано в [Дополнительные ответы в OpenAPI](additional-responses.md){.internal-link target=_blank}.
+
+В следующих разделах вы увидите, как использовать/объявлять такие кастомные `Response`, при этом сохраняя автоматическое преобразование данных, документацию и т.д.

```suggestion
**FastAPI** предоставляет `starlette.responses` через `fastapi.responses` просто для вашего удобства, как разработчика. Но большинство доступных Response-классов поступают напрямую из Starlette.
```

Just a suggestion. What do you think?

That makes more sense, thank you

> Но большинство доступных ответов поступают напрямую из Starlette.

I though you accepted my suggestion and going to change it, but it's still unchanged.
Will you change it? Or would you like to leave it as it is?


🌐 Add Russian translation for `docs/ru/docs/advanced/additional-status-codes.md`

@@ -0,0 +1,41 @@
+# Дополнительные статус коды
+
+По умолчанию **FastAPI** возвращает ответы, используя `JSONResponse`, помещая содержимое, которое вы возвращаете из вашей *операции пути*, внутрь этого `JSONResponse`.
+
+Он будет использовать код статуса по умолчанию или тот, который вы укажете в вашей *операции пути*.
+
+## Дополнительные статус коды
+
+Если вы хотите возвращать дополнительный статус код помимо основного, вы можете сделать это, возвращая объект `Response` напрямую, как `JSONResponse`, и устанавливая нужный статус код напрямую.
+
+Например, скажем, вы хотите создать *операцию пути*, которая позволяет обновлять элементы и возвращает HTTP-код 200 "OK" при успешном выполнении.
+
+Но вы также хотите, чтобы она принимала новые элементы. И если элемент ранее не существовал, он создаётся, и возвращался HTTP-код 201 "Created".
+
+Чтобы реализовать это, импортируйте `JSONResponse` и возвращайте ваш контент напрямую, устанавливая нужный `status_code`:
+
+{* ../../docs_src/additional_status_codes/tutorial001_an_py310.py hl[4,25] *}
+
+/// warning | Внимание
+
+Когда вы возвращаете объект `Response` напрямую, как в примере выше, он будет возвращён как есть.
+
+Он не будет сериализован при помощи модели и т.д.
+
+Убедитесь, что в нём содержатся именно те данные, которые вы хотите, и что значения являются валидным JSON (если вы используете `JSONResponse`).
+
+///
+
+/// note | Технические детали
+
+Вы также можете использовать `from starlette.responses import JSONResponse`.
+
+**FastAPI** предоставляет тот же `starlette.responses` через `fastapi.responses` просто для вашего удобства, как разработчика. Но большинство доступных Response-классов поступают напрямую из Starlette. То же самое касается и `status`.
+
+///
+
+## OpenAPI и документация API
+
+Если вы возвращаете дополнительные коды статусов и ответы напрямую, они не будут включены в схему OpenAPI (документацию API), потому что FastAPI не может заранее знать, что вы собираетесь вернуть.
+
+Но вы можете задокументировать это в вашем коде, используя: [Дополнительные ответы в OpenAPI](additional-responses.md){.internal-link target=_blank}.

```suggestion
**FastAPI** предоставляет тот же `starlette.responses` через `fastapi.responses` просто для вашего удобства, как разработчика. Но большинство доступных Response-классов поступают напрямую из Starlette. То же самое касается и `status`.
```
I think "responses" shouldn't be translated here, better change it to "Response-классы" or something like this to make it clear. What do you think?

That makes more sense, thank you