開發 - 貢獻¶
首先，您可能想先了解協助 FastAPI 和獲得協助的基本方法。
開發¶
如果您已經複製了 fastapi 儲存庫，並且想要深入研究程式碼，以下是一些設定環境的指南。
虛擬環境¶
請遵循指示建立並啟用 fastapi 內部程式碼的虛擬環境。
使用 pip 安裝必要套件¶
啟用環境後，安裝必要的套件
$ pip install -r requirements.txt
---> 100%
它會將所有依賴項和您的本地 FastAPI 安裝到您的本地環境中。
使用您的本地 FastAPI¶
如果您建立一個導入並使用 FastAPI 的 Python 檔案，並使用您本地環境中的 Python 執行它，它將使用您複製的本地 FastAPI 原始碼。
如果您在再次執行該 Python 檔案時更新了本地 FastAPI 原始碼，它將使用您剛編輯的最新版 FastAPI。
這樣，您就不必「安裝」您的本地版本即可測試每個變更。
「技術細節」
這只會在您使用內含的 requirements.txt 安裝，而不是直接執行 pip install fastapi 時發生。
這是因為在 requirements.txt 檔案中，本地版本的 FastAPI 標記為以「可編輯」模式安裝，並使用 -e 選項。
格式化程式碼¶
您可以執行一個腳本來格式化和清理所有程式碼
$ bash scripts/format.sh
它還會自動排序所有導入。
測試¶
您可以執行一個本地腳本來測試所有程式碼並產生 HTML 格式的涵蓋率報告
$ bash scripts/test-cov-html.sh
此命令會產生一個目錄 ./htmlcov/，如果您在瀏覽器中開啟 ./htmlcov/index.html 檔案，您可以互動式地瀏覽測試涵蓋的程式碼區域，並注意是否有任何區域遺漏。
文件¶
首先，請確定您已按照上述說明設定環境，這將安裝所有必要套件。
即時文件¶
在本地開發期間，有一個腳本會建置網站並檢查是否有任何變更，並即時重新載入
$ python ./scripts/docs.py live
<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008
<span style="color: green;">[INFO]</span> Start watching changes
<span style="color: green;">[INFO]</span> Start detecting changes
它將在 http://127.0.0.1:8008 上提供文件。
這樣，您可以編輯文件/原始檔並即時查看變更。
提示
或者，您可以手動執行與腳本相同的步驟。
進入語言目錄，主要的英文文件位於 docs/en/
$ cd docs/en/
然後在該目錄中執行 mkdocs
$ mkdocs serve --dev-addr 8008
Typer CLI（選用）¶
這裡的說明顯示如何直接使用 python 程式執行 ./scripts/docs.py 中的腳本。
但您也可以使用 Typer CLI，安裝完成後，您將在終端機中獲得指令的自動完成。
如果您安裝了 Typer CLI，您可以使用以下指令安裝自動完成：
$ typer --install-completion
zsh completion installed in /home/user/.bashrc.
Completion will take effect once you restart the terminal.
文件結構¶
此文件使用 MkDocs 建立。
並且在 ./scripts/docs.py 中有一些額外的工具/腳本來處理翻譯。
提示
您不需要查看 ./scripts/docs.py 中的程式碼，只需在命令列中使用它即可。
所有文件都以 Markdown 格式儲存在 ./docs/en/ 目錄中。
許多教學都包含程式碼區塊。
在大多數情況下，這些程式碼區塊實際上是完整的應用程式，可以直接執行。
事實上，這些程式碼區塊並不是寫在 Markdown 裡面的，它們是位於 ./docs_src/ 目錄中的 Python 檔案。
這些 Python 檔案會在產生網站時被包含/注入到文件中。
測試文件¶
大多數測試實際上都是針對文件中範例原始檔執行的。
這有助於確保：
- 文件是最新的。
- 文件中的範例可以直接執行。
- 大多數功能都包含在文件中，並由測試覆蓋率確保。
同時作為應用程式和文件¶
如果您執行範例，例如：
$ fastapi dev tutorial001.py
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
由於 Uvicorn 預設會使用 8000 連接埠，因此在 8008 連接埠上的文件不會發生衝突。
翻譯¶
非常歡迎協助翻譯！沒有社群的幫助，這是不可能完成的。 🌎 🚀
以下是如何協助翻譯的步驟。
技巧和準則¶
-
檢查目前 現有的拉取請求 (Pull Request) 是否有您的語言。您可以使用語言標籤篩選拉取請求。例如，西班牙文的標籤是
lang-es。 -
審閱這些拉取請求，請求更改或批准它們。對於我不懂的語言，我會在合併之前等待其他人審閱翻譯。
-
檢查是否有 GitHub 討論區 來協調您語言的翻譯。您可以訂閱它，當有新的拉取請求需要審閱時，會自動在討論區中新增評論。
-
如果您翻譯頁面，請為每個翻譯的頁面新增一個拉取請求。這將使其他人更容易進行審閱。
-
要檢查您要翻譯的語言的兩個字母代碼，您可以使用表格 ISO 639-1 代碼列表。
現有語言¶
假設您要翻譯已有部分頁面翻譯的語言，例如西班牙文。
西班牙文的兩個字母代碼是 es。因此，西班牙文翻譯的目錄位於 docs/es/。
提示
主要的（「官方」）語言是英文，位於 docs/en/。
現在為西班牙語文件執行即時伺服器。
// Use the command "live" and pass the language code as a CLI argument
$ python ./scripts/docs.py live es
<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008
<span style="color: green;">[INFO]</span> Start watching changes
<span style="color: green;">[INFO]</span> Start detecting changes
提示
或者，您可以手動執行與腳本相同的步驟。
進入語言目錄，西班牙語翻譯位於 docs/es/。
$ cd docs/es/
然後在該目錄中執行 mkdocs
$ mkdocs serve --dev-addr 8008
現在您可以前往 http://127.0.0.1:8008 並即時查看您的變更。
您會看到每種語言都有所有頁面。但有些頁面尚未翻譯，頂部會有一個關於缺少翻譯的資訊方塊。
現在假設您要新增「功能」區段的翻譯 功能。
- 複製位於以下位置的檔案
docs/en/docs/features.md
- 將其貼到完全相同的位置，但使用您要翻譯的語言，例如：
docs/es/docs/features.md
提示
請注意，路徑和檔案名稱中唯一的更改是語言代碼，從 en 更改為 es。
如果您前往您的瀏覽器，您會看到現在文件顯示您的新區段（頂部的資訊方塊已消失）。🎉
現在您可以翻譯所有內容，並在儲存檔案時查看其外觀。
不要翻譯這些頁面¶
🚨 不要翻譯
reference/下的檔案release-notes.mdfastapi-people.mdexternal-links.mdnewsletter.mdmanagement-tasks.mdmanagement.md
其中一些檔案更新非常頻繁，翻譯總是會落後，或者它們包含來自英文原始檔案的主要內容等。
新增語言¶
假設您要新增尚未翻譯的語言的翻譯，甚至連某些頁面都沒有翻譯。
假設您要新增克里奧爾語的翻譯，但文件中還沒有。
檢查上面的連結，「克里奧爾語」的代碼是 ht。
下一步是執行腳本來產生新的翻譯目錄
// Use the command new-lang, pass the language code as a CLI argument
$ python ./scripts/docs.py new-lang ht
Successfully initialized: docs/ht
現在您可以在您的程式碼編輯器中檢查新建立的目錄 docs/ht/。
該命令建立了一個檔案 docs/ht/mkdocs.yml，其中包含一個簡單的設定，該設定繼承了 en 版本的所有內容。
INHERIT: ../en/mkdocs.yml
提示
您也可以手動使用這些內容建立該檔案。
該命令還為首頁建立了一個虛擬檔案 docs/ht/index.md，您可以先翻譯該檔案。
您可以繼續執行「現有語言」的先前指示來完成該過程。
您可以使用這兩個檔案 docs/ht/mkdocs.yml 和 docs/ht/index.md 提交第一個拉取請求。🎉
預覽結果¶
如上所述，您可以使用帶有 live 命令的 ./scripts/docs.py 來預覽結果（或 mkdocs serve）。
完成後，您還可以測試所有內容的線上外觀，包括所有其他語言。
要執行此操作，請先建置所有文件
// Use the command "build-all", this will take a bit
$ python ./scripts/docs.py build-all
Building docs for: en
Building docs for: es
Successfully built docs for: es
這會建置每個語言的所有獨立 MkDocs 網站，將它們組合起來，並在 ./site/ 產生最終輸出。
然後您可以使用命令 serve 來提供服務
// Use the command "serve" after running "build-all"
$ python ./scripts/docs.py serve
Warning: this is a very simple server. For development, use mkdocs serve instead.
This is here only to preview a site with translations already built.
Make sure you run the build-all command first.
Serving at: http://127.0.0.1:8008
翻譯的特定提示和指導方針¶
-
僅翻譯 Markdown 文件（
.md）。不要翻譯./docs_src中的程式碼範例。 -
在 Markdown 文件中的程式碼區塊中，翻譯註釋（
# 註釋），但保留其餘部分不變。 -
不要更改任何用「``」括起來的內容（行內程式碼）。
-
在以
///開頭的行中，僅翻譯"... 文字 ..."部分。保留其餘部分不變。 -
您可以翻譯像
/// warning這樣的資訊方塊，例如使用/// warning | 注意。但不要更改///後面的第一個詞，它決定了資訊方塊的顏色。 -
不要更改圖片、程式碼檔案、Markdown 文件連結中的路徑。
-
然而，當 Markdown 文件被翻譯後，連結到其標題的
#hash-parts（井字號片段）可能會改變。如果可能，請更新這些連結。- 使用正規表達式
#[^# ]在翻譯後的文件中搜尋此類連結。 - 在所有已翻譯成您的語言的文件中搜尋
your-translated-document.md（您已翻譯的文件.md）。例如，VS Code 有個選項「編輯」->「在檔案中尋找」。 - 翻譯文件時，不要「預先翻譯」連結到未翻譯文件標題的
#hash-parts（井字號片段）。
- 使用正規表達式