コンテンツへスキップ

開発 - 貢献

まず、FastAPI を助け、助けを得る基本的な方法を知りたいかもしれません。

開発中

fastapi リポジトリを既にクローンしており、コードを深く掘り下げたい場合は、環境をセットアップするためのいくつかのガイドラインを以下に示します。

仮想環境

fastapi の内部コード用に仮想環境を作成およびアクティブ化するための指示に従ってください。

要件をインストール

環境をアクティブ化した後、必要なパッケージをインストールします

$ pip install -r requirements.txt

---> 100%

uv を持っている場合

$ uv pip install -r requirements.txt

---> 100%

これにより、すべての依存関係とローカルのFastAPIがローカル環境にインストールされます。

ローカルのFastAPIを使用する

FastAPI をインポートして使用する Python ファイルを作成し、それをローカル環境の Python で実行すると、クローンされたローカルの FastAPI ソースコードが使用されます。

そして、そのローカルの FastAPI ソースコードを更新して再度 Python ファイルを実行すると、編集したばかりの新しいバージョンの FastAPI が使用されます。

これにより、変更をテストするためにローカルバージョンを「インストール」する必要がなくなります。

技術的な詳細

これは、pip install fastapi を直接実行するのではなく、この含まれている requirements.txt を使用してインストールした場合にのみ発生します。

これは、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 127.0.0.1:8008

Typer CLI (オプション)

ここでの指示は、./scripts/docs.py のスクリプトを python プログラムで直接使用する方法を示しています。

しかし、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 のコードを見る必要はありません。コマンドラインでそれを使用するだけです。

すべてのドキュメントは、ディレクトリ ./docs/en/ 内の Markdown 形式です。

多くのチュートリアルにはコードブロックがあります。

ほとんどの場合、これらのコードブロックは、そのまま実行できる実際の完全なアプリケーションです。

実際、これらのコードブロックは 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 のドキュメントと競合することはありません。

翻訳

注意

翻訳に関する最新情報

ドキュメントの翻訳の処理方法を更新しています。

これまで、私たちはコミュニティメンバーにプルリクエストを介してページの翻訳を依頼し、少なくとも2人のネイティブスピーカーによってレビューされてきました。これにより、FastAPIをより多くのユーザーに届けることができましたが、いくつかの課題にも直面しました。一部の言語では翻訳されたページがごくわずかであり、その他は古く、時間の経過とともに維持が困難です。これを改善するために、翻訳をより効率的に管理するための自動化ツール🤖を開発しています。準備ができ次第、ドキュメントは機械翻訳され、公開前に少なくとも2人のネイティブスピーカーによって✅レビューされます。これにより、メンテナーのレビュー負担を軽減しながら、翻訳を最新の状態に保つことができます。

現在変更されている点

  • 🚫 コミュニティから提出された新しい翻訳PRは受け付けなくなりました。

  • ⏳ 既存のオープンPRはレビューされ、今後3週間以内（2025年7月11日以降）に完了した場合、引き続きマージされる可能性があります。

  • 🌐 将来的には、少なくとも3人のアクティブなネイティブスピーカーが翻訳をレビューおよび維持できる言語のみをサポートします。

この移行は、翻訳の一貫性とタイムリー性を高め、貢献者をより良くサポートするのに役立ちます🙌。これまで貢献してくださった皆様、ありがとうございました！💖

翻訳のヘルプは 大変 感謝されています！コミュニティの助けなしではできません。🌎 🚀

以下は、翻訳を支援するための手順です。

ヒントとガイドライン

  • あなたの言語について、現在存在するプルリクエストを確認してください。あなたの言語のラベルが付いているプルリクエストでフィルタリングできます。例えば、スペイン語の場合、ラベルはlang-esです。

  • それらのプルリクエストをレビューし、変更を要求したり、承認したりしてください。私が話せない言語については、マージする前に他の何人かが翻訳をレビューするのを待ちます。

ヒント

既存のプルリクエストに変更提案のコメントを追加できます。

承認または変更要求のためにプルリクエストレビューを追加することに関するドキュメントを確認してください。

  • あなたの言語の翻訳を調整するためのGitHub Discussionがあるかどうかを確認してください。それに購読すると、レビューする新しいプルリクエストがあるときに、自動コメントがディスカッションに追加されます。

  • ページを翻訳する場合、翻訳されたページごとに1つのプルリクエストを追加してください。これにより、他の人がレビューしやすくなります。

  • 翻訳したい言語の2文字コードを確認するには、ISO 639-1 コードのリストの表を使用できます。

既存の言語

スペイン語のように、一部のページが既に翻訳されている言語のページを翻訳したいとします。

スペイン語の場合、2文字コードはesです。したがって、スペイン語の翻訳ディレクトリはdocs/にあります。

ヒント

メイン（「公式」）言語は英語で、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/ です。

$ cd docs/

次に、そのディレクトリで mkdocs を実行します。

$ mkdocs serve --dev-addr 127.0.0.1:8008

これで、http://127.0.0.1:8008 にアクセスして、変更をライブで確認できます。

すべての言語にはすべてのページがあることがわかります。しかし、一部のページは翻訳されておらず、上部に翻訳が不足していることに関する情報ボックスが表示されます。

次に、機能セクションの翻訳を追加したいとします。

  • ファイルをコピーします
docs/en/docs/features.md
  • 同じ場所に貼り付けますが、翻訳したい言語の場合、例えば
docs/docs/features.md

ヒント

パスとファイル名で唯一の変更点は、言語コードが en から es に変更されていることです。

ブラウザにアクセスすると、新しいセクションが表示されていることがわかります（上部の情報ボックスは消えています）。🎉

これで、ファイルを保存しながら、すべてを翻訳して表示を確認できます。

これらのページは翻訳しないでください

🚨 翻訳しないでください

  • reference/以下のファイル
  • release-notes.md
  • fastapi-people.md
  • external-links.md
  • newsletter.md
  • management-tasks.md
  • management.md
  • contributing.md

これらのファイルの中には非常に頻繁に更新されるものがあり、翻訳は常に遅れてしまうか、英語のソースファイルからメインコンテンツを取り込んでいるものなどがあります。

新しい言語をリクエストする

まだ翻訳されていない言語、例えばラテン語の翻訳をリクエストしたいとします。

その言語に関する議論がない場合、新しい言語をリクエストすることから始めることができます。そのためには、次の手順に従ってください。

  • テンプレートに従って新しい議論を作成します。
  • 数人のネイティブスピーカーに議論にコメントしてもらい、その言語の翻訳レビューを手伝うことを約束してもらいます。

議論に参加者が複数いる場合、FastAPIチームはそれを評価し、公式の翻訳にすることができます。

その後、ドキュメントはAIを使用して自動的に翻訳され、ネイティブスピーカーのチームが翻訳をレビューし、AIプロンプトの調整を手伝うことができます。

新しい翻訳が作成された場合、例えばドキュメントが更新されたり新しいセクションが追加されたりすると、同じ議論に新しい翻訳へのリンクとともにコメントが追加され、レビューを促します。

新しい言語

Note

これらの手順はFastAPIチームによって実行されます。

上記のリンク（ISO 639-1コードのリスト）を確認すると、ラテン語の2文字コードがlaであることがわかります。

新しい言語の新しいディレクトリを作成するには、次のスクリプトを実行します。

// Use the command new-lang, pass the language code as a CLI argument
$ python ./scripts/docs.py new-lang la

Successfully initialized: docs/la

これで、コードエディタで新しく作成されたディレクトリ docs/la/ を確認できます。

このコマンドは、en バージョンのすべてを継承するシンプルな設定を持つファイル docs/la/mkdocs.yml を作成しました。

INHERIT: ../en/mkdocs.yml

ヒント

その内容を持つファイルを単に手動で作成することもできます。

このコマンドは、メインページ用のダミーファイル docs/la/index.md も作成しました。まずこれを翻訳することから始められます。

このプロセスについては、「既存の言語」に関する以前の指示を続行できます。

docs/la/mkdocs.yml と docs/la/index.md の2つのファイルで最初のプルリクエストを作成できます。🎉

結果をプレビュー

すでに述べたように、./scripts/docs.py を live コマンド（または 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 ドキュメント内のコードブロックでは、コメント (# a comment) を翻訳しますが、それ以外は変更しないでください。

  • "``" (インラインコード) で囲まれたものは変更しないでください。

  • /// で始まる行では、| の後のテキスト部分のみを翻訳してください。残りは変更しないでください。

  • /// warning のような情報ボックスは、たとえば /// warning | Achtung のように翻訳できます。ただし、/// の直後の単語は変更しないでください。これは情報ボックスの色を決定します。

  • 画像、コードファイル、Markdown ドキュメントへのリンクのパスは変更しないでください。

  • ただし、Markdown ドキュメントが翻訳されると、その見出しへのリンクの #hash-parts が変更される場合があります。可能であれば、これらのリンクを更新してください。

    • 翻訳されたドキュメントで、正規表現 #[^# ] を使用してそのようなリンクを検索してください。
    • すでにあなたの言語に翻訳されているすべてのドキュメントで your-translated-document.md を検索してください。例えば、VS Codeには「編集」->「ファイルを検索」オプションがあります。
    • ドキュメントを翻訳する際、未翻訳のドキュメントの見出しへのリンクである #hash-parts を「事前翻訳」しないでください。