🌐 Add Russian translation for `docs/ru/docs/virtual-environments.md`

New translation to Russian language added: docs/ru/docs/virtual-environments.md

[USER_REDACTED], [USER_REDACTED], [USER_REDACTED], [USER_REDACTED] please have a look and leave a review if you have time. :slightly_smiling_face:

Thanks!

@@ -0,0 +1,839 @@
+# Виртуальная среда
+
+При работе с проектами в Python рекомендуется использовать **виртуальную среду разработки** (или какой-нибудь другой подобный механизм). Это нужно для того, чтобы изолировать устанавливаемые пакеты для каждого отдельного проекта.
+
+/// info | Дополнительная информация
+
+Если вы уже знакомы с виртуальными средами разработки, знаете как их создавать и использовать, то вы можете свободно пропустить данный раздел. 🤓
+
+///
+
+/// tip | Подсказка
+
+**Виртуальная среда** и **переменная окружения** это две разные вещи.
+
+**Переменная окружения** это системная переменная, которую могут использовать программы.
+
+**Виртуальная среда** это папка, содержащая файлы.
+
+///
+
+/// info | Дополнительная информация
+
+В этом разделе мы научим вас пользоваться виртуальными средами разработки и расскажем, как они работают.
+
+Если же вы готовы воспользоваться инструментом, **который умеет управлять всем, что касается Python-проектов**,
+(включая установку Python), то попробуйте uv.
+
+///
+
+## Создание проекта
+
+В первую очередь, создайте директорию для вашего проекта.
+
+Я обычно создаю папку под названием `code` внутри моего домашнего каталога `/home/user`.
+
+Затем внутри данной папки я создаю отдельную директорию под каждый свой проект.
+
+

+
+```console
+// Перейдите в домашний каталог
+$ cd
+// Создайте отдельную папку под все будущие программные проекты (code)
+$ mkdir code
+// Войдите в директорию code
+$ cd code
+// Создайте директрорию под данный проект (awesome-project)
+$ mkdir awesome-project
+// Перейдите в созданную директорию проекта
+$ cd awesome-project
+```
+
+

+
+## Создание виртуальной среды разработки
+
+Начиная работу с Python-проектом, сразу же создавайте виртуальную среду разработки
+**внутри вашего проекта**.
+
+/// tip | Подсказка
+
+Виртуальная среда разработки создается один раз, и в дальнейшем, работая с проектом, этого больше делать не придется.
+
+///
+
+//// tab | `venv`
+
+Для создания виртуальной среды вы можете воспользоваться модулем `venv`, который является частью встроенной библиотеки Python.
+
+

+
+```console
+$ python -m venv .venv
+```
+
+

+
+/// details | Что делает эта команда?
+
+* `python`: использовать программу под именем `python`
+* `-m`: вызывать модуль как скрипт, в следующей инструкции мы скажем какой именно модуль вызвать
+* `venv`: использовать модуль под названием `venv`, который обычно устанавливается вместе с Python
+* `.venv`: создать виртуальную среду разработки в новой директории `.venv`
+
+///
+
+////
+
+//// tab | `uv`
+
+Если вы установили `uv`, то вы можете им воспользоваться для создания виртуальной среды разработки.
+
+

+
+```console
+$ uv venv
+```
+
+

+
+/// tip | Подсказка
+
+По умолчанию `uv` создаст виртуальную среду разработки в папке под названием `.venv`.
+
+Но вы можете это изменить, передав дополнительный аргумент с именем директории.
+
+///
+
+////
+
+Данная команда создаст новую виртуальную среду разработки в папке `.venv`.
+
+/// details | `.venv` или другое имя?
+
+Вы можете поместить виртуальную среду разработки в папку с другим именем, но традиционным (конвенциональным) названием является `.venv` .
+
+///
+
+## Активация виртуальной среды разработки
+
+Активируйте виртуальную среду разработки, и тогда любая запускаемая Python-команда или устанавливаемый пакет будут ее использовать.
+
+/// tip | Подсказка
+
+При работе над проектом делайте это **каждый раз** при запуске **новой сессии в терминале**.
+
+///
+
+//// tab | Linux, macOS
+
+

+
+```console
+$ source .venv/bin/activate
+```
+
+

+
+////
+
+//// tab | [NAME_REDACTED]
+
+

+
+```console
+$ .venv\Scripts\Activate.ps1
+```
+
+

+
+////
+
+//// tab | [NAME_REDACTED]
+
+Или при использовании Bash для Windows (напр. [NAME_REDACTED]):
+
+

+
+```console
+$ source .venv/Scripts/activate
+```
+
+

+
+////
+
+## Проверка активации виртуальной среды
+
+Проверьте, активна ли виртуальная среда (удостоверимся, что предыдущая команда сработала).
+
+/// tip | Подсказка
+
+Убедитесь в том, что все работает так, как нужно и вы используете именно ту виртуальную среду разработки, которую нужно. Делать это необязательно, но желательно.
+
+///
+
+//// tab | Linux, macOS, [NAME_REDACTED]
+
+

+
+```console
+$ which python
+
+/home/user/code/awesome-project/.venv/bin/python
+```
+
+

+
+Если данная команда показывает, что исполняемый файл `python` (`.venv\bin\python`), находится внутри виртуальной среды вашего проекта (у нас это `awesome-project`), значит все отработало как нужно. 🎉
+
+////
+
+//// tab | [NAME_REDACTED]
+
+

+
+```console
+$ Get-Command python
+
+C:\Users\user\code\awesome-project\.venv\Scripts\python
+```
+
+

+
+Если данная команда показывает, что исполняемый файл `python` (`.venv\Scripts\python`), находится внутри виртуальной среды вашего проекта (у нас это `awesome-project`), значит все отработало как нужно. 🎉
+
+////
+
+## Обновление `pip`
+
+/// tip | Подсказка
+
+Если вы используете `uv`, то вы должны будете его использовать для установки пакетов вместо `pip`, поэтому обновлять `pip` вам ненужно. 😎
+
+///
+
+Если для установки пакетов вы используете `pip` (он устанавливается по умолчанию вместе с Python), то обновите `pip` до последней версии.
+
+Большинство экзотических ошибок, возникающих при установке пакетов, устраняется предварительным обновлением `pip`.
+
+/// tip | Подсказка
+
+Обычно это делается только один раз, сразу после создания виртуальной среды разработки.
+
+///
+
+Убедитесь в том, что виртуальная среда активирована (с помощью вышеуказанной команды) и запустите следующую команду:
+
+

+
+```console
+$ python -m pip install --upgrade pip
+
+---> 100%
+```
+
+

+
+## Добавление `.gitignore`
+
+Если вы используете **Git** (а вы должны его использовать), то добавьте файл `.gitignore` и исключите из Git всё, что находится в папке `.venv`.
+
+/// tip | Подсказка
+
+Если для создания виртуальной среды вы используете `uv`, то для вас все уже сделано и вы можете пропустить этот шаг. 😎
+
+///
+
+/// tip | Подсказка
+
+Это делается один раз, сразу после создания виртуальной среды разработки.
+
+///
+
+

+
+```console
+$ echo "*" > .venv/.gitignore
+```
+
+

+
+/// details | Что делает эта команда?
+
+* `echo "*"`: напечатать `*` в консоли (следующий шаг это слегка изменит)
+* `>`: все что находится слева от `>` не печатать в консоль, но записать в файл находящийся справа от `>`
+* `.gitignore`: имя файла, в который нужно записать текст.
+
+`*` в Git означает "всё". Т.е. будет проигнорировано всё, что содержится в папке `.venv`.
+
+Данная команда создаст файл `.gitignore` следующего содержания:
+
+```gitignore
+*
+```
+
+///
+
+## Установка пакетов
+
+После установки виртуальной среды, вы можете устанавливать в нее пакеты.
+
+/// tip | Подсказка
+
+Сделайте это **один раз**, при установке или обновлении пакетов, нужных вашему проекту.
+
+Если вам понадобится обновить версию пакета или добавить новый пакет, то вы должны будете **сделать это снова**.
+
+///
+
+### Установка пакетов напрямую
+
+Если вы торопитесь и не хотите объявлять зависимости проекта в отдельном файле, то вы можете установить их напрямую.
+
+/// tip | Подсказка
+
+Объявление пакетов, которые использует ваш проект, и их версий в отдельном файле (например, в `requirements.txt` или в `pyproject.toml`) - это отличная идея.
+
+///
+
+//// tab | `pip`
+
+

+
+```console
+$ pip install "fastapi[standard]"
+
+---> 100%
+```
+
+

+
+////
+
+//// tab | `uv`
+
+Если вы используете `uv`:
+
+

+
+```console
+$ uv pip install "fastapi[standard]"
+---> 100%
+```
+
+

+
+////
+
+### Установка из `requirements.txt`
+
+Если у вас есть `requirements.txt`, то вы можете использовать его для установки пакетов.
+
+//// tab | `pip`
+
+

+
+```console
+$ pip install -r requirements.txt
+---> 100%
+```
+
+

+
+////
+
+//// tab | `uv`
+
+Если вы используете `uv`:
+
+

+
+```console
+$ uv pip install -r requirements.txt
+---> 100%
+```
+
+

+
+////
+
+/// details | `requirements.txt`
+
+`requirements.txt` с парочкой пакетов внутри выглядит приблизительно так:
+
+```requirements.txt
+fastapi[standard]==0.113.0
+pydantic==2.8.0
+```
+
+///
+
+## Запуск программы
+
+После активации виртуальной среды разработки вы можете запустить свою программу и она будет использовать версию Python и пакеты, установленные в виртуальной среде.
+
+

+
+```console
+$ python main.py
+
+[NAME_REDACTED]
+```
+
+

+
+## Настройка редактора
+
+Вероятно, вы захотите воспользоваться редактором. Убедитесь, что вы настроили его на использование той самой виртуальной среды, которую вы создали. (Скорее всего, она автоматически будет обнаружена). Это позволит вам использовать авто-завершение и выделение ошибок в редакторе.
+
+Например:
+
+* VS Code
+* PyCharm
+
+/// tip | Подсказка
+
+Обычно это делается один раз, при создании виртуальной среды разработки.
+
+///
+
+## Деактивация виртуальной среды разработки
+
+По окончании работы над проектом вы можете деактивировать виртуальную среду.
+
+

+
+```console
+$ deactivate
+```
+
+

+
+Таким образом, при запуске `python`, будет использована версия `python` установленная глобально, а не  из этой виртуальной среды вместе с установленными в ней пакетами.
+
+## Все готово к работе
+
+Теперь вы готовы к тому, чтобы начать работу над своим проектом.
+
+
+
+/// tip | Подсказка
+
+Хотите разобраться со всем, что написано выше?
+
+Продолжайте читать. 👇🤓
+
+///
+
+## Зачем использовать виртуальную среду?
+
+Для работы с FastAPI вам потребуется установить Python.
+
+После этого вам нужно будет **установить** FastAPI и другие **пакеты**, которые вы собираетесь использовать.
+
+Для установки пакетов обычно используют `pip`, который устанавливается вместе с Python (или же используют альтернативные решения).
+
+Тем не менее, если вы просто используете `pip` напрямую, то пакеты будут установлены в **глобальное Python-окружение** (глобально установленный Python).
+
+### Проблема
+
+Так в чем же проблема с установкой пакетов в глобальную среду Python?
+
+В какой-то момент вам, вероятно, придется писать множество разных программ, которые используют различные пакеты. 😱
+
+Например, вы создаете проект `philosophers-stone`, который зависит от пакета под названием **`harry`, версии `1`**. Таким образом, вам нужно установить `harry`.
+
+```mermaid
+flowchart LR
+    stone(philosophers-stone) -->|requires| harry-1[harry v1]
+```
+
+Затем, в какой-то момент, вы создаете другой проект под названием `prisoner-of-azkaban`, и этот проект тоже зависит от `harry`, но он уже использует **`harry` версии `3`**.
+
+```mermaid
+flowchart LR
+    azkaban(prisoner-of-azkaban) --> |requires| harry-3[harry v3]
+```
+
+Проблема заключается в том, что при установке в глобальное окружение, а не в локальную виртуальную среду разработки, вам нужно будет выбирать, какую версию пакета `harry` устанавливать.
+
+Если вам нужен `philosophers-stone`, то вам нужно сначала установить `harry` версии `1`:
+
+

+
+```console
+$ pip install "harry==1"
+```
+
+

+
+И тогда в вашем глобальном окружении Python будет установлен `harry` версии `1`:
+
+```mermaid
+flowchart LR
+    subgraph global[global env]
+        harry-1[harry v1]
+    end
+    subgraph stone-project[philosophers-stone project]
+        stone(philosophers-stone) -->|requires| harry-1
+    end
+```
+
+Но если позднее вы захотите запустить `prisoner-of-azkaban`, то вам нужно будет удалить `harry` версии 1, и установить `harry` версии `3` (при установке пакета версии `3` поверх пакета версии `1`, пакет версии `1` удаляется автоматически).
+
+

+
+```console
+$ pip install "harry==3"
+```
+
+

+
+И тогда, в вашей глобальной среде окружения Python, будет установлен пакет `harry` версии `3`.
+
+И когда вы снова попытаетесь запустить `philosophers-stone`, то существует вероятность того, что он не будет работать, так как он использует `harry` версии `1`.
+
+```mermaid
+flowchart LR
+    subgraph global[global env]
+        harry-1[<strike>harry v1</strike>]
+        style harry-1 fill:#ccc,stroke-dasharray: 5 5
+        harry-3[harry v3]
+    end
+    subgraph stone-project[philosophers-stone project]
+        stone(philosophers-stone) -.-x|⛔| harry-1
+    end
+    subgraph azkaban-project[prisoner-of-azkaban project]
+        azkaban(prisoner-of-azkaban) --> |requires| harry-3
+    end
+```
+
+/// tip | Подсказка
+
+В пакетах Python очень часто стараются изо всех сил избегать внесения критических изменений в новые версии, но лучше перестраховаться и планово устанавливать новые версии, а затем запускать тесты, чтобы проверить, все ли работает правильно.
+
+///
+
+Теперь представьте, что это происходит со многими другими пакетами, которые используются в ваших проектах. С этим очень сложно справиться. И скорее всего, в конечном итоге вы будете запускать некоторые проекты с некоторыми несовместимыми зависимостями и не будете знать, почему что-то не работает.
+
+Кроме того, в зависимости от вашей операционной системы (напр. Linux, Windows, macOS), она может поставляться с уже установленным Python. Вероятно, что в этом случае в ней уже установлены системные пакеты определенных версий. Если вы устанавливаете пакеты глобально, то вы можете **поломать** программы, являющиеся частью ОС.
+
+## Куда устанавливаются пакеты?
+
+Когда вы устанавливаете Python, то на вашей машине создается некоторое количество директорий, содержащих некоторое количество файлов.
+
+Среди них есть каталоги, отвечающие за хранение всех устанавливаемых вами пакетов.
+
+Когда вы запустите команду:
+
+

+
+```console
+// Не запускайте эту команду, это просто пример 🤓
+$ pip install "fastapi[standard]"
+---> 100%
+```
+
+

+
+То будет скачан сжатый файл, содержащий код FastAPI, обычно скачивание происходит с PyPI.
+
+Также будут скачаны файлы, содержащие пакеты, которые использует FastAPI.
+
+Затем все файлы будут извлечены и помещены в директорию на вашем компьютере.
+
+По умолчанию эти файлы будут загружены и извлечены в один из каталогов установки Python, т.е. в глобальную среду.
+
+## Что такое виртуальная среда разработки?
+
+Решением проблемы размещения всех пакетов в глобальной среде будет использование отдельной виртуальной среды под каждый проект, над которым вы работаете.
+
+Виртуальная среда это обычная папка, очень похожая на глобальную, куда вы можете устанавливать пакеты для вашего проекта.
+
+Таким образом, каждый проект будет иметь свою отдельную виртуальную среду разработки (в директории `.venv`) вместе со своими пакетами.
+
+```mermaid
+flowchart TB
+    subgraph stone-project[philosophers-stone project]
+        stone(philosophers-stone) --->|requires| harry-1
+        subgraph venv1[.venv]
+            harry-1[harry v1]
+        end
+    end
+    subgraph azkaban-project[prisoner-of-azkaban project]
+        azkaban(prisoner-of-azkaban) --->|requires| harry-3
+        subgraph venv2[.venv]
+            harry-3[harry v3]
+        end
+    end
+    stone-project ~~~ azkaban-project
+```
+
+## Что означает активация виртуальной среды?
+
+Когда вы активируете виртуальную среду разработки, например, так:
+
+//// tab | Linux, macOS
+
+

+
+```console
+$ source .venv/bin/activate
+```
+
+

+
+////
+
+//// tab | [NAME_REDACTED]
+
+

+
+```console
+$ .venv\Scripts\Activate.ps1
+```
+
+

+
+////
+
+//// tab | [NAME_REDACTED]
+
+Или если вы воспользуетесь Bash под Windows (напр. [NAME_REDACTED]):
+
+

+
+```console
+$ source .venv/Scripts/activate
+```
+
+

+
+////
+
+
+Эта команда создаст или изменит некоторые [переменные окружения](environment-variables.md){.internal-link target=_blank}, которые будут доступны для последующих команд.
+
+Одной из таких переменных является `PATH`.
+
+/// tip | Подсказка
+
+Вы можете узнать больше о переменной окружения `PATH` в разделе [Переменные окружения](environment-variables.md#path-environment-variable){.internal-link target=_blank}.
+
+///
+
+При активации виртуальной среды путь `.venv/bin` (для Linux и macOS) или `.venv\Scripts` (для Windows) добавляется в переменную окружения `PATH`.
+
+Предположим, что до активации виртуальной среды переменная `PATH` выглядела так:
+
+//// tab | Linux, macOS
+
+```plaintext
+/usr/bin:/bin:/usr/sbin:/sbin
+```
+
+Это означает, что система ищет программы в следующих каталогах:
+
+* `/usr/bin`
+* `/bin`
+* `/usr/sbin`
+* `/sbin`
+
+////
+
+//// tab | Windows
+
+```plaintext
+C:\Windows\System32
+```
+
+Это означает, что система ищет программы в:
+
+* `C:\Windows\System32`
+
+////
+
+После активации виртуальной среды переменная окружение `PATH` будет выглядеть примерно так:
+
+//// tab | Linux, macOS
+
+```plaintext
+/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin
+```
+
+Это означает, что система теперь будет искать программы в:
+
+```plaintext
+/home/user/code/awesome-project/.venv/bin
+```
+
+прежде чем начать искать в других каталогах.
+
+Таким образом, когда вы введете в консоль `python`, система будет искать Python в
+
+```plaintext
+/home/user/code/awesome-project/.venv/bin/python
+```
+
+и будет использовать именно его.
+
+////
+
+//// tab | Windows
+
+```plaintext
+C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32
+```
+
+Это означает, что система в первую очередь начнет искать программы в:
+
+```plaintext
+C:\Users\user\code\awesome-project\.venv\Scripts
+```
+
+прежде чем начать искать в других директориях.
+
+Таким образом, если вы введете в консоль команду `python`, то система найдет Python в:
+
+```plaintext
+C:\Users\user\code\awesome-project\.venv\Scripts\python
+```
+
+и использует его.
+
+////
+
+Очень важной деталью является то, что путь к виртуальной среде будет помещен в самое начало переменной `PATH`. Система обнаружит данный путь к Python раньше, чем какой-либо другой. Таким образом, при запуске команды `python`, будет использован именно Python из виртуальной среды разработки, а не какой-нибудь другой (например, Python из глобальной среды)
+
+Активация виртуальной среды разработки также меняет и несколько других вещей, но данная функция является основной.
+
+## Проверка виртуальной среды
+
+Когда вы проверяете активна ли виртуальная среда разработки, например, так:
+
+//// tab | Linux, macOS, [NAME_REDACTED]
+
+

+
+```console
+$ which python
+
+/home/user/code/awesome-project/.venv/bin/python
+```
+
+

+
+////
+
+//// tab | [NAME_REDACTED]
+
+

+
+```console
+$ Get-Command python
+
+C:\Users\user\code\awesome-project\.venv\Scripts\python
+```
+
+

+
+////
+
+Это означает, что будет использоваться `python` **из виртуальной среды разработки**.
+
+Вы используете `which` для Linux и macOS и `Get-Command` для [NAME_REDACTED].
+
+Эта команда работает следующим образом: она проверяет переменную окружения `PATH`, проходя по очереди каждый указанный путь в поисках программы под названием `python`. И когда она её находит, то возвращает путь к данной программе.
+
+Основной момент при вызове команды `python` состоит в том, какой именно "`python`" будет запущен.
+
+Таким образом, вы можете убедиться, что используете правильную виртуальную среду разработки.
+
+/// tip | Подсказка
+
+Легко активировать одну виртуальную среду, вызвать один Python и **перейти к следующему проекту**.
+
+И следующий проект не будет работать потому, что вы используете **неправильный Python** из виртуальной среды другого проекта.
+
+Так что, будет нелишним проверить, какой `python` вы используете. 🤓
+
+///
+
+## Зачем деактивируют виртуальную среду?
+
+Предположим, что вы работаете над проектом `philosophers-stone`, **активируете виртуальную среду разработки**, устанавливаете пакеты и работаете с данной средой.
+
+И позже вам понадобилось поработать с **другим проектом** `prisoner-of-azkaban`.
+
+Вы переходите к этому проекту:
+
+

+
+```console
+$ cd ~/code/prisoner-of-azkaban
+```
+
+

+
+Если вы не деактивировали виртуальное окружение проекта `philosophers-stone`, то при запуске `python` через консоль будет вызван Python из `philosophers-stone`
+
+

+
+```console
+$ cd ~/code/prisoner-of-azkaban
+
+$ python main.py
+
+// Error importing sirius, it's not installed 😱
+Traceback (most recent call last):
+    File "main.py", line 1, in <module>
+        import sirius
+```
+
+

+
+Но если вы деактивируете виртуальную среду разработки и активируете новую среду для `prisoner-of-askaban`, то вы тогда запустите Python из виртуального окружения `prisoner-of-azkaban`.
+
+

+
+```console
+$ cd ~/code/prisoner-of-azkaban
+
+// Вам не требуется находится в старой директории для деактивации среды разработки, вы можете это сделать откуда угодно, даже из каталога другого проекта, в который вы перешли. 😎
+$ deactivate
+
+// Активируйте виртуальную среду разработки в prisoner-of-azkaban/.venv 🚀
+$ source .venv/bin/activate
+
+// Тепреь, когда вы запустите python, он найдет пакет sirius, установленный в виртуальной среде ✨
+$ python main.py
+
+Я торжественно клянусь в этом! 🐺
+```
+
+

+
+## Альтернативы
+
+Это простое руководство поможет вам начать работу и научит тому, как всё работает **изнутри**.
+
+Существует много альтернативных решений для работы с виртуальными средами разработки, с программными зависимостями, а также с проектами.
+
+Когда вы будете готовы использовать единый инструмент для управления проектом, программными зависимостями, виртуальными средами разработки и т.д., то я рекомендую вам попробовать uv.
+
+`uv` может очень многое. Он умеет:
+
+* **Устанавливать Python**, включая установку различных версий
+* Управлять средой виртуального окружения вашего проекта
+* Устанавливать **пакеты**
+* Управлять пакетами и их версиями внутри вашего проекта
+* Удостовериться, что вы используете **точный** набор пакетов и версий при установке, включая зависимости. Таким образом, вы можете быть уверенны, что проект, запускается в production, точно также, как и при разработке, этот механизм называется *locking*
+* Многие другие вещи
+
+## Заключение
+
+Если вы прочитали и поняли всё это, то теперь вы знаете **гораздо больше** о виртуальных средах разработки, чем многие другие разработчики. 🤓
+
+Скорее всего, знание этих деталей будет полезно вам в будущем. Когда вы будете отлаживать что-то, кажущееся сложным, вы будете знать, **как это работает под капотом**. 😎

Thanks!

```suggestion
Виртуальная среда разработки создается один раз и в дальнейшем, работая с проектом, этого больше делать не придется.
```

```suggestion
* `venv`: использовать модуль под названием `venv`, который обычно устанавливается вместе с Python
```

```suggestion
* `python`: использовать программу под именем `python`
```

```suggestion
* `-m`: вызывать модуль как скрипт, в следующей инструкции мы скажем какой именно модуль вызвать
```

```suggestion
* `.venv`: создать виртуальную среду разработки в новой директории `.venv`
```

```suggestion
Активируйте виртуальную среду разработки и тогда любая запускаемая Python-команда или устанавливаемый пакет будут ее использовать.
```

Если вы лентяй, то можно заменить `source` на `.`

```suggestion
Убедитесь в том, что все работает так, как нужно и вы используете именно ту виртуальную среду разработки, которую нужно. Делать это необязательно, но желательно.
```

```suggestion
Если данная команда показывает, что исполняемый файл `python`, находится внутри виртуальной среды вашего проекта (у нас это `awesome-project`), значит все отработало как нужно. 🎉
```

```suggestion
Убедитесь в том, что виртуальная среда активирована (с помощью вышеуказанной команды) и запустите следующую команду:
```

странная инструкция, достаточно написать в игнор саму папку .венв

```suggestion
Если для создания виртуальной среды вы используете <a href="https://github.com/astral-sh/uv" class="external-link" target="_blank">`uv`</a>, то для вас все уже сделано и вы можете пропустить этот шаг. 😎
```

```suggestion
Если у вас есть `requirements.txt`, то вы можете использовать его для установки пакетов.
```

```suggestion
После активации виртуальной среды разработки вы можете запустить свою программу и она будет использовать версию Python и пакеты, установленные в виртуальной среде.
```

Эта часть с новой строки что ли?

```suggestion
Обычно это делается один раз, при создании виртуальной среды разработки.
```

```suggestion
По окончании работы над проектом вы можете деактивировать виртуальную среду.
```

```suggestion
Таким образом, при запуске `python`, будет использована версия `python` установленная глобально, а не  из этой виртуальной среды вместе с установленными в ней пакетами.
```

```suggestion
После этого вам нужно будет **установить** FastAPI и другие **пакеты**, которые вы собираетесь использовать.
```

```suggestion
Для установки пакетов обычно используют `pip`, который устанавливается вместе с Python (или же используют альтернативные решения).
```

```suggestion
Затем, в какой-то момент, вы создаете другой проект под названием `prisoner-of-azkaban`, и этот проект тоже зависит от `harry`, но он уже использует **`harry` версии `3`**.
```

я здесь оставлю запятую: сложносочиненное предложение с союзом и

uv так делает, очень удобная вещь для каких-то своих папок или настроек.

по привычке нажала ENTER (поправила)


🌐 Add Ukrainian translation for `docs/uk/docs/fastapi-cli.md`

Hey guys! This would be my first (hopefully) successful  contribution to fastapi docs :)

@@ -0,0 +1,83 @@
+# FastAPI CLI
+
+**FastAPI CLI** це програма командного рядка, яку Ви можете використовувати, щоб обслуговувати Ваш додаток FastAPI, керувати Вашими FastApi проектами, тощо.
+
+Коли Ви встановлюєте FastApi (тобто виконуєте `pip install "fastapi[standard]"`), Ви також встановлюєте пакунок `fastapi-cli`, цей пакунок надає команду `fastapi` в терміналі.
+
+Для запуску Вашого FastAPI проекту для розробки, Ви можете скористатись командою `fastapi dev`:
+
+

+
+```console
+$ <font color="#4E9A06">fastapi</font> dev <u style="text-decoration-style:single">main.py</u>
+<font color="#3465A4">INFO    </font> Using path <font color="#3465A4">main.py</font>
+<font color="#3465A4">INFO    </font> Resolved absolute path <font color="#75507B">/home/user/code/awesomeapp/</font><font color="#AD7FA8">main.py</font>
+<font color="#3465A4">INFO    </font> Searching for package file structure from directories with <font color="#3465A4">__init__.py</font> files
+<font color="#3465A4">INFO    </font> Importing from <font color="#75507B">/home/user/code/</font><font color="#AD7FA8">awesomeapp</font>
+
+ ╭─ <font color="#8AE234"><b>Python module file</b></font> ─╮
+ │                      │
+ │  🐍 main.py          │
+ │                      │
+ ╰──────────────────────╯
+
+<font color="#3465A4">INFO    </font> Importing module <font color="#4E9A06">main</font>
+<font color="#3465A4">INFO    </font> Found importable FastAPI app
+
+ ╭─ <font color="#8AE234"><b>[NAME_REDACTED] app</b></font> ─╮
+ │                          │
+ │  <span style="background-color:#272822"><font color="#FF4689">from</font></span><span style="background-color:#272822"><font color="#F8F8F2"> main </font></span><span style="background-color:#272822"><font color="#FF4689">import</font></span><span style="background-color:#272822"><font color="#F8F8F2"> app</font></span><span style="background-color:#272822">  </span>  │
+ │                          │
+ ╰──────────────────────────╯
+
+<font color="#3465A4">INFO    </font> Using import string <font color="#8AE234"><b>main:app</b></font>
+
+ <span style="background-color:#C4A000"><font color="#2E3436">╭────────── FastAPI CLI - Development mode ───────────╮</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│  Serving at: http://127.0.0.1:8000                  │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│  API docs: http://127.0.0.1:8000/docs               │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│  Running in development mode, for production use:   │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│  </font></span><span style="background-color:#C4A000"><font color="#555753"><b>fastapi run</b></font></span><span style="background-color:#C4A000"><font color="#2E3436">                                        │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">╰─────────────────────────────────────────────────────╯</font></span>
+
+<font color="#4E9A06">INFO</font>:     Will watch for changes in these directories: ['/home/user/code/awesomeapp']
+<font color="#4E9A06">INFO</font>:     Uvicorn running on <b>http://127.0.0.1:8000</b> (Press CTRL+C to quit)
+<font color="#4E9A06">INFO</font>:     Started reloader process [<font color="#34E2E2"><b>2265862</b></font>] using <font color="#34E2E2"><b>WatchFiles</b></font>
+<font color="#4E9A06">INFO</font>:     Started server process [<font color="#06989A">2265873</font>]
+<font color="#4E9A06">INFO</font>:     Waiting for application startup.
+<font color="#4E9A06">INFO</font>:     Application startup complete.
+```
+
+

+
+Програма командного рядка `fastapi` це **FastAPI CLI**.
+
+FastAPI CLI приймає шлях до Вашої Python програми (напр. `main.py`) і автоматично виявляє екземпляр `FastAPI` (зазвичай названий `app`), обирає коректний процес імпорту, а потім обслуговує його.
+
+Натомість, для запуску у продакшн використовуйте `fastapi run`. 🚀
+
+Всередині **FastAPI CLI** використовує Uvicorn, високопродуктивний, production-ready, ASGI cервер. 😎
+
+## `fastapi dev`
+
+Використання `fastapi dev` ініціює режим розробки.
+
+За замовчуванням, **автоматичне перезавантаження** увімкнене, автоматично перезавантажуючи сервер кожного разу, коли Ви змінюєте Ваш код. Це ресурсо-затратно, та може бути менш стабільним, ніж коли воно вимкнене. Ви повинні використовувати його тільки під час розробки. Воно також слухає IP-адресу `127.0.0.1`, що є IP Вашого девайсу для самостійної комунікації з самим собою (`localhost`).
+
+## `fastapi run`
+
+Виконання `fastapi run` запустить FastAPI у продакшн-режимі за замовчуванням.
+
+За замовчуванням, **автоматичне перезавантаження** вимкнене. Воно також прослуховує IP-адресу `0.0.0.0`, що означає всі доступні IP адреси, тим самим даючи змогу будь-кому комунікувати з девайсом. Так Ви зазвичай будете запускати його у продакшн, наприклад у контейнері.
+
+В більшості випадків Ви можете (і маєте) мати "termination proxy", який обробляє HTTPS для Вас, це залежить від способу розгортання вашого додатку, Ваш провайдер може зробити це для Вас, або Вам потрібно налаштувати його самостійно.
+
+/// tip
+
+Ви можете дізнатись більше про це у [документації про розгортування](deployment/index.md){.internal-link target=_blank}.
+
+///

[USER_REDACTED] , great job! Agree with [USER_REDACTED] , apply his suggestions please.

```suggestion
Коли Ви встановлюєте FastApi (тобто виконуєте `pip install "fastapi[standard]"`), Ви також встановлюєте пакунок `fastapi-cli`, цей пакунок надає команду `fastapi` в терміналі.
```

```suggestion
**FastAPI CLI** це програма командного рядка, яку Ви можете використовувати, щоб обслуговувати Ваш додаток FastAPI, керувати Вашими FastApi проектами, тощо.
```

```suggestion
Для запуску Вашого FastAPI проекту для розробки, Ви можете скористатись командою `fastapi dev`:
```

```suggestion
FastAPI CLI приймає шлях до Вашої Python програми (напр.  `main.py`) і автоматично виявляє екземпляр `FastAPI` (зазвичай названий `app`), обирає коректний процес імпорту, а потім обслуговує його.
```

or word `Наприклад` fully

```suggestion
Всередині **FastAPI CLI** використовує <a href="https://www.uvicorn.org" class="external-link" target="_blank">Uvicorn</a>, високопродуктивний, production-ready, ASGI cервер. 😎
```

```suggestion
За замовчуванням, **автоматичне перезавантаження** вимкнене. Воно також прослуховує IP-адресу `0.0.0.0`, що означає всі доступні IP адреси, тим самим даючи змогу будь-кому комунікувати з девайсом. Так ви зазвичай будете запускати його у продакшн, наприклад у контейнері.
```

```suggestion
В більшості випадків Ви можете (і маєте) мати "termination proxy", який обробляє HTTPS для вас, це залежить від способу розгортання вашого додатку, Ваш провайдер може зробити це для вас, або вам потрібно налаштувати його самостійно.
```

[USER_REDACTED] Great job. There are just several typos.

```suggestion
Ви можете дізнатись більше про це у [документації про розгортування](deployment/index.md){.internal-link target=_blank}.
```


🌐 Add Korean translation for `docs/ko/docs/tutorial/request-forms.md`

@@ -0,0 +1,74 @@
+# 폼 데이터
+
+JSON 대신 폼 필드를 받아야 하는 경우 `Form`을 사용할 수 있습니다.
+
+/// info | 정보
+
+폼을 사용하려면, 먼저 `python-multipart`를 설치하세요.
+
+[가상 환경](../virtual-environments.md){.internal-link target=_blank}을 생성하고 활성화한 다음, 아래와 같이 설치할 수 있습니다:
+
+```console
+$ pip install python-multipart
+```
+
+///
+
+## `Form` 임포트하기
+
+`fastapi`에서 `Form`을 임포트합니다:
+
+{* ../../docs_src/request_forms/tutorial001_an_py39.py hl[3] *}
+
+## `Form` 매개변수 정의하기
+
+`Body` 또는 `Query`와 동일한 방식으로 폼 매개변수를 만듭니다:
+
+{* ../../docs_src/request_forms/tutorial001_an_py39.py hl[9] *}
+
+예를 들어, OAuth2 사양을 사용할 수 있는 방법 중 하나("패스워드 플로우"라고 함)로 `username`과 `password`를 폼 필드로 보내야 합니다.
+
+사양에서는 필드 이름이 `username` 및 `password`로 정확하게 명명되어야 하고, JSON이 아닌 폼 필드로 전송해야 합니다.
+
+`Form`을 사용하면 유효성 검사, 예제, 별칭(예: `username` 대신 `user-name`) 등을 포함하여 `Body`(및 `Query`, `Path`, `Cookie`)와 동일한 구성을 선언할 수 있습니다.
+
+/// info | 정보
+
+`Form`은 `Body`에서 직접 상속되는 클래스입니다.
+
+///
+
+/// tip | 팁
+
+폼 본문을 선언할 때, 폼이 없으면 매개변수가 쿼리 매개변수나 본문(JSON) 매개변수로 해석(interpret)되기 때문에 `Form`을 명시적으로 사용해야 합니다.
+
+///
+
+## "폼 필드"에 대해
+
+HTML 폼(`<form></form>`)이 데이터를 서버로 보내는 방식은 일반적으로 해당 데이터에 대해 "특수" 인코딩을 사용하며, 이는 JSON과 다릅니다.
+
+**FastAPI**는 JSON 대신 올바른 위치에서 해당 데이터를 읽습니다.
+
+/// note | 기술 세부사항
+
+폼의 데이터는 일반적으로 "미디어 유형(media type)" `application/x-www-form-urlencoded`를 사용하여 인코딩합니다.
+
+그러나 폼에 파일이 포함된 경우, `multipart/form-data`로 인코딩합니다. 다음 장에서 파일 처리에 대해 읽을 겁니다.
+
+
+이러한 인코딩 및 폼 필드에 대해 더 읽고 싶다면, POST에 대한 MDN 웹 문서를 참조하세요.
+
+///
+
+/// warning | 경고
+
+*경로 작업*에서 여러 `Form` 매개변수를 선언할 수 있지만, JSON으로 수신할 것으로 예상되는 `Body` 필드와 함께 선언할 수 없습니다. 요청 본문은 `application/json` 대신에 `application/x-www-form-urlencoded`를 사용하여 인코딩되기 때문입니다.
+
+이는 **FastAPI**의 제한 사항이 아니며 HTTP 프로토콜의 일부입니다.
+
+///
+
+## 요약
+
+폼 데이터 입력 매개변수를 선언하려면 `Form`을 사용하세요.

LGTM!

LGTM

번역 고생많으셨습니다.
아직 모든 한국어 번역 케이스에 익숙하지 않아 조심스럽지만...이 부분 번역이 누락된게 맞을까요?

password flow 번역에 대하여

https://fastapi.tiangolo.com/ko/tutorial/security/simple-oauth2/#username-password 문서에서는 "패스워드 플로우"로 번역되어 있습니다.

그러나, "비밀번호 흐름"으로 번역하는 것이 기존에 "path operation"을 "경로 작업"으로 번역한 기조와 더 일관성이 있을 것 같습니다. 어떤 표현이 더 적절할지 의견 부탁드립니다.

넵, 맞습니다. 리뷰 감사합니다

흐음...기번역된 문서와 일관성을 위해서 "패스워드 플로우"로 하겠습니다.


🌐 Add Korean translation for `docs/ko/docs/tutorial/request-form-models.md`

For consistency, I translate "Form" to "폼" not "양식" by [NAME_REDACTED] [translated docs](https://fastapi.tiangolo.com/ko/tutorial/request-forms-and-files/?h=%ED%8F%BC)

@@ -0,0 +1,78 @@
+# 폼 모델
+
+FastAPI에서 **Pydantic 모델**을 이용하여 **폼 필드**를 선언할 수 있습니다.
+
+/// info | 정보
+
+폼(Form)을 사용하려면, 먼저 `python-multipart`를 설치하세요.
+
+[가상 환경](../virtual-environments.md){.internal-link target=_blank}을 생성하고 활성화한 다음, 아래와 같이 설치할 수 있습니다:
+
+```console
+$ pip install python-multipart
+```
+
+///
+
+/// note | 참고
+
+이 기능은 FastAPI 버전 `0.113.0` 이후부터 지원됩니다. 🤓
+
+///
+
+## Pydantic 모델을 사용한 폼
+
+**폼 필드**로 받고 싶은 필드를 **Pydantic 모델**로 선언한 다음, 매개변수를 `Form`으로 선언하면 됩니다:
+
+{* ../../docs_src/request_form_models/tutorial001_an_py39.py hl[9:11,15] *}
+
+**FastAPI**는 요청에서 받은 **폼 데이터**에서 **각 필드**에 대한 데이터를 **추출**하고 정의한 Pydantic 모델을 줍니다.
+
+## 문서 확인하기
+
+문서 UI `/docs`에서 확인할 수 있습니다:
+
+

+
+

+
+## 추가 폼 필드 금지하기
+
+일부 특별한 사용 사례(흔하지는 않겠지만)에서는 Pydantic 모델에서 정의한 폼 필드를 **제한**하길 원할 수도 있습니다. 그리고 **추가** 필드를 **금지**할 수도 있습니다.
+
+/// note | 참고
+
+이 기능은 FastAPI 버전 `0.114.0` 이후부터 지원됩니다. 🤓
+
+///
+
+Pydantic의 모델 구성을 사용하여 추가(`extra`) 필드를 금지(`forbid`)할 수 있습니다:
+
+{* ../../docs_src/request_form_models/tutorial002_an_py39.py hl[12] *}
+
+클라이언트가 추가 데이터를 보내려고 하면 **오류** 응답을 받게 됩니다.
+
+예를 들어, 클라이언트가 폼 필드를 보내려고 하면:
+
+* `username`: `Rick`
+* `password`: `[NAME_REDACTED]`
+* `extra`: `Mr. Poopybutthole`
+
+`extra` 필드가 허용되지 않는다는 오류 응답을 받게 됩니다:
+
+```json
+{
+    "detail": [
+        {
+            "type": "extra_forbidden",
+            "loc": ["body", "extra"],
+            "msg": "Extra inputs are not permitted",
+            "input": "Mr. Poopybutthole"
+        }
+    ]
+}
+```
+
+## 요약
+
+Pydantic 모델을 사용하여 FastAPI에서 폼 필드를 선언할 수 있습니다. 😎

LGTM! 🚀

```suggestion
[가상 환경](../virtual-environments.md){.internal-link target=_blank}을 생성하고 활성화한 다음, 아래와 같이 설치할 수 있습니다:
```

I feel like there are a lot of ‘고’ and ‘,’ which makes for awkward sentences.

```suggestion
## 요약
```

I think there's a typo!

```suggestion
일부 특별한 사용 사례(흔하지는 않겠지만)에서는 Pydantic 모델에서 정의한 폼 필드를 **제한**하길 원할 수도 있습니다. 그리고 **추가**분을 **금지**하구요.
```
**추가**분을 이부분이 조금 어색한 문장인거같아요.
"추가적인 필드를 금지할 수도 있습니다." 라는 형식은 어떤거같나요?
이 전까지는 "다." 로 끝나지만 **금지**하구요. 에서는 "요." 로 끝나는것도 어색한 것 같습니다.

If my words were presumptuous, I sincerely apologize.

> Make sure you create a [virtual environment](https://c13563d6.fastapitiangolo.pages.dev/ko/virtual-environments/), activate it, and then install it, for example:

원문을 살려서 번역한건데 흠..많이 어색한가요?

훨씬 낫네요. 반영하겠습니다.

Not at all. Thank you for the review. 😄

한글로 보기에는 조금...? 어색함이 있는거 같아요.

Resolve: [📝 Accept the review](https://github.com/fastapi/fastapi/pull/13002/commits/47eb188a711f31b975522e55f7d375502079fca3)


🌐 Add Korean translation for `docs/ko/docs/tutorial/cookie-param-models.md`

It was fun, but it was hard: cookie jokes. 🤪 🍪

@@ -0,0 +1,76 @@
+# 쿠키 매개변수 모델
+
+관련있는 **쿠키**들의 그룹이 있는 경우, **Pydantic 모델**을 생성하여 선언할 수 있습니다. 🍪
+
+이를 통해 **여러 위치**에서 **모델을 재사용** 할 수 있고 모든 매개변수에 대한 유효성 검사 및 메타데이터를 한 번에 선언할 수도 있습니다. 😍
+
+/// note | 참고
+
+이 기능은 FastAPI 버전 `0.115.0` 이후부터 지원됩니다. 🤓
+
+///
+
+/// tip | 팁
+
+동일한 기술이 `Query`, `Cookie`, 그리고 `Header`에 적용됩니다. 😎
+
+///
+
+## Pydantic 모델을 사용한 쿠키
+
+**Pydantic 모델**에 필요한 **쿠키** 매개변수를 선언한 다음, 해당 매개변수를 `Cookie`로 선언합니다:
+
+{* ../../docs_src/cookie_param_models/tutorial001_an_py310.py hl[9:12,16] *}
+
+**FastAPI**는 요청에서 받은 **쿠키**에서 **각 필드**에 대한 데이터를 **추출**하고 정의한 Pydantic 모델을 줍니다.
+
+## 문서 확인하기
+
+문서 UI `/docs`에서 정의한 쿠키를 볼 수 있습니다:
+
+

+
+

+
+/// info | 정보
+
+명심하세요, 내부적으로 **브라우저는 쿠키를 특별한 방식으로 처리**하기 때문에 **자바스크립트**가 쉽게 쿠키를 건드릴 수 **없습니다**.
+
+`/docs`에서 **API 문서 UI**로 이동하면 *경로 작업*에 대한 쿠키의 **문서**를 볼 수 있습니다.
+
+하지만 아무리 **데이터를 입력**하고 "실행(Execute)"을 클릭해도, 문서 UI는 **자바스크립트**로 작동하기 때문에 쿠키는 전송되지 않고, 아무 값도 쓰지 않은 것처럼 **오류** 메시지를 보게 됩니다.
+
+///
+
+## 추가 쿠키 금지하기
+
+일부 특별한 사용 사례(흔하지는 않겠지만)에서는 수신하려는 쿠키를 **제한**할 수 있습니다.
+
+이제 API는 자신의 쿠키 동의를 제어할 수 있는 권한을 갖게 되었습니다. 🤪🍪
+
+Pydantic의 모델 구성을 사용하여 추가(`extra`) 필드를 금지(`forbid`)할 수 있습니다:
+
+{* ../../docs_src/cookie_param_models/tutorial002_an_py39.py hl[10] *}
+
+클라이언트가 **추가 쿠키**를 보내려고 시도하면, **오류** 응답을 받게 됩니다.
+
+API가 거부하는데도 동의를 얻기 위해 애쓰는 불쌍한 쿠키 배너(팝업)들. 🍪
+
+예를 들어, 클라이언트가 `good-list-please` 값으로 `santa_tracker` 쿠키를 보내려고 하면 클라이언트는 `santa_tracker` 쿠키가 허용되지 않는다는 **오류** 응답을 받게 됩니다:
+
+```json
+{
+    "detail": [
+        {
+            "type": "extra_forbidden",
+            "loc": ["cookie", "santa_tracker"],
+            "msg": "Extra inputs are not permitted",
+            "input": "good-list-please",
+        }
+    ]
+}
+```
+
+## 요약
+
+**Pydantic 모델**을 사용하여 **FastAPI**에서 **쿠키**를 선언할 수 있습니다. 😍

LGTM!

```suggestion
명심하세요, 알지 못하는 곳에서 **브라우저는 쿠키를 특별한 방식으로 처리**하기 때문에 **자바스크립트**가 쉽게 쿠키를 건드릴 수 **없습니다**.
```

뒤편에서 보다는 알지 못하는 곳에서는 어떨까요??

너무 직역해서 어색하긴 하네요. 원문 "behind the scenes"은 알지 못하는게 아니라 내부적인 일을 뜻하니 "내부적"으로라고 하는건 어떻나요?

Resolve at: [9bad893](https://github.com/fastapi/fastapi/pull/13000/commits/9bad893d876e5fd0cded1a04935fe8f9bbd1c238)

좋습니다!!


🌐 Add Korean translation for `docs/ko/docs/advanced/testing-dependencies.md`

Add translation to docs/ko/docs/advanced/testing-dependencies.md

@@ -0,0 +1,53 @@
+# 테스트 의존성 오버라이드
+
+## 테스트 중 의존성 오버라이드하기
+
+테스트를 진행하다 보면 의존성을 오버라이드해야 하는 경우가 있습니다.
+
+원래 의존성을 실행하고 싶지 않을 수도 있습니다(또는 그 의존성이 가지고 있는 하위 의존성까지도 실행되지 않길 원할 수 있습니다).
+
+대신, 테스트 동안(특정 테스트에서만) 사용될 다른 의존성을 제공하고, 원래 의존성이 사용되던 곳에서 사용할 수 있는 값을 제공하기를 원할 수 있습니다.
+
+### 사용 사례: 외부 서비스
+
+예를 들어, 외부 인증 제공자를 호출해야 하는 경우를 생각해봅시다.
+
+토큰을 보내면 인증된 사용자를 반환합니다.
+
+제공자는 요청당 요금을 부과할 수 있으며, 테스트를 위해 고정된 모의 사용자가 있는 경우보다 호출하는 데 시간이 더 걸릴 수 있습니다.
+
+외부 제공자를 한 번만 테스트하고 싶을 수도 있지만 테스트를 실행할 때마다 반드시 호출할 필요는 없습니다.
+
+이 경우 해당 공급자를 호출하는 종속성을 오버라이드하고 테스트에 대해서만 모의 사용자를 반환하는 사용자 지정 종속성을 사용할 수 있습니다.
+
+### `app.dependency_overrides` 속성 사용하기
+
+이런 경우를 위해 **FastAPI** 응용 프로그램에는 `app.dependency_overrides`라는 속성이 있습니다. 이는 간단한 `dict`입니다.
+
+테스트를 위해 의존성을 오버라이드하려면, 원래 의존성(함수)을 키로 설정하고 오버라이드할 의존성(다른 함수)을 값으로 설정합니다.
+
+그럼 **FastAPI**는 원래 의존성 대신 오버라이드된 의존성을 호출합니다.
+
+{* ../../docs_src/dependency_testing/tutorial001_an_py310.py hl[26:27,30] *}
+
+/// tip | 팁
+
+**FastAPI** 애플리케이션 어디에서든 사용된 의존성에 대해 오버라이드를 설정할 수 있습니다.
+
+원래 의존성은 *경로 동작 함수*, *경로 동작 데코레이터*(반환값을 사용하지 않는 경우), `.include_router()` 호출 등에서 사용될 수 있습니다.
+
+FastAPI는 여전히 이를 오버라이드할 수 있습니다.
+
+///
+
+그런 다음, `app.dependency_overrides`를 빈 `dict`로 설정하여 오버라이드를 재설정(제거)할 수 있습니다:
+
+```python
+app.dependency_overrides = {}
+```
+
+/// tip | 팁
+
+특정 테스트에서만 의존성을 오버라이드하고 싶다면, 테스트 시작 시(테스트 함수 내부) 오버라이드를 설정하고 테스트 종료 시(테스트 함수 끝부분) 재설정하면 됩니다.
+
+///

LGTM !! 🔥

LGTM!

LGTM 🚀

It's okay, but it would be better to reveal the nuance of "want" more clearly.

override; "재정의"도 좋지만 계속해서 "오버라이드"를 사용하므로 여기서도 따르면 좋을거 같습니다.

```suggestion
**FastAPI** 애플리케이션 어디에서든 사용된 의존성에 대해 오버라이드를 설정할 수 있습니다.

원래 의존성은 *경로 동작 함수*, *경로 동작 데코레이터*(반환값을 사용하지 않는 경우), `.include_router()` 호출 등에서 사용될 수 있습니다.
```

The blank line should have been included.

How about rephrasing it like this?


🌐 Add Korean translation for `docs/ko/docs/advanced/websockets.md`

Add translation to docs/ko/docs/advanced/websockets.md

@@ -0,0 +1,186 @@
+# WebSockets
+
+여러분은 **FastAPI**에서 WebSockets를 사용할 수 있습니다.
+
+## `WebSockets` 설치
+
+[가상 환경](../virtual-environments.md){.internal-link target=_blank)를 생성하고 활성화한 다음, `websockets`를 설치하세요:
+
+

+
+```console
+$ pip install websockets
+
+---> 100%
+```
+
+

+
+## WebSockets 클라이언트
+
+### 프로덕션 환경에서
+
+여러분의 프로덕션 시스템에서는 React, Vue.js 또는 Angular와 같은 최신 프레임워크로 생성된 프런트엔드를 사용하고 있을 가능성이 높습니다.
+
+백엔드와 WebSockets을 사용해 통신하려면 아마도 프런트엔드의 유틸리티를 사용할 것입니다.
+
+또는 네이티브 코드로 WebSocket 백엔드와 직접 통신하는 네이티브 모바일 응용 프로그램을 가질 수도 있습니다.
+
+혹은 WebSocket 엔드포인트와 통신할 수 있는 다른 방법이 있을 수도 있습니다.
+
+---
+
+하지만 이번 예제에서는 일부 자바스크립트를 포함한 간단한 HTML 문서를 사용하겠습니다. 모든 것을 긴 문자열 안에 넣습니다.
+
+물론, 이는 최적의 방법이 아니며 프로덕션 환경에서는 사용하지 않을 것입니다.
+
+프로덕션 환경에서는 위에서 설명한 옵션 중 하나를 사용하는 것이 좋습니다.
+
+그러나 이는 WebSockets의 서버 측에 집중하고 동작하는 예제를 제공하는 가장 간단한 방법입니다:
+
+{* ../../docs_src/websockets/tutorial001.py hl[2,6:38,41:43] *}
+
+## `websocket` 생성하기
+
+**FastAPI** 응용 프로그램에서 `websocket`을 생성합니다:
+
+{* ../../docs_src/websockets/tutorial001.py hl[1,46:47] *}
+
+/// note | 기술적 세부사항
+
+`from starlette.websockets import WebSocket`을 사용할 수도 있습니다.
+
+**FastAPI**는 개발자를 위한 편의를 위해 동일한 `WebSocket`을 직접 제공합니다. 하지만 이는 Starlette에서 가져옵니다.
+
+///
+
+## 메시지를 대기하고 전송하기
+
+WebSocket 경로에서 메시지를 대기(`await`)하고 전송할 수 있습니다.
+
+{* ../../docs_src/websockets/tutorial001.py hl[48:52] *}
+
+여러분은 이진 데이터, 텍스트, JSON 데이터를 받을 수 있고 전송할 수 있습니다.
+
+## 시도해보기
+
+파일 이름이 `main.py`라고 가정하고 응용 프로그램을 실행합니다:
+
+

+
+```console
+$ fastapi dev main.py
+
+<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+```
+
+

+
+브라우저에서 http://127.0.0.1:8000을 열어보세요.
+
+간단한 페이지가 나타날 것입니다:
+
+
+
+입력창에 메시지를 입력하고 전송할 수 있습니다:
+
+
+
+**FastAPI** WebSocket 응용 프로그램이 응답을 돌려줄 것입니다:
+
+
+
+여러 메시지를 전송(그리고 수신)할 수 있습니다:
+
+
+
+모든 메시지는 동일한 WebSocket 연결을 사용합니다.
+
+## `Depends` 및 기타 사용하기
+
+WebSocket 엔드포인트에서 `fastapi`에서 다음을 가져와 사용할 수 있습니다:
+
+* `Depends`
+* `Security`
+* `Cookie`
+* `Header`
+* `Path`
+* `Query`
+
+이들은 다른 FastAPI 엔드포인트/*경로 작동*과 동일하게 동작합니다:
+
+{* ../../docs_src/websockets/tutorial002_an_py310.py hl[68:69,82] *}
+
+/// info | 정보
+
+WebSocket에서는 `HTTPException`을 발생시키는 것이 적합하지 않습니다. 대신 `WebSocketException`을 발생시킵니다.
+
+명세서에 정의된 유효한 코드를 사용하여 종료 코드를 설정할 수 있습니다.
+
+///
+
+### 종속성을 가진 WebSockets 테스트
+
+파일 이름이 `main.py`라고 가정하고 응용 프로그램을 실행합니다:
+
+

+
+```console
+$ fastapi dev main.py
+
+<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+```
+
+

+
+브라우저에서 http://127.0.0.1:8000을 열어보세요.
+
+다음과 같은 값을 설정할 수 있습니다:
+
+* 경로에 사용된 "Item ID".
+* 쿼리 매개변수로 사용된 "Token".
+
+/// tip | 팁
+
+쿼리 `token`은 종속성에 의해 처리됩니다.
+
+///
+
+이제 WebSocket에 연결하고 메시지를 전송 및 수신할 수 있습니다:
+
+
+
+## 연결 해제 및 다중 클라이언트 처리
+
+WebSocket 연결이 닫히면, `await websocket.receive_text()`가 `WebSocketDisconnect` 예외를 발생시킵니다. 이를 잡아 처리할 수 있습니다:
+
+{* ../../docs_src/websockets/tutorial003_py39.py hl[79:81] *}
+
+테스트해보기:
+
+* 여러 브라우저 탭에서 앱을 엽니다.
+* 각 탭에서 메시지를 작성합니다.
+* 한 탭을 닫아보세요.
+
+`WebSocketDisconnect` 예외가 발생하며, 다른 모든 클라이언트가 다음과 같은 메시지를 수신합니다:
+
+```
+Client #1596980209979 left the chat
+```
+
+/// tip | 팁
+
+위 응용 프로그램은 여러 WebSocket 연결에 메시지를 브로드캐스트하는 방법을 보여주는 간단한 예제입니다.
+
+그러나 모든 것을 메모리의 단일 리스트로 처리하므로, 프로세스가 실행 중인 동안만 동작하며 단일 프로세스에서만 작동합니다.
+
+FastAPI와 쉽게 통합할 수 있으면서 더 견고하고 Redis, PostgreSQL 등을 지원하는 도구를 찾고 있다면, encode/broadcaster를 확인하세요.
+
+///
+
+## 추가 정보
+
+다음 옵션에 대한 자세한 내용을 보려면 Starlette의 문서를 확인하세요:
+
+* `WebSocket` 클래스.
+* 클래스 기반 WebSocket 처리.

LGTM 👍

LGTM!

```suggestion
또는 네이티브 코드로 WebSocket 백엔드와 직접 통신하는 네이티브 모바일 응용 프로그램을 가질 수도 있습니다.
```

'애플리케이션' should be changed to '응용 프로그램'.

```suggestion
**FastAPI** 응용 프로그램에서 `websocket`을 생성합니다:
```

'애플리케이션' should be changed to '응용 프로그램'.

```suggestion
**FastAPI** WebSocket 응용 프로그램이 응답을 돌려줄 것입니다:
```

'애플리케이션' should be changed to '응용 프로그램'.

```suggestion
파일 이름이 `main.py`라고 가정하고 응용 프로그램을 실행합니다:
```

'애플리케이션' should be changed to '응용 프로그램'.

```suggestion
위 응용 프로그램은 여러 WebSocket 연결에 메시지를 브로드캐스트하는 방법을 보여주는 간단한 예제입니다.
```

'애플리케이션' should be changed to '응용 프로그램'.

Thank you for your reviews !!


🌐 Add Traditional Chinese translation for `docs/zh-hant/docs/async.md`

@@ -0,0 +1,442 @@
+# 並行與 async / await
+
+有關*路徑操作函式*的 `async def` 語法的細節與非同步 (asynchronous) 程式碼、並行 (concurrency) 與平行 (parallelism) 的一些背景知識。
+
+## 趕時間嗎?
+
+TL;DR:
+
+如果你正在使用要求你以 `await` 語法呼叫的第三方函式庫，例如：
+
+```Python
+results = await some_library()
+```
+
+然後，使用 `async def` 宣告你的*路徑操作函式*：
+
+
+```Python hl_lines="2"
+[USER_REDACTED].get('/')
+async def read_results():
+    results = await some_library()
+    return results
+```
+
+/// note | 注意
+
+你只能在 `async def` 建立的函式內使用 `await`。
+
+///
+
+---
+
+如果你使用的是第三方函式庫並且它需要與某些外部資源（例如資料庫、API、檔案系統等）進行通訊，但不支援 `await`（目前大多數資料庫函式庫都是這樣），在這種情況下，你可以像平常一樣使用 `def` 宣告*路徑操作函式*，如下所示：
+
+```Python hl_lines="2"
+[USER_REDACTED].get('/')
+def results():
+    results = some_library()
+    return results
+```
+
+---
+
+如果你的應用程式不需要與外部資源進行任何通訊並等待其回應，請使用 `async def`。
+
+---
+
+如果你不確定該用哪個，直接用 `def` 就好。
+
+---
+
+**注意**：你可以在*路徑操作函式*中混合使用 `def` 和 `async def` ，並使用最適合你需求的方式來定義每個函式。FastAPI 會幫你做正確的處理。
+
+無論如何，在上述哪種情況下，FastAPI 仍將以非同步方式運行，並且速度非常快。
+
+但透過遵循上述步驟，它將能進行一些效能最佳化。
+
+## 技術細節
+
+現代版本的 Python 支援使用 **「協程」** 的 **`async` 和 `await`** 語法來寫 **「非同步程式碼」**。
+
+接下來我們逐一介紹：
+
+* **非同步程式碼**
+* **`async` 和 `await`**
+* **協程**
+
+## 非同步程式碼
+
+非同步程式碼僅意味著程式語言 💬 有辦法告訴電腦/程式 🤖 在程式碼中的某個點，它 🤖 需要等待某些事情完成。讓我們假設這些事情被稱為「慢速檔案」📝。
+
+因此，在等待「慢速檔案」📝 完成的這段時間，電腦可以去處理一些其他工作。
+
+接著程式 🤖 會在有空檔時回來查看是否有等待的工作已經完成，並執行必要的後續操作。
+
+接下來，它 🤖 完成第一個工作（例如我們的「慢速檔案」📝）並繼續執行相關的所有操作。
+這個「等待其他事情」通常指的是一些相對較慢的（與處理器和 RAM 記憶體的速度相比）的 I/O 操作，比如說：
+
+* 透過網路傳送來自用戶端的資料
+* 從網路接收來自用戶端的資料
+* 從磁碟讀取檔案內容
+* 將內容寫入磁碟
+* 遠端 API 操作
+* 資料庫操作
+* 資料庫查詢
+* 等等
+
+由於大部分的執行時間都消耗在等待 I/O 操作上，因此這些操作被稱為 "I/O 密集型" 操作。
+
+之所以稱為「非同步」，是因為電腦/程式不需要與那些耗時的任務「同步」，等待任務完成的精確時間，然後才能取得結果並繼續工作。
+
+相反地，非同步系統在任務完成後，可以讓任務稍微等一下（幾微秒），等待電腦/程式完成手頭上的其他工作，然後再回來取得結果繼續進行。
+
+相對於「非同步」（asynchronous），「同步」（synchronous）也常被稱作「順序性」（sequential），因為電腦/程式會依序執行所有步驟，即便這些步驟涉及等待，才會切換到其他任務。
+
+### 並行與漢堡
+
+上述非同步程式碼的概念有時也被稱為「並行」，它不同於「平行」。
+
+並行和平行都與 "不同的事情或多或少同時發生" 有關。
+
+但並行和平行之間的細節是完全不同的。
+
+為了理解差異，請想像以下有關漢堡的故事：
+
+### 並行漢堡
+
+你和你的戀人去速食店，排隊等候時，收銀員正在幫排在你前面的人點餐。😍
+
+
+
+輪到你了，你給你與你的戀人點了兩個豪華漢堡。🍔🍔
+
+
+
+收銀員通知廚房準備你的漢堡（儘管他們還在為前面其他顧客準備食物）。
+
+
+
+之後你完成付款。💸
+
+收銀員給你一個號碼牌。
+
+
+
+在等待漢堡的同時，你可以與戀人選一張桌子，然後坐下來聊很長一段時間（因為漢堡十分豪華，準備特別費工。）
+
+這段時間，你還能欣賞你的戀人有多麼的可愛、聰明與迷人。✨😍✨
+
+
+
+當你和戀人邊聊天邊等待時，你會不時地查看櫃檯上的顯示的號碼，確認是否已經輪到你了。
+
+然後在某個時刻，終於輪到你了。你走到櫃檯，拿了漢堡，然後回到桌子上。
+
+
+
+你和戀人享用這頓大餐，整個過程十分開心✨
+
+
+
+/// info
+
+漂亮的插畫來自 [NAME_REDACTED]. 🎨
+
+///
+
+---
+
+想像你是故事中的電腦或程式 🤖。
+
+當你排隊時，你在放空😴，等待輪到你，沒有做任何「生產性」的事情。但這沒關係，因為收銀員只是接單（而不是準備食物），所以排隊速度很快。
+
+然後，當輪到你時，你開始做真正「有生產力」的工作，處理菜單，決定你想要什麼，替戀人選擇餐點，付款，確認你給了正確的帳單或信用卡，檢查你是否被正確收費，確認訂單中的項目是否正確等等。
+
+但是，即使你還沒有拿到漢堡，你與收銀員的工作已經「暫停」了 ⏸，因為你必須等待 🕙 漢堡準備好。
+
+但當你離開櫃檯，坐到桌子旁，拿著屬於你的號碼等待時，你可以把注意力 🔀 轉移到戀人身上，並開始「工作」⏯ 🤓——也就是和戀人調情 😍。這時你又開始做一些非常「有生產力」的事情。
+
+接著，收銀員 💁 將你的號碼顯示在櫃檯螢幕上，並告訴你「漢堡已經做好了」。但你不會瘋狂地立刻跳起來，因為顯示的號碼變成了你的。你知道沒有人會搶走你的漢堡，因為你有自己的號碼，他們也有他們的號碼。
+
+所以你會等戀人講完故事（完成當前的工作 ⏯/正在進行的任務 🤓），然後微笑著溫柔地說你要去拿漢堡了 ⏸。
+
+然後你走向櫃檯 🔀，回到已經完成的最初任務 ⏯，拿起漢堡，說聲謝謝，並帶回桌上。這就結束了與櫃檯的互動步驟/任務 ⏹，接下來會產生一個新的任務，「吃漢堡」 🔀 ⏯，而先前的「拿漢堡」任務已經完成了 ⏹。
+
+### 平行漢堡
+
+現在，讓我們來想像這裡不是「並行漢堡」，而是「平行漢堡」。
+
+你和戀人一起去吃平行的速食餐。
+
+你們站在隊伍中，前面有幾位（假設有 8 位）既是收銀員又是廚師的員工，他們同時接單並準備餐點。
+
+所有排在你前面的人都在等著他們的漢堡準備好後才會離開櫃檯，因為每位收銀員在接完單後，馬上會去準備漢堡，然後才回來處理下一個訂單。
+
+
+
+終於輪到你了，你為你和你的戀人點了兩個非常豪華的漢堡。
+
+你付款了 💸。
+
+
+
+收銀員走進廚房準備食物。
+
+你站在櫃檯前等待 🕙，以免其他人先拿走你的漢堡，因為這裡沒有號碼牌系統。
+
+
+
+由於你和戀人都忙著不讓別人搶走你的漢堡，等漢堡準備好時，你根本無法專心和戀人互動。😞
+
+這是「同步」(synchronous)工作，你和收銀員/廚師 👨🍳 是「同步化」的。你必須等到 🕙 收銀員/廚師 👨🍳 完成漢堡並交給你的那一刻，否則別人可能會拿走你的餐點。
+
+
+
+最終，經過長時間的等待 🕙，收銀員/廚師 👨🍳 拿著漢堡回來了。
+
+
+
+你拿著漢堡，和你的戀人回到餐桌。
+
+你們僅僅是吃完漢堡，然後就結束了。⏹
+
+
+
+整個過程中沒有太多的談情說愛，因為大部分時間 🕙 都花在櫃檯前等待。😞
+
+/// info
+
+漂亮的插畫來自 [NAME_REDACTED]. 🎨
+
+///
+
+---
+
+在這個平行漢堡的情境下，你是一個程式 🤖 且有兩個處理器（你和戀人），兩者都在等待 🕙 並專注於等待櫃檯上的餐點 🕙，等待的時間非常長。
+
+這家速食店有 8 個處理器（收銀員/廚師）。而並行漢堡店可能只有 2 個處理器（一位收銀員和一位廚師）。
+
+儘管如此，最終的體驗並不是最理想的。😞
+
+---
+
+這是與漢堡類似的故事。🍔
+
+一個更「現實」的例子，想像一間銀行。
+
+直到最近，大多數銀行都有多位出納員 👨💼👨💼👨💼👨💼，以及一條長長的隊伍 🕙🕙🕙🕙🕙🕙🕙🕙。
+
+所有的出納員都在一個接一個地滿足每位客戶的所有需求 👨💼⏯。
+
+你必須長時間排隊 🕙，不然就會失去機會。
+
+所以，你不會想帶你的戀人 😍 一起去銀行辦事 🏦。
+
+### 漢堡結論
+
+在「和戀人一起吃速食漢堡」的這個場景中，由於有大量的等待 🕙，使用並行系統 ⏸🔀⏯ 更有意義。
+
+這也是大多數 Web 應用的情況。
+
+許多用戶正在使用你的應用程式，而你的伺服器則在等待 🕙 這些用戶不那麼穩定的網路來傳送請求。
+
+接著，再次等待 🕙 回應。
+
+這種「等待」 🕙 通常以微秒來衡量，但累加起來，最終還是花費了很多等待時間。
+
+這就是為什麼對於 Web API 來說，使用非同步程式碼 ⏸🔀⏯ 是非常有意義的。
+
+這種類型的非同步性正是 NodeJS 成功的原因（儘管 NodeJS 不是平行的），這也是 Go 語言作為程式語言的一個強大優勢。
+
+這與 **FastAPI** 所能提供的性能水平相同。
+
+你可以同時利用並行性和平行性，進一步提升效能，這比大多數已測試的 NodeJS 框架都更快，並且與 Go 語言相當，而 Go 是一種更接近 C 的編譯語言（感謝 Starlette）。
+
+### 並行比平行更好嗎？
+
+不是的！這不是故事的本意。
+
+並行與平行不同。並行在某些 **特定** 的需要大量等待的情境下表現更好。正因如此，並行在 Web 應用程式開發中通常比平行更有優勢。但並不是所有情境都如此。
+
+因此，為了平衡報導，想像下面這個短故事
+
+> 你需要打掃一間又大又髒的房子。
+
+*是的，這就是全部的故事。*
+
+---
+
+這裡沒有任何需要等待 🕙 的地方，只需要在房子的多個地方進行大量的工作。
+
+你可以像漢堡的例子那樣輪流進行，先打掃客廳，再打掃廚房，但由於你不需要等待 🕙 任何事情，只需要持續地打掃，輪流並不會影響任何結果。
+
+無論輪流執行與否（並行），你都需要相同的工時完成任務，同時需要執行相同工作量。
+
+但是，在這種情境下，如果你可以邀請8位前收銀員/廚師（現在是清潔工）來幫忙，每個人（加上你）負責房子的某個區域，這樣你就可以 **平行** 地更快完成工作。
+
+在這個場景中，每個清潔工（包括你）都是一個處理器，完成工作的一部分。
+
+由於大多數的執行時間都花在實際的工作上（而不是等待），而電腦中的工作由 CPU 完成，因此這些問題被稱為「CPU 密集型」。
+
+---
+
+常見的 CPU 密集型操作範例包括那些需要進行複雜數學計算的任務。
+
+例如：
+
+* **音訊**或**圖像處理**；
+* **電腦視覺**：一張圖片由數百萬個像素組成，每個像素有 3 個值/顏色，處理這些像素通常需要同時進行大量計算；
+* **機器學習**: 通常需要大量的「矩陣」和「向量」運算。想像一個包含數字的巨大電子表格，並所有的數字同時相乘;
+* **深度學習**: 這是機器學習的子領域，同樣適用。只不過這不僅僅是一張數字表格，而是大量的數據集合，並且在很多情況下，你會使用特殊的處理器來構建或使用這些模型。
+
+### 並行 + 平行: Web + 機器學習
+
+使用 **FastAPI**，你可以利用並行的優勢，這在 Web 開發中非常常見（這也是 NodeJS 的最大吸引力）。
+
+但你也可以利用平行與多行程 (multiprocessing)（讓多個行程同時運行） 的優勢來處理機器學習系統中的 **CPU 密集型**工作。
+
+這一點，再加上 Python 是 **資料科學**、機器學習，尤其是深度學習的主要語言，讓 **FastAPI** 成為資料科學/機器學習 Web API 和應用程式（以及許多其他應用程式）的絕佳選擇。
+
+想了解如何在生產環境中實現這種平行性，請參見 [部屬](deployment/index.md){.internal-link target=_blank}。
+
+## `async` 和 `await`
+
+現代 Python 版本提供一種非常直觀的方式定義非同步程式碼。這使得它看起來就像正常的「順序」程式碼，並在適當的時機「等待」。
+
+當某個操作需要等待才能回傳結果，並且支援這些新的 Python 特性時，你可以像這樣編寫程式碼：
+
+```Python
+burgers = await get_burgers(2)
+```
+
+這裡的關鍵是 `await`。它告訴 Python 必須等待 ⏸ `get_burgers(2)` 完成它的工作 🕙， 然後將結果儲存在 `burgers` 中。如此，Python 就可以在此期間去處理其他事情 🔀 ⏯ （例如接收另一個請求）。
+
+要讓 `await` 運作，它必須位於支持非同步功能的函式內。為此，只需使用 `async def` 宣告函式：
+
+```Python hl_lines="1"
+async def get_burgers(number: int):
+    # Do some asynchronous stuff to create the burgers
+    return burgers
+```
+
+...而不是 `def`:
+
+```Python hl_lines="2"
+# This is not asynchronous
+def get_sequential_burgers(number: int):
+    # Do some sequential stuff to create the burgers
+    return burgers
+```
+
+使用 `async def`，[NAME_REDACTED] 知道在該函式內需要注意 `await`，並且它可以「暫停」 ⏸ 執行該函式，然後執行其他任務 🔀 後回來。
+
+當你想要呼叫 `async def` 函式時，必須使用「await」。因此，這樣寫將無法運行：
+
+```Python
+# This won't work, because get_burgers was defined with: async def
+burgers = get_burgers(2)
+```
+
+---
+
+如果你正在使用某個函式庫，它告訴你可以使用 `await` 呼叫它，那麼你需要用 `async def` 定義*路徑操作函式*，如：
+
+```Python hl_lines="2-3"
+[USER_REDACTED].get('/burgers')
+async def read_burgers():
+    burgers = await get_burgers(2)
+    return burgers
+```
+
+### 更多技術細節
+
+你可能已經注意到，`await` 只能在 `async def` 定義的函式內使用。
+
+但同時，使用 `async def` 定義的函式本身也必須被「等待」。所以，帶有 `async def` 函式只能在其他使用 `async def` 定義的函式內呼叫。
+
+那麼，這就像「先有雞還是先有蛋」的問題，要如何呼叫第一個 `async` 函式呢？
+
+如果你使用 FastAPI，無需擔心這個問題，因為「第一個」函式將是你的*路徑操作函式*，FastAPI 會知道如何正確處理這個問題。
+
+但如果你想在沒有 FastAPI 的情況下使用 `async` / `await`，你也可以這樣做。
+
+### 編寫自己的非同步程式碼
+
+Starlette （和 **FastAPI**） 是基於 AnyIO 實作的，這使得它們與 Python 標準函式庫相容 asyncio 和 Trio。
+
+特別是，你可以直接使用 AnyIO 來處理更複雜的並行使用案例，這些案例需要你在自己的程式碼中使用更高階的模式。
+
+即使你不使用 **FastAPI**，你也可以使用 AnyIO 來撰寫自己的非同步應用程式，並獲得高相容性及一些好處（例如結構化並行）。
+
+### 其他形式的非同步程式碼
+
+使用 `async` 和 `await` 的風格在語言中相對較新。
+
+但它使處理異步程式碼變得更加容易。
+
+相同的語法（或幾乎相同的語法）最近也被包含在現代 JavaScript（無論是瀏覽器還是 NodeJS）中。
+
+但在此之前，處理異步程式碼要更加複雜和困難。
+
+在較舊的 Python 版本中，你可能會使用多執行緒或 Gevent。但這些程式碼要更難以理解、調試和思考。
+
+在較舊的 NodeJS / 瀏覽器 JavaScript 中，你會使用「回呼」，這可能會導致回呼地獄。
+
+## 協程
+
+**協程** 只是 `async def` 函式所回傳的非常特殊的事物名稱。Python 知道它是一個類似函式的東西，可以啟動它，並且在某個時刻它會結束，但它也可能在內部暫停 ⏸，只要遇到 `await`。
+
+這種使用 `async` 和 `await` 的非同步程式碼功能通常被概括為「協程」。這與 Go 語言的主要特性「Goroutines」相似。
+
+## 結論
+
+讓我們再次回顧之前的句子：
+
+> 現代版本的 Python 支持使用 **"協程"** 的 **`async` 和 `await`** 語法來寫 **"非同步程式碼"**。
+
+現在應該能明白其含意了。✨
+
+這些就是驅動 FastAPI（通過 Starlette）運作的原理，也讓它擁有如此驚人的效能。
+
+## 非常技術性的細節
+
+/// warning
+
+你大概可以跳過這段。
+
+這裡是有關 FastAPI 內部技術細節。
+
+如果你有相當多的技術背景（例如協程、執行緒、阻塞等），並且對 FastAPI 如何處理 `async def` 與常規 `def` 感到好奇，請繼續閱讀。
+
+///
+
+### 路徑操作函数
+
+當你使用 `def` 而不是 `async def` 宣告*路徑操作函式*時，該函式會在外部的執行緒池（threadpool）中執行，然後等待結果，而不是直接呼叫（因為這樣會阻塞伺服器）。
+
+如果你來自於其他不以這種方式運作的非同步框架，而且你習慣於使用普通的 `def` 定義僅進行簡單計算的*路徑操作函式*，目的是獲得微小的性能增益（大約 100 奈秒），請注意，在 FastAPI 中，效果會完全相反。在這些情況下，最好使用 `async def`除非你的*路徑操作函式*執行阻塞的 I/O 的程式碼。
+
+不過，在這兩種情況下，**FastAPI** [仍然很快](index.md#_11){.internal-link target=_blank}至少與你之前的框架相當（或者更快）。
+
+### 依賴項(Dependencies)
+
+同樣適用於[依賴項](tutorial/dependencies/index.md){.internal-link target=_blank}。如果依賴項是一個標準的 `def` 函式，而不是 `async def`，那麼它在外部的執行緒池被運行。
+
+### 子依賴項
+
+你可以擁有多個相互依賴的依賴項和[子依賴項](tutorial/dependencies/sub-dependencies.md){.internal-link target=_blank} （作為函式定義的參數），其中一些可能是用 `async def` 宣告，也可能是用 `def` 宣告。它們仍然可以正常運作，用 `def` 定義的那些將會在外部的執行緒中呼叫（來自執行緒池），而不是被「等待」。
+
+### 其他輔助函式
+
+你可以直接呼叫任何使用 `def` 或 `async def` 建立的其他輔助函式，FastAPI 不會影響你呼叫它們的方式。
+
+這與 FastAPI 為你呼叫*路徑操作函式*和依賴項的邏輯有所不同。
+
+如果你的輔助函式是用 `def` 宣告的，它將會被直接呼叫（按照你在程式碼中撰寫的方式），而不是在執行緒池中。如果該函式是用 `async def` 宣告，那麼你在呼叫時應該使用 `await` 等待其結果。
+
+---
+
+再一次強調，這些都是非常技術性的細節，如果你特地在尋找這些資訊，這些內容可能會對你有幫助。
+
+否則，只需遵循上面提到的指引即可：趕時間嗎?.

i've reviewed in #12489

I've fixed this (it wasn't rendering properly)
(we have to include the “note” as the styling depends on this part)


🌐 Add Korean translation for `docs/ko/docs/tutorial/testing.md`

@@ -0,0 +1,243 @@
+# 테스팅
+
+Starlette 덕분에 **FastAPI** 를 테스트하는 일은 쉽고 즐거운 일이 되었습니다.
+
+Starlette는 HTTPX를 기반으로 하며, 이는 Requests를 기반으로 설계되었기 때문에 매우 친숙하고 직관적입니다.
+
+이를 사용하면 FastAPI에서 pytest를 직접 사용할 수 있습니다.
+
+## `TestClient` 사용하기
+
+/// info | 정보
+
+`TestClient` 사용하려면, 우선 `httpx` 를 설치해야 합니다.
+
+[virtual environment](../virtual-environments.md){.internal-link target=_blank} 를 만들고, 활성화 시킨 뒤에 설치하세요. 예시:
+
+```console
+$ pip install httpx
+```
+
+///
+
+`TestClient` 를 임포트하세요.
+
+**FastAPI** 어플리케이션을 전달하여 `TestClient` 를 만드세요.
+
+이름이 `test_` 로 시작하는 함수를 만드세요(`pytest` 의 표준적인 관례입니다).
+
+`httpx` 를 사용하는 것과 같은 방식으로 `TestClient` 객체를 사용하세요.
+
+표준적인 파이썬 문법을 이용하여 확인이 필요한 곳에 간단한 `assert` 문장을 작성하세요(역시 표준적인 `pytest` 관례입니다).
+
+{* ../../docs_src/app_testing/tutorial001.py hl[2,12,15:18] *}
+
+/// tip | 팁
+
+테스트를 위한 함수는 `async def` 가 아니라 `def` 로 작성됨에 주의하세요.
+
+그리고 클라이언트에 대한 호출도 `await` 를 사용하지 않는 일반 호출입니다.
+
+이렇게 하여 복잡한 과정 없이 `pytest` 를 직접적으로 사용할 수 있습니다.
+
+///
+
+/// note | 기술 세부사항
+
+`from starlette.testclient import TestClient` 역시 사용할 수 있습니다.
+
+**FastAPI** 는 개발자의 편의를 위해 `starlette.testclient` 를 `fastapi.testclient` 로도 제공할 뿐입니다. 이는 단지 `Starlette` 에서 직접 가져오는지의 차이일 뿐입니다.
+
+///
+
+/// tip | 팁
+
+FastAPI 애플리케이션에 요청을 보내는 것 외에도 테스트에서 `async` 함수를 호출하고 싶다면 (예: 비동기 데이터베이스 함수), 심화 튜토리얼의 [[NAME_REDACTED]](../advanced/async-tests.md){.internal-link target=_blank} 를 참조하세요.
+
+///
+
+## 테스트 분리하기
+
+실제 애플리케이션에서는 테스트를 별도의 파일로 나누는 경우가 많습니다.
+
+
+그리고 **FastAPI** 애플리케이션도 여러 파일이나 모듈 등으로 구성될 수 있습니다.
+
+### **FastAPI** app 파일
+
+[[NAME_REDACTED]](bigger-applications.md){.internal-link target=_blank} 에 묘사된 파일 구조를 가지고 있는 것으로 가정해봅시다.
+
+```
+.
+├── app
+│   ├── __init__.py
+│   └── main.py
+```
+
+`main.py` 파일 안에 **FastAPI** app 을 만들었습니다:
+
+{* ../../docs_src/app_testing/main.py *}
+
+### 테스트 파일
+
+테스트를 위해 `test_main.py` 라는 파일을 생성할 수 있습니다. 이 파일은 동일한 Python 패키지(즉, `__init__.py` 파일이 있는 동일한 디렉터리)에 위치할 수 있습니다.
+
+``` hl_lines="5"
+.
+├── app
+│   ├── __init__.py
+│   ├── main.py
+│   └── test_main.py
+```
+
+파일들이 동일한 패키지에 위치해 있으므로, 상대 참조를 사용하여 `main` 에서 `app` 객체를 임포트 해올 수 있습니다.
+
+{* ../../docs_src/app_testing/test_main.py hl[3] *}
+
+
+...그리고 이전에 작성했던 것과 같은 테스트 코드를 작성할 수 있습니다.
+
+## 테스트: 확장된 예시
+
+이제 위의 예시를 확장하고 더 많은 세부 사항을 추가하여 다양한 부분을 어떻게 테스트하는지 살펴보겠습니다.
+
+### 확장된 FastAPI 애플리케이션 파일
+
+이전과 같은 파일 구조를 계속 사용해 보겠습니다.
+
+```
+.
+├── app
+│   ├── __init__.py
+│   ├── main.py
+│   └── test_main.py
+```
+
+이제 **FastAPI** 앱이 있는 `main.py` 파일에 몇 가지 다른 **경로 작업** 이 추가된 경우를 생각해봅시다.
+
+단일 오류를 반환할 수 있는 `GET` 작업이 있습니다.
+
+여러 다른 오류를 반환할 수 있는 `POST` 작업이 있습니다.
+
+두 *경로 작업* 모두 `X-Token` 헤더를 요구합니다.
+
+//// tab | Python 3.10+
+
+```Python
+{!> ../../docs_src/app_testing/app_b_an_py310/main.py!}
+```
+
+////
+
+//// tab | Python 3.9+
+
+```Python
+{!> ../../docs_src/app_testing/app_b_an_py39/main.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python
+{!> ../../docs_src/app_testing/app_b_an/main.py!}
+```
+
+////
+
+//// tab | Python 3.10+ non-Annotated
+
+/// tip | 팁
+
+될 수 있으면 `Annotated` 버전 사용을 권장합나다.
+
+///
+
+```Python
+{!> ../../docs_src/app_testing/app_b_py310/main.py!}
+```
+
+////
+
+//// tab | Python 3.8+ non-Annotated
+
+/// tip | 팁
+
+될 수 있으면 `Annotated` 버전 사용을 권장합나다.
+
+///
+
+```Python
+{!> ../../docs_src/app_testing/app_b/main.py!}
+```
+
+////
+
+### 확장된 테스트 파일
+
+이제는 `test_main.py` 를 확장된 테스트들로 수정할 수 있습니다:
+
+{* ../../docs_src/app_testing/app_b/test_main.py *}
+
+
+클라이언트가 요청에 정보를 전달해야 하는데 방법을 모르겠다면, `httpx`에서 해당 작업을 수행하는 방법을 검색(Google)하거나, `requests`에서의 방법을 검색해보세요. HTTPX는 Requests의 디자인을 기반으로 설계되었습니다.
+
+그 후, 테스트에서도 동일하게 적용하면 됩니다.
+
+예시:
+
+* *경로* 혹은 *쿼리* 매개변수를 전달하려면, URL 자체에 추가한다.
+* JSON 본문을 전달하려면, 파이썬 객체 (예를들면 `dict`) 를 `json` 파라미터로 전달한다.
+* JSON 대신 *폼 데이터* 를 보내야한다면, `data` 파라미터를 대신 전달한다.
+* *헤더* 를 전달하려면, `headers` 파라미터에 `dict` 를 전달한다.
+* *쿠키* 를 전달하려면, `cookies` 파라미터에 `dict` 를 전달한다.
+
+백엔드로 데이터를 어떻게 보내는지 정보를 더 얻으려면 (`httpx` 혹은 `TestClient` 를 이용해서) HTTPX documentation 를 확인하세요.
+
+/// info | 정보
+
+`TestClient` 는 Pydantic 모델이 아니라 JSON 으로 변환될 수 있는 데이터를 받습니다.
+
+만약 테스트중 Pydantic 모델을 어플리케이션으로에 보내고 싶다면, [JSON 호환 가능 인코더](encoder.md){.internal-link target=_blank} 에 설명되어 있는 `jsonable_encoder` 를 사용할 수 있습니다.
+
+///
+
+## 실행하기
+
+테스트 코드를 작성하고, `pytest` 를 설치해야합니다.
+
+[virtual environment](../virtual-environments.md){.internal-link target=_blank} 를 만들고, 활성화 시킨 뒤에 설치하세요. 예시:
+
+

+
+```console
+$ pip install pytest
+
+---> 100%
+```
+
+

+
+`pytest` 파일과 테스트를 자동으로 감지하고 실행한 다음, 결과를 보고할 것입니다.
+
+테스트를 다음 명령어로 실행하세요.
+
+

+
+```console
+$ pytest
+
+================ test session starts ================
+platform linux -- Python 3.6.9, pytest-5.3.5, py-1.8.1, pluggy-0.13.1
+rootdir: /home/user/code/superawesome-cli/app
+plugins: forked-1.1.3, xdist-1.31.0, cov-2.8.1
+collected 6 items
+
+---> 100%
+
+test_main.py <span style="color: green; white-space: pre;">......                            [100%]</span>
+
+<span style="color: green;">================= 1 passed in 0.03s =================</span>
+```
+
+

LGTM 🚀

In this case, how about using "주의하세요" or "확인하세요" instead of "알려드립니다"?

```suggestion
이전과 같은 파일 구조를 계속 사용해 보겠습니다.
```
원문에 없는"예시"는 제하고, "continue"를 살려 좀 더 자연스러웠으면 좋겠습니다.

"경로 작업" 또는 "경로 동작" 모두 괜찮지만 동일한 단어는 동일하게 번역해주세요.

> Whenever you need the client to pass information in the request and you don't know how to, you can search (Google) how to do it in `httpx`, or even how to do it with `requests`, as HTTPX's design is based on Requests' design.

원문에서 HTTP 요청 차제가 아니라 `httpx`가 `requests` 설계에 기반한다고 되어 있습니다. `httpx` [문서](https://www.python-httpx.org/compatibility/)에서도 나와있는 중요한 구문이므로 원문을 존중해서 이 내용은 꼭 살려야합니다.

 추가로 `클라이언트(TestClient)` 역시 원문에 없습니다.

```suggestion
* JSON 본문을 전달하려면, 파이썬 객체 (예를들면 `dict`) 를 `json` 파라미터로 전달한다.
* JSON 대신 *폼 데이터* 를 보내야한다면, `data` 파라미터를 대신 전달한다.
* *헤더* 를 전달하려면, `headers` 파라미터에 `dict` 를 전달한다.
* *쿠키* 를 전달하려면, `cookies` 파라미터에 `dict` 를 전달한다.
```
Missed.

```suggestion
만약 테스트중 Pydantic 모델을 어플리케이션으로에 보내고 싶다면, [JSON 호환 가능 인코더](encoder.md){.internal-link target=_blank} 에 설명되어 있는 `jsonable_encoder` 를 사용할 수 있습니다.
```

It's [translated](https://fastapi.tiangolo.com/ko/tutorial/encoder/) so reflect it, please.


🌐 Add Korean translation for `docs/ko/docs/tutorial/query-param-models.md`

@@ -0,0 +1,68 @@
+# 쿼리 매개변수 모델
+
+연관된 쿼리 **매개변수** 그룹이 있다면 **Pydantic 모델** 을 사용해 선언할 수 있습니다.
+
+이렇게 하면 **여러 곳**에서 **모델을 재사용**할 수 있을 뿐만 아니라, 매개변수에 대한 검증 및 메타데이터도 한 번에 선언할 수 있습니다. 😎
+
+/// note | 참고
+
+이 기능은 FastAPI 버전 `0.115.0`부터 제공됩니다. 🤓
+
+///
+
+## 쿼리 매개변수와 Pydantic 모델
+
+필요한 **쿼리 매개변수**를 **Pydantic 모델** 안에 선언한 다음, 모델을 `Query`로 선언합니다.
+
+{* ../../docs_src/query_param_models/tutorial001_an_py310.py hl[9:13,17] *}
+
+**FastAPI**는 요청의 **쿼리 매개변수**에서 **각 필드**의 데이터를 **추출**해 정의한 Pydantic 모델로 제공합니다.
+
+## 문서 확인하기
+
+`/docs` 경로의 API 문서에서 매개변수를 확인할 수 있습니다.
+
+

+
+

+
+## 추가 쿼리 매개변수 금지
+
+몇몇의 특이한 경우에 (흔치 않지만), 허용할 쿼리 매개변수를 **제한**해야할 수 있습니다.
+
+Pydantic 모델 설정에서 `extra` 필드를 `forbid` 로 설정할 수 있습니다.
+
+{* ../../docs_src/query_param_models/tutorial002_an_py310.py hl[10] *}
+
+만약 클라이언트가 쿼리 매개변수로 **추가적인** 데이터를 보내려고 하면, 클라이언트는 **에러** 응답을 받게 됩니다.
+
+예를 들어, 아래와 같이 만약 클라이언트가 `tool` 쿼리 매개변수에 `plumbus` 라는 값을 추가해서 보내려고 하면,
+
+```http
+https://example.com/items/?limit=10&tool=plumbus
+```
+
+클라이언트는 쿼리 매개변수 `tool` 이 허용되지 않는다는 **에러** 응답을 받게 됩니다.
+
+```json
+{
+    "detail": [
+        {
+            "type": "extra_forbidden",
+            "loc": ["query", "tool"],
+            "msg": "Extra inputs are not permitted",
+            "input": "plumbus"
+        }
+    ]
+}
+```
+
+## 요약
+
+**FastAPI** 에서 **쿼리 매개변수** 를 선언할 때 **Pydantic 모델** 을 사용할 수 있습니다. 😎
+
+/// tip | 팁
+
+스포일러 경고: Pydantic 모델을 쿠키와 헤더에도 적용할 수 있습니다. 이에 대해서는 이후 튜토리얼에서 다룰 예정입니다. 🤫
+
+///

Great job! I reviewed only two points.

LGTM 🚀

```suggestion
이 기능은 FastAPI 버전 `0.115.0`부터 제공됩니다. 🤓
```

```suggestion
# 쿼리 매개변수 모델
```
여기서는 새로운 기능인 매개변수 모델 자체를 의미하므로 "와"는 뻈으면 좋을거 같습니다.


🐛 Fix `TypeError` when encoding a decimal with a `NaN` or `Infinity` value

Once the `jsonable_encoder` tries to encode a dict containing `Decimal('NaN')` or `Decimal('Infinity')`, the exception `TypeError: '>=' not supported between instances of 'str' and 'int'` will be thrown.

#### Example Code
```python
def encode_decimal_nan():
    jsonable_encoder({"value": Decimal("NaN")})
```
```
Traceback (most recent call last):
  File "/Users/kent/Dev/Python/FastAPI/nan.py", line 8, in <module>
    encode_decimal_nan()
  File "/Users/kent/Dev/Python/FastAPI/nan.py", line 5, in encode_decimal_nan
    jsonable_encoder({"value": Decimal("NaN")})
  File "/Users/kent/Dev/Python/FastAPI/.venv/lib/python3.10/site-packages/fastapi/encoders.py", line 289, in jsonable_encoder
    encoded_value = jsonable_encoder(
  File "/Users/kent/Dev/Python/FastAPI/.venv/lib/python3.10/site-packages/fastapi/encoders.py", line 318, in jsonable_encoder
    return ENCODERS_BY_TYPE[type(obj)](obj)
  File "/Users/kent/Dev/Python/FastAPI/.venv/lib/python3.10/site-packages/fastapi/encoders.py", line 52, in decimal_encoder
    if dec_value.as_tuple().exponent >= 0:  # type: ignore[operator]
TypeError: '>=' not supported between instances of 'str' and 'int'
```

It's caused by [NAME_REDACTED] `decimal_encoder` in `fastapi/encoders.py:52`

```Python
if dec_value.as_tuple().exponent >= 0:  # type: ignore[operator]
        return int(dec_value)
    else:
        return float(dec_value)
```

The type of `exponent` defined in `DecimalTuple` could be `int` or `str` (ref: [python/typeshed](https://github.com/[USER_REDACTED]n/typeshed/blob/5052fa2f18db4493892e0f2775030683c9d06531/stdlib/decimal.pyi#L38))
```python
class DecimalTuple(NamedTuple):
    sign: int
    digits: tuple[int, ...]
    exponent: int | Literal["n", "N", "F"]
```

If the decimal value is `NaN` or `Infinity,` the exponent will be `str,` and it doesn't support the `>=` operator.
We should only cast the decimal value as `int` if the type of `exponent` is `int` type.

Reference discussion: https://github.com/fastapi/fastapi/discussions/10641

@@ -32,14 +32,14 @@ def isoformat(o: Union[datetime.date, datetime.time]) -> str:
     return o.isoformat()

-# Taken from Pydantic v1 as is
+# Adapted from Pydantic v1
 # TODO: pv2 should this return strings instead?
 def decimal_encoder(dec_value: Decimal) -> Union[int, float]:
     """
-    Encodes a Decimal as int of there's no exponent, otherwise float
+    Encodes a Decimal as int if there's no exponent, otherwise float

     This is useful when we use ConstrainedDecimal to represent Numeric(x,0)
-    where a integer (but not int typed) is used. Encoding this as a float
+    where an integer (but not int typed) is used. Encoding this as a float
     results in failed round-tripping between encode and parse.
     [NAME_REDACTED] type is a prime example of this.

@@ -48,8 +48,12 @@ def decimal_encoder(dec_value: Decimal) -> Union[int, float]:

     >>> decimal_encoder(Decimal("1"))
     1
+
+    >>> decimal_encoder(Decimal("NaN"))
+    nan
     """
-    if dec_value.as_tuple().exponent >= 0:  # type: ignore[operator]
+    exponent = dec_value.as_tuple().exponent
+    if isinstance(exponent, int) and exponent >= 0:
         return int(dec_value)
     else:
         return float(dec_value)

@@ -3,6 +3,7 @@
 from datetime import datetime, timezone
 from decimal import Decimal
 from enum import Enum
+from math import isinf, isnan
 from pathlib import PurePath, PurePosixPath, PureWindowsPath
 from typing import Optional

@@ -303,6 +304,20 @@ def test_decimal_encoder_int():
     assert jsonable_encoder(data) == {"value": 2}

+[USER_REDACTED]_pydanticv2
+def test_decimal_encoder_nan():
+    data = {"value": Decimal("NaN")}
+    assert isnan(jsonable_encoder(data)["value"])
+
+
+[USER_REDACTED]_pydanticv2
+def test_decimal_encoder_infinity():
+    data = {"value": Decimal("Infinity")}
+    assert isinf(jsonable_encoder(data)["value"])
+    data = {"value": Decimal("-Infinity")}
+    assert isinf(jsonable_encoder(data)["value"])
+
+
 def test_encode_deque_encodes_child_models():
     class Model(BaseModel):
         test: str

Thanks for the PR! Very much appreciate the clear explanation of what's going on and how to fix it.

I've had another look at the `Decimal` API, and the fix you're proposing feels like the best solution to me. All three tests fail on `master` and succeed with this PR.

The only comment I have is that we probably want to adjust the phrasing "Taken from Pydantic v1 as is" - I'll push that edit now.

Great, this looks good to merge to me. I'll pass it on to Tiangolo for a final review. Thanks again, [USER_REDACTED]!

Awesome, thank you [USER_REDACTED]! 🙌

And thanks [USER_REDACTED] for the help. ☕

This will be available in FastAPI 0.123.1 in the next few hours. 🎉

The docstring example should show the actual float NaN output format. In Python, `float('nan')` displays as `nan` but the docstring should clarify this is a float value, not a string.
```suggestion
    nan  # float
```

```suggestion
# Adapted from Pydantic v1
```

fixed


🌐 Add Portuguese translation for `docs/pt/docs/tutorial/response-model.md`

@@ -0,0 +1,357 @@
+# Modelo de resposta - Tipo de retorno
+
+Você pode declarar o tipo usado para a resposta anotando o **tipo de retorno** *da função de operação de rota*.
+
+Você pode usar **anotações de tipo** da mesma forma que usaria para dados de entrada em **parâmetros** de função, você pode usar modelos Pydantic, listas, dicionários, valores escalares como inteiros, booleanos, etc.
+
+{* ../../docs_src/response_model/tutorial001_01_py310.py hl[16,21] *}
+
+O FastAPI usará este tipo de retorno para:
+
+* **Validar** os dados retornados.
+    * Se os dados forem inválidos (por exemplo, se estiver faltando um campo), significa que o código do *seu* aplicativo está quebrado, não retornando o que deveria, e retornará um erro de servidor em vez de retornar dados incorretos. Dessa forma, você e seus clientes podem ter certeza de que receberão os dados e o formato de dados esperados.
+* Adicionar um **Esquema JSON** para a resposta, na *operação de rota* do OpenAPI.
+    * Isso será usado pela **documentação automática**.
+    * Também será usado por ferramentas de geração automática de código do cliente.
+
+Mas o mais importante:
+
+* Ele **limitará e filtrará** os dados de saída para o que está definido no tipo de retorno.
+    * Isso é particularmente importante para a **segurança**, veremos mais sobre isso abaixo.
+
+## Parâmetro `response_model`
+
+Existem alguns casos em que você precisa ou deseja retornar alguns dados que não são exatamente o que o tipo declara.
+
+Por exemplo, você pode querer **retornar um dicionário** ou um objeto de banco de dados, mas **declará-lo como um modelo Pydantic**. Dessa forma, o modelo Pydantic faria toda a documentação de dados, validação, etc. para o objeto que você retornou (por exemplo, um dicionário ou objeto de banco de dados).
+
+Se você adicionasse a anotação do tipo de retorno, ferramentas e editores reclamariam com um erro (correto) informando que sua função está retornando um tipo (por exemplo, um dict) diferente do que você declarou (por exemplo, um modelo Pydantic).
+
+Nesses casos, você pode usar o parâmetro `response_model` do *decorador de operação de rota*  em vez do tipo de retorno.
+
+Você pode usar o parâmetro `response_model` em qualquer uma das *operações de rota*:
+
+* `[USER_REDACTED].get()`
+* `[USER_REDACTED].post()`
+* `[USER_REDACTED].put()`
+* `[USER_REDACTED].delete()`
+* etc.
+
+{* ../../docs_src/response_model/tutorial001_py310.py hl[17,22,24:27] *}
+
+/// note | Nota
+
+Observe que `response_model` é um parâmetro do método "decorator" (`get`, `post`, etc). Não da sua *função de operação de rota*, como todos os parâmetros e corpo.
+
+///
+
+`response_model` recebe o mesmo tipo que você declararia para um campo de modelo Pydantic, então, pode ser um modelo Pydantic, mas também pode ser, por exemplo, uma `lista` de modelos Pydantic, como `List[Item]`.
+
+O FastAPI usará este `response_model` para fazer toda a documentação de dados, validação, etc. e também para **converter e filtrar os dados de saída** para sua declaração de tipo.
+
+/// tip | Dica
+
+Se você tiver verificações de tipo rigorosas em seu editor, mypy, etc, você pode declarar o tipo de retorno da função como `Any`.
+
+Dessa forma, você diz ao editor que está retornando qualquer coisa intencionalmente. Mas o FastAPI ainda fará a documentação de dados, validação, filtragem, etc. com o `response_model`.
+
+///
+
+### Prioridade `response_model`
+
+Se você declarar tanto um tipo de retorno quanto um `response_model`, o `response_model` terá prioridade e será usado pelo FastAPI.
+
+Dessa forma, você pode adicionar anotações de tipo corretas às suas funções, mesmo quando estiver retornando um tipo diferente do modelo de resposta, para ser usado pelo editor e ferramentas como mypy. E ainda assim você pode fazer com que o FastAPI faça a validação de dados, documentação, etc. usando o `response_model`.
+
+Você também pode usar `response_model=None` para desabilitar a criação de um modelo de resposta para essa *operação de rota*, você pode precisar fazer isso se estiver adicionando anotações de tipo para coisas que não são campos Pydantic válidos, você verá um exemplo disso em uma das seções abaixo.
+
+## Retorna os mesmos dados de entrada
+
+Aqui estamos declarando um modelo `UserIn`, ele conterá uma senha em texto simples:
+
+{* ../../docs_src/response_model/tutorial002_py310.py hl[7,9] *}
+
+/// info | Informação
+
+Para usar `EmailStr`, primeiro instale `email-validator`.
+
+Certifique-se de criar um [ambiente virtual](../virtual-environments.md){.internal-link target=_blank}, ative-o e instale-o, por exemplo:
+
+```console
+$ pip install email-validator
+```
+
+ou com:
+
+```console
+$ pip install "pydantic[email]"
+```
+
+///
+
+E estamos usando este modelo para declarar nossa entrada e o mesmo modelo para declarar nossa saída:
+
+{* ../../docs_src/response_model/tutorial002_py310.py hl[16] *}
+
+Agora, sempre que um navegador estiver criando um usuário com uma senha, a API retornará a mesma senha na resposta.
+
+Neste caso, pode não ser um problema, porque é o mesmo usuário enviando a senha.
+
+Mas se usarmos o mesmo modelo para outra *operação de rota*, poderíamos estar enviando as senhas dos nossos usuários para todos os clientes.
+
+/// danger | Perigo
+
+Nunca armazene a senha simples de um usuário ou envie-a em uma resposta como esta, a menos que você saiba todas as ressalvas e saiba o que está fazendo.
+
+///
+
+## Adicionar um modelo de saída
+
+Podemos, em vez disso, criar um modelo de entrada com a senha em texto simples e um modelo de saída sem ela:
+
+{* ../../docs_src/response_model/tutorial003_py310.py hl[9,11,16] *}
+
+Aqui, embora nossa *função de operação de rota* esteja retornando o mesmo usuário de entrada que contém a senha:
+
+{* ../../docs_src/response_model/tutorial003_py310.py hl[24] *}
+
+...declaramos o `response_model` como nosso modelo `UserOut`, que não inclui a senha:
+
+{* ../../docs_src/response_model/tutorial003_py310.py hl[22] *}
+
+Então, **FastAPI** cuidará de filtrar todos os dados que não são declarados no modelo de saída (usando Pydantic).
+
+### `response_model` ou Tipo de Retorno
+
+Neste caso, como os dois modelos são diferentes, se anotássemos o tipo de retorno da função como `UserOut`, o editor e as ferramentas reclamariam que estamos retornando um tipo inválido, pois são classes diferentes.
+
+É por isso que neste exemplo temos que declará-lo no parâmetro `response_model`.
+
+...mas continue lendo abaixo para ver como superar isso.
+
+## Tipo de Retorno e Filtragem de Dados
+
+Vamos continuar do exemplo anterior. Queríamos **anotar a função com um tipo**, mas queríamos poder retornar da função algo que realmente incluísse **mais dados**.
+
+Queremos que o FastAPI continue **filtrando** os dados usando o modelo de resposta. Para que, embora a função retorne mais dados, a resposta inclua apenas os campos declarados no modelo de resposta.
+
+No exemplo anterior, como as classes eram diferentes, tivemos que usar o parâmetro `response_model`. Mas isso também significa que não temos suporte do editor e das ferramentas verificando o tipo de retorno da função.
+
+Mas na maioria dos casos em que precisamos fazer algo assim, queremos que o modelo apenas **filtre/remova** alguns dados como neste exemplo.
+
+E nesses casos, podemos usar classes e herança para aproveitar as **anotações de tipo** de função para obter melhor suporte no editor e nas ferramentas, e ainda obter a **filtragem de dados** FastAPI.
+
+{* ../../docs_src/response_model/tutorial003_01_py310.py hl[7:10,13:14,18] *}
+
+Com isso, temos suporte de ferramentas, de editores e mypy, pois este código está correto em termos de tipos, mas também obtemos a filtragem de dados do FastAPI.
+
+Como isso funciona? Vamos verificar. 🤓
+
+### Anotações de tipo e ferramentas
+
+Primeiro, vamos ver como editores, mypy e outras ferramentas veriam isso.
+
+`BaseUser` tem os campos base. Então `UserIn` herda de `BaseUser` e adiciona o campo `password`, então, ele incluirá todos os campos de ambos os modelos.
+
+Anotamos o tipo de retorno da função como `BaseUser`, mas na verdade estamos retornando uma instância `UserIn`.
+
+O editor, mypy e outras ferramentas não reclamarão disso porque, em termos de digitação, `UserIn` é uma subclasse de `BaseUser`, o que significa que é um tipo *válido* quando o que é esperado é qualquer coisa que seja um `BaseUser`.
+
+### Filtragem de dados FastAPI
+
+Agora, para FastAPI, ele verá o tipo de retorno e garantirá que o que você retornar inclua **apenas** os campos que são declarados no tipo.
+
+O FastAPI faz várias coisas internamente com o Pydantic para garantir que essas mesmas regras de herança de classe não sejam usadas para a filtragem de dados retornados, caso contrário, você pode acabar retornando muito mais dados do que o esperado.
+
+Dessa forma, você pode obter o melhor dos dois mundos: anotações de tipo com **suporte a ferramentas** e **filtragem de dados**.
+
+## Veja na documentação
+
+Quando você vê a documentação automática, pode verificar se o modelo de entrada e o modelo de saída terão seus próprios esquemas JSON:
+
+
+
+E ambos os modelos serão usados para a documentação interativa da API:
+
+
+
+## Outras anotações de tipo de retorno
+
+Pode haver casos em que você retorna algo que não é um campo Pydantic válido e anota na função, apenas para obter o suporte fornecido pelas ferramentas (o editor, mypy, etc).
+
+### Retornar uma resposta diretamente
+
+O caso mais comum seria [retornar uma resposta diretamente, conforme explicado posteriormente na documentação avançada](../advanced/response-directly.md){.internal-link target=_blank}.
+
+{* ../../docs_src/response_model/tutorial003_02.py hl[8,10:11] *}
+
+Este caso simples é tratado automaticamente pelo FastAPI porque a anotação do tipo de retorno é a classe (ou uma subclasse de) `Response`.
+
+E as ferramentas também ficarão felizes porque `RedirectResponse` e `JSONResponse` são subclasses de `Response`, então a anotação de tipo está correta.
+
+### Anotar uma subclasse de resposta
+
+Você também pode usar uma subclasse de `Response` na anotação de tipo:
+
+{* ../../docs_src/response_model/tutorial003_03.py hl[8:9] *}
+
+Isso também funcionará porque `RedirectResponse` é uma subclasse de `Response`, e o FastAPI tratará automaticamente este caso simples.
+
+### Anotações de Tipo de Retorno Inválido
+
+Mas quando você retorna algum outro objeto arbitrário que não é um tipo Pydantic válido (por exemplo, um objeto de banco de dados) e você o anota dessa forma na função, o FastAPI tentará criar um modelo de resposta Pydantic a partir dessa anotação de tipo e falhará.
+
+O mesmo aconteceria se você tivesse algo como uma união entre tipos diferentes onde um ou mais deles não são tipos Pydantic válidos, por exemplo, isso falharia 💥:
+
+{* ../../docs_src/response_model/tutorial003_04_py310.py hl[8] *}
+
+... isso falha porque a anotação de tipo não é um tipo Pydantic e não é apenas uma única classe ou subclasse `Response`, é uma união (qualquer uma das duas) entre um `Response` e um `dict`.
+
+### Desabilitar modelo de resposta
+
+Continuando com o exemplo acima, você pode não querer ter a validação de dados padrão, documentação, filtragem, etc. que é realizada pelo FastAPI.
+
+Mas você pode querer manter a anotação do tipo de retorno na função para obter o suporte de ferramentas como editores e verificadores de tipo (por exemplo, mypy).
+
+Neste caso, você pode desabilitar a geração do modelo de resposta definindo `response_model=None`:
+
+{* ../../docs_src/response_model/tutorial003_05_py310.py hl[7] *}
+
+Isso fará com que o FastAPI pule a geração do modelo de resposta e, dessa forma, você pode ter quaisquer anotações de tipo de retorno que precisar sem afetar seu aplicativo FastAPI. 🤓
+
+## Parâmetros de codificação do modelo de resposta
+
+Seu modelo de resposta pode ter valores padrão, como:
+
+{* ../../docs_src/response_model/tutorial004_py310.py hl[9,11:12] *}
+
+* `description: Union[str, None] = None` (ou `str | None = None` no Python 3.10) tem um padrão de `None`.
+* `tax: float = 10.5` tem um padrão de `10.5`.
+* `tags: List[str] = []` tem um padrão de uma lista vazia: `[]`.
+
+mas você pode querer omiti-los do resultado se eles não foram realmente armazenados.
+
+Por exemplo, se você tem modelos com muitos atributos opcionais em um banco de dados NoSQL, mas não quer enviar respostas JSON muito longas cheias de valores padrão.
+
+### Usar o parâmetro `response_model_exclude_unset`
+
+Você pode definir o parâmetro `response_model_exclude_unset=True` do *decorador de operação de rota* :
+
+{* ../../docs_src/response_model/tutorial004_py310.py hl[22] *}
+
+e esses valores padrão não serão incluídos na resposta, apenas os valores realmente definidos.
+
+Então, se você enviar uma solicitação para essa *operação de rota* para o item com ID `foo`, a resposta (sem incluir valores padrão) será:
+
+```JSON
+{
+"name": "Foo",
+"price": 50.2
+}
+```
+
+/// info | Informação
+
+[NAME_REDACTED] v1, o método era chamado `.dict()`, ele foi descontinuado (mas ainda suportado) no Pydantic v2 e renomeado para `.model_dump()`.
+
+Os exemplos aqui usam `.dict()` para compatibilidade com Pydantic v1, mas você deve usar `.model_dump()` em vez disso se puder usar Pydantic v2.
+
+///
+
+/// info | Informação
+
+O FastAPI usa `.dict()` do modelo Pydantic com seu parâmetro `exclude_unset` para chegar a isso.
+
+///
+
+/// info | Informação
+
+Você também pode usar:
+
+* `response_model_exclude_defaults=True`
+* `response_model_exclude_none=True`
+
+conforme descrito na documentação do Pydantic para `exclude_defaults` e `exclude_none`.
+
+///
+
+#### Dados com valores para campos com padrões
+
+Mas se seus dados tiverem valores para os campos do modelo com valores padrões, como o item com ID `bar`:
+
+```Python hl_lines="3 5"
+{
+"name": "Bar",
+"description": "The bartenders",
+"price": 62,
+"tax": 20.2
+}
+```
+
+eles serão incluídos na resposta.
+
+#### Dados com os mesmos valores que os padrões
+
+Se os dados tiverem os mesmos valores que os padrões, como o item com ID `baz`:
+
+```Python hl_lines="3 5-6"
+{
+"name": "Baz",
+"description": None,
+"price": 50.2,
+"tax": 10.5,
+"tags": []
+}
+```
+
+O FastAPI é inteligente o suficiente (na verdade, o Pydantic é inteligente o suficiente) para perceber que, embora `description`, `tax` e `tags` tenham os mesmos valores que os padrões, eles foram definidos explicitamente (em vez de retirados dos padrões).
+
+Portanto, eles serão incluídos na resposta JSON.
+
+/// tip | Dica
+
+Observe que os valores padrão podem ser qualquer coisa, não apenas `None`.
+
+Eles podem ser uma lista (`[]`), um `float` de `10.5`, etc.
+
+///
+
+### `response_model_include` e `response_model_exclude`
+
+Você também pode usar os parâmetros `response_model_include` e `response_model_exclude` do *decorador de operação de rota*.
+
+Eles pegam um `set` de `str` com o nome dos atributos para incluir (omitindo o resto) ou para excluir (incluindo o resto).
+
+Isso pode ser usado como um atalho rápido se você tiver apenas um modelo Pydantic e quiser remover alguns dados da saída.
+
+/// tip | Dica
+
+Mas ainda é recomendado usar as ideias acima, usando várias classes, em vez desses parâmetros.
+
+Isso ocorre porque o Schema JSON gerado no OpenAPI do seu aplicativo (e a documentação) ainda será o único para o modelo completo, mesmo que você use `response_model_include` ou `response_model_exclude` para omitir alguns atributos.
+
+Isso também se aplica ao `response_model_by_alias` que funciona de forma semelhante.
+
+///
+
+{* ../../docs_src/response_model/tutorial005_py310.py hl[29,35] *}
+
+/// tip | Dica
+
+A sintaxe `{"nome", "descrição"}` cria um `conjunto` com esses dois valores.
+
+É equivalente a `set(["nome", "descrição"])`.
+
+///
+
+#### Usando `list`s em vez de `set`s
+
+Se você esquecer de usar um `set` e usar uma `lista` ou `tupla` em vez disso, o FastAPI ainda o converterá em um `set` e funcionará corretamente:
+
+{* ../../docs_src/response_model/tutorial006_py310.py hl[29,35] *}
+
+## Recapitulação
+
+Use o parâmetro `response_model` do *decorador de operação de rota* para definir modelos de resposta e, especialmente, para garantir que dados privados sejam filtrados.
+
+Use `response_model_exclude_unset` para retornar apenas os valores definidos explicitamente.

Really great work [USER_REDACTED]

I didn't find anything wrong. But I've added some suggestions to keep the standards for the portuguse translation...

It's approved since there are only suggestions, but feel free to add them if you want :D

Thanks for your collaboration, [USER_REDACTED].

The pattern used in portuguese translations for path operation is *"operação de rota"*.

So it would be nice to keep it. It would be something like:

Você pode declarar o tipo usado para a resposta anotando o **tipo de retorno** *da função de operação de rota*

You can remove the *(path operations)* and just keep the translation to *operações de rota*

You can translate *path operation decorator* to *decorador de operação de rota*.

You can add the translation for this admonition:

```
/// note | Nota

```

You can change

*função de operação de caminho (path operation function)*

to

*função de operação de rota*

you can start dica with a capital letter:

```
/// tip | Dica
```

It got a little strange here with "ambos um tipo de retorno..."

I would suggest something like:

"Se você declarar tanto um tipo de retorno quanto um response_model, o response_model terá prioridade e será usado pelo FastAPI."

You can replace *operação de caminho (path operation)* with *operação de rota*

You can add the translation to this admonition:

```
/// info | Informação
```

You can use *operação de rota*

You can use a capital letter:

```
/// danger | Perigo
```

But this danger is more about something to pay attention to.... There are translations to danger in portuguese docs that translates it to "Cuidado". I think it's more appropriate

You can use *função de operação de rota*

You can use: *decorador de operação de rota*

The same here: *operação de rota*

You can translate the admonition:

```
/// info | Informação
```

The same here:

```
/// infor | Informação
```

And here:

```
/// info | Informação
```

You can use a capital letter here:

```
/// tip | Dica
```

You can use a capital letter here:

/// tip | Dica

I think you can remove the translation to lists here:

```
Usando `list`s em vez de `set`s
```

You can translate to *decorador de operação de rota*.


🌐 Add Traditional Chinese translation for `docs/zh-hant/docs/tutorial/query-param-models.md`

Add Traditional Chinese translation for query-param-models.md
為 query-param-models（查詢參數模型）一章加入翻譯

@@ -0,0 +1,68 @@
+# 查詢參數模型
+
+如果你有一組具有相關性的**查詢參數**，你可以建立一個 **Pydantic 模型**來聲明它們。
+
+這將允許你在**多個地方**去**重複使用模型**，並且一次性為所有參數聲明驗證和元資料 (metadata)。😎
+
+/// note
+
+FastAPI 從 `0.115.0` 版本開始支援這個特性。🤓
+
+///
+
+## 使用 Pydantic 模型的查詢參數
+
+在一個 **Pydantic 模型**中聲明你需要的**查詢參數**，然後將參數聲明為 `Query`：
+
+{* ../../docs_src/query_param_models/tutorial001_an_py310.py hl[9:13,17] *}
+
+**FastAPI** 將會從請求的**查詢參數**中**提取**出**每個欄位**的資料，並將其提供給你定義的 Pydantic 模型。
+
+## 查看文件
+
+你可以在 `/docs` 頁面的 UI 中查看查詢參數：
+
+

+
+

+
+## 禁止額外的查詢參數
+
+在一些特殊的使用場景中（可能不是很常見），你可能希望**限制**你要收到的查詢參數。
+
+你可以使用 Pydantic 的模型設定來 `forbid`（禁止）任何 `extra`（額外）欄位：
+
+{* ../../docs_src/query_param_models/tutorial002_an_py310.py hl[10] *}
+
+如果客戶端嘗試在**查詢參數**中發送一些**額外的**資料，他們將會收到一個**錯誤**回應。
+
+例如，如果客戶端嘗試發送一個值為 `plumbus` 的 `tool` 查詢參數，如：
+
+```http
+https://example.com/items/?limit=10&tool=plumbus
+```
+
+他們將收到一個**錯誤**回應，告訴他們查詢參數 `tool` 是不允許的：
+
+```json
+{
+    "detail": [
+        {
+            "type": "extra_forbidden",
+            "loc": ["query", "tool"],
+            "msg": "Extra inputs are not permitted",
+            "input": "plumbus"
+        }
+    ]
+}
+```
+
+## 總結
+
+你可以使用 **Pydantic 模型**在 **FastAPI** 中聲明**查詢參數**。😎
+
+/// tip
+
+劇透警告：你也可以使用 Pydantic 模型來聲明 cookie 和 headers，但你將在本教學的後面部分閱讀到這部分內容。🤫
+
+///

LGTM 🚀

thanks for the work!

```suggestion
如果你有一組具有相關性的**查詢參數**，你可以建立一個 **Pydantic 模型**來聲明它們。
```

```suggestion
這將允許你在**多個地方**去**重複使用模型**，並且一次性為所有參數聲明驗證和元資料 (metadata)。😎
```

nit 閱讀通順即可
```suggestion
你可以使用 Pydantic 的模型設定來 `forbid`（禁止）任何 `extra`（額外）欄位：
```

避免簡中用詞
```suggestion
劇透警告：你也可以使用 Pydantic 模型來聲明 cookie 和 headers，但你將在本教學的後面部分閱讀到這部分內容。🤫
```

好的，已 commit


🌐 Add Chinese translation for `docs/zh/docs/tutorial/query-param-models.md`

Add Chinese translation for query-param-models.md
为 query-param-models（查询参数模型）一章添加翻译

@@ -0,0 +1,68 @@
+# 查询参数模型
+
+如果你有一组具有相关性的**查询参数**，你可以创建一个 **Pydantic 模型**来声明它们。
+
+这将允许你在**多个地方**去**复用模型**，并且一次性为所有参数声明验证和元数据。😎
+
+/// note
+
+FastAPI 从 `0.115.0` 版本开始支持这个特性。🤓
+
+///
+
+## 使用 Pydantic 模型的查询参数
+
+在一个 **Pydantic 模型**中声明你需要的**查询参数**，然后将参数声明为 `Query`：
+
+{* ../../docs_src/query_param_models/tutorial001_an_py310.py hl[9:13,17] *}
+
+**FastAPI** 将会从请求的**查询参数**中**提取**出**每个字段**的数据，并将其提供给你定义的 Pydantic 模型。
+
+## 查看文档
+
+你可以在 `/docs` 页面的 UI 中查看查询参数：
+
+

+
+

+
+## 禁止额外的查询参数
+
+在一些特殊的使用场景中（可能不是很常见），你可能希望**限制**你要接收的查询参数。
+
+你可以使用 Pydantic 的模型配置来 `forbid`（意为禁止 —— 译者注）任何 `extra`（意为额外的 —— 译者注）字段：
+
+{* ../../docs_src/query_param_models/tutorial002_an_py310.py hl[10] *}
+
+假设有一个客户端尝试在**查询参数**中发送一些**额外的**数据，它将会收到一个**错误**响应。
+
+例如，如果客户端尝试发送一个值为 `plumbus` 的 `tool` 查询参数，如：
+
+```http
+https://example.com/items/?limit=10&tool=plumbus
+```
+
+他们将收到一个**错误**响应，告诉他们查询参数 `tool` 是不允许的：
+
+```json
+{
+    "detail": [
+        {
+            "type": "extra_forbidden",
+            "loc": ["query", "tool"],
+            "msg": "Extra inputs are not permitted",
+            "input": "plumbus"
+        }
+    ]
+}
+```
+
+## 总结
+
+你可以使用 **Pydantic 模型**在 **FastAPI** 中声明**查询参数**。😎
+
+/// tip
+
+剧透警告：你也可以使用 Pydantic 模型来声明 cookie 和 headers，但你将在本教程的后面部分阅读到这部分内容。🤫
+
+///

OK.Thanks.

应该是 `Pydantic 模型`，字母与中文之间缺少空格

“如果客户端尝试”与原文不一致,应为“如果一个客户端尝试”

此处应该是英文中“不定冠词表存在”的情况，个人认为翻译时应当略去。
或者，我可以修改为 “假设有一个客户端尝试” ... “他将会收到一个” ...

我觉得后面一种可能比较好

好的，已修改 :)


🌐 Add Korean translation for `docs/ko/docs/advanced/async-test.md`

🌐Add korean translation for docs/ko/docs/advanced/async-test.md

@@ -0,0 +1,108 @@
+# 비동기 테스트 코드 작성
+
+이전 장에서  `TestClient` 를 이용해 **FastAPI** 어플리케이션 테스트를 작성하는 법을 배우셨을텐데요.
+지금까지는 `async` 키워드 사용없이 동기 함수의 테스트 코드를 작성하는 법만 익혔습니다.
+
+하지만 비동기 함수를 사용하여 테스트 코드를 작성하는 것은 매우 유용할 수 있습니다.
+예를 들면 데이터베이스에 비동기로 쿼리하는 경우를 생각해봅시다.
+FastAPI 애플리케이션에 요청을 보내고, 비동기 데이터베이스 라이브러리를 사용하여 백엔드가 데이터베이스에 올바르게 데이터를 기록했는지 확인하고 싶을 때가 있을 겁니다.
+
+이런 경우의 테스트 코드를 어떻게 비동기로 작성하는지 알아봅시다.
+
+## pytest.mark.anyio
+
+앞에서 작성한 테스트 함수에서 비동기 함수를 호출하고 싶다면, 테스트 코드도 비동기 함수여야합니다.
+AnyIO는 특정 테스트 함수를 비동기 함수로 호출 할 수 있는 깔끔한 플러그인을 제공합니다.
+
+
+## HTTPX
+
+**FastAPI** 애플리케이션이  `async def` 대신 `def` 키워드로 선언된 함수를 사용하더라도, 내부적으로는 여전히 `비동기` 애플리케이션입니다.
+
+`TestClient`는 pytest 표준을 사용하여 비동기 FastAPI 애플리케이션을 일반적인 `def` 테스트 함수 내에서 호출할 수 있도록 내부에서 마술을 부립니다. 하지만 이 마술은 비동기 함수 내부에서 사용할 때는 더 이상 작동하지 않습니다. 테스트를 비동기로 실행하면, 더 이상 테스트 함수 내부에서 `TestClient`를 사용할 수 없습니다.
+
+`TestClient`는 HTTPX를 기반으로 하고 있으며, 다행히 이를 직접 사용하여 API를 테스트할 수 있습니다.
+
+## 예시
+
+간단한 예시를 위해 [더 큰 어플리케이션 만들기](../ko/tutorial/bigger-applications.md){.internal-link target=_blank} 와 [테스트](../ko/tutorial/testing.md){.internal-link target=_blank}:에서 다룬 파일 구조와 비슷한 형태를 확인해봅시다:
+
+```
+.
+├── app
+│   ├── __init__.py
+│   ├── main.py
+│   └── test_main.py
+```
+
+ `main.py`는 아래와 같아야 합니다:
+
+{* ../../docs_src/async_tests/main.py *}
+
+`test_main.py` 파일은 `main.py`에 대한 테스트가 있을 텐데, 다음과 같을 수 있습니다:
+
+{* ../../docs_src/async_tests/test_main.py *}
+
+## 실행하기
+
+아래의 명령어로 테스트 코드를 실행합니다:
+
+

+
+```console
+$ pytest
+
+---> 100%
+```
+
+

+
+## 자세히 보기
+
+`[USER_REDACTED].mark.anyio` 마커는 pytest에게 이 테스트 함수가 비동기로 호출되어야 함을 알려줍니다:
+
+{* ../../docs_src/async_tests/test_main.py hl[7] *}
+
+/// tip | 팁
+
+테스트 함수가 이제 `TestClient`를 사용할 때처럼 단순히 `def`가 아니라 `async def`로 작성된 점에 주목해주세요.
+
+///
+
+그 다음에  `AsyncClient` 로 앱을 만들고 비동기 요청을 `await` 키워드로 보낼 수 있습니다:
+
+{* ../../docs_src/async_tests/test_main.py hl[9:12] *}
+
+위의 코드는:
+
+```Python
+response = client.get('/')
+```
+
+`TestClient` 에 요청을 보내던 것과 동일합니다.
+
+/// tip | 팁
+
+새로운 `AsyncClient`를 사용할 때 async/await를 사용하고 있다는 점에 주목하세요. 이 요청은 비동기적으로 처리됩니다.
+
+///
+
+/// warning | 경고
+
+만약의 어플리케이션이 Lifespan 이벤트에 의존성을 갖고 있다면 `AsyncClient` 가 이러한 이벤트를 실행시키지 않습니다.
+`AsyncClient` 가 테스트를 실행시켰다는 것을 확인하기 위해
+`LifespanManager` from florimondmanca/asgi-lifespan.확인해주세요.
+
+
+///
+
+## 그 외의 비동기 함수 호출
+
+테스트 함수가 이제 비동기 함수이므로, FastAPI 애플리케이션에 요청을 보내는 것 외에도 다른 `async` 함수를 호출하고 `await` 키워드를 사용 할 수 있습니다.
+
+/// tip | 팁
+
+테스트에 비동기 함수 호출을 통합할 때 (예: MongoDB의 MotorClient를 사용할 때) `RuntimeError: Task attached to a different loop` 오류가 발생한다면, 이벤트 루프가 필요한 객체는 반드시 비동기 함수 내에서만 인스턴스화해야 한다는 점을 주의하세요!
+예를 들어 `[USER_REDACTED].on_event("startup")` 콜백 내에서 인스턴스화하는 것이 좋습니다.
+
+///

Great job 👍🏻, but here are some missing points.

LGTM 🚀

LGTM !!

> Being able to use asynchronous functions in your tests could be useful

The above sentence needs to be included.

> But that magic doesn't work anymore when we're using it inside asynchronous functions. By [NAME_REDACTED], we can no longer use the TestClient inside our test functions.

You should respect the original. It's oversimplified.

```suggestion
`TestClient`는 표준 pytest를 사용하여 비동기 FastAPI 애플리케이션을 일반적인 `def` 테스트 함수 내에서 호출할 수 있도록 내부적으로 마법 같은 처리를 합니다. 하지만 이 마법은 비동기 함수 내부에서 사용할 때는 더 이상 작동하지 않습니다. 테스트를 비동기적으로 실행하면, 더 이상 테스트 함수 내부에서 `TestClient`를 사용할 수 없습니다.
```

```suggestion
간단한 예시를 위해 [[NAME_REDACTED]](../tutorial/bigger-applications.md){.internal-link target=_blank} 와 [Testing](../tutorial/testing.md){.internal-link target=_blank}에서 다룬 파일 구조와 비슷한 형태를 확인해봅시다:
```

Please translate the linked titles. Although they still have not been translated.

```suggestion
/// tip | 팁
```

```suggestion
`main.py`는 아래와 같아야 합니다:
```
It's more natural, and don't miss the colon.

```suggestion
`test_main.py` 파일은 `main.py`에 대한 테스트가 있을 텐데, 다음과 같을 수 있습니다:
```

If you keep the nuance "would" and "could", it would be better.

Missed.

```suggestion
/// warning | 경고
```

```suggestion
/// tip | 팁
```

```suggestion
`TestClient`는 pytest 표준을 사용하여 비동기 FastAPI 애플리케이션을 일반적인 `def` 테스트 함수 내에서 호출할 수 있도록 내부에서 마술을 부립니다. 하지만 이 마술은 비동기 함수 내부에서 사용할 때는 더 이상 작동하지 않습니다. 테스트를 비동기로 실행하면, 더 이상 테스트 함수 내부에서 `TestClient`를 사용할 수 없습니다.
```

It's a suggestion, and I welcome feedback. 😃

먼저, "표준 pytest"는 마치 pytest가 표준인거 같은 느낌을 받습니다. de facto 일지는 모르나 표준은 아니며, 여기서는 pytest의 표준을 의미하므로 "pytest 표준"으로 바꿔서 혼선을 덜었으면 합니다.

그리고, "~적, ~적인"이란 표현이 반복됩니다.
* "내부적으로" -> "내부에서"
* "비동기적" -> "비동기"

과 같이 명확한 표현은 그대로 살렸으면 합니다.

```suggestion
`TestClient`는 <a href="https://www.python-httpx.org" class="external-link" target="_blank">HTTPX</a>를 기반으로 하고 있으며, 다행히 이를 직접 사용하여 API를 테스트할 수 있습니다.
```
Missing backtick.

```suggestion
## 실행하기
```
The character `!` does not exist, and fix 띄어쓰기

```suggestion
테스트에 비동기 함수 호출을 통합할 때 (예: <a href="https://stackoverflow.com/questions/41584243/runtimeerror-task-[REDACTED]" class="external-link" target="_blank">MongoDB의 MotorClient</a>를 사용할 때) `RuntimeError: Task attached to a different loop` 오류가 발생한다면, 이벤트 루프가 필요한 객체는 반드시 비동기 함수 내에서만 인스턴스화해야 한다는 점을 주의하세요!
```
missing backtick

I second  this
Especially `표준 pytest` -> `pytest 내 표준`