翻訳ステータス
FastAPI-fastkit のドキュメントは複数の言語でビルドされますが、すべての翻訳が 同じ完成度になっているわけではありません。このページでは、翻訳がどこまで進んでいるか、未翻訳ページがどのように表示されるか、そしてどう貢献できるかをまとめています。
信頼できる情報源 (Source of truth)
英語 (
en) が原典です。 ドキュメントに記載されている製品・CLI・API の挙動は、すべて英語ファイルを基準に最初に記述されます。他の言語はその英語原典を翻訳したものであり、リリース時点より遅れる場合があります。翻訳されたページが英語ページと食い違う場合は、翻訳が更新されるまで 英語ページを信頼してください。
英語ドキュメントは docs/en/ 配下にあります。それ以外のすべてのロケール (docs/ko/, docs/ja/, ...) は翻訳対象です。
リポジトリルートの CHANGELOG.md も、この英語原典に含まれます。ロケール固有の changelog.md ページがある場合でも、翻訳版のリリース履歴を別に維持するのではなく、基準となる英語版 changelog への案内ページとして扱うのが現在の方針です。
ロケールごとの完成度
下記の数値は、英語原典に対して各ロケールのディレクトリツリーに実在する Markdown ページ数を示します。言語切替メニューに表示されるロケール一覧 (次のセクションで説明) ではなく、リポジトリに実際にチェックインされているファイル数を基準にしています。
| ロケール | ステータス | Markdown ページ | 備考 |
|---|---|---|---|
🇬🇧 English (en) |
✅ 原典 (Source of truth) | 26 / 26 | すべての基準になる原文です。 |
🇰🇷 Korean (ko) |
✅ 完了 | 26 / 26 | ロケール側のページはすべてそろっています。Phase 1: トップレベル + コアの user-guide、Phase 2: 残りの user-guide + すべての tutorial、Phase 3: contributing + reference。docs/ko/changelog.md は英語の CHANGELOG.md を意図的に再利用しています。 |
🇯🇵 Japanese (ja) |
✅ 完了 | 26 / 26 | ロケール側のページはすべて存在します。Phase 1: トップレベル + コアの user-guide、Phase 2: 残りの user-guide + すべての tutorial、Phase 3: contributing + reference。docs/ja/changelog.md は英語の CHANGELOG.md を意図的に再利用しています。 |
🇨🇳 Chinese (zh) |
✅ 完了 | 26 / 26 | ロケール側のページはすべて存在します。Phase 1: トップレベル + コアの user-guide、Phase 2: 残りの user-guide + すべての tutorial、Phase 3: contributing + reference。docs/zh/changelog.md は英語の CHANGELOG.md を意図的に再利用しています。 |
🇪🇸 Spanish (es) |
✅ 完了 | 26 / 26 | ロケール側のページはすべて存在します。Phase 1: トップレベル + コアの user-guide、Phase 2: 残りの user-guide + すべての tutorial、Phase 3: contributing + reference。docs/es/changelog.md は英語の CHANGELOG.md を意図的に再利用しています。 |
🇫🇷 French (fr) |
✅ 完了 | 26 / 26 | ロケール側のページはすべて存在します。Phase 1: トップレベル + コアの user-guide、Phase 2: 残りの user-guide + すべての tutorial、Phase 3: contributing + reference。docs/fr/changelog.md は英語の CHANGELOG.md を意図的に再利用しています。 |
🇩🇪 German (de) |
✅ 完了 | 26 / 26 | ロケール側のページはすべて存在します。Phase 1: トップレベル + コアの user-guide、Phase 2: 残りの user-guide + すべての tutorial、Phase 3: contributing + reference。docs/de/changelog.md は英語の CHANGELOG.md を意図的に再利用しています。 |
スナップショット検証日: 2026-06-18。Phase 3 (contributing + reference) を反映した現在のブランチを基準に zh 行を再集計しました。中国語はロケール側のページが 26 件すべて存在し、✅ 完了として追跡されます。 この表は手動で管理されています。リポジトリルートで現在の状態を再カウントしたい場合は、次のコマンドを実行してください:
$ for loc in en ko ja zh es fr de; do
echo "$loc: $(find docs/$loc -name '*.md' 2>/dev/null | wc -l | tr -d ' ')"
done
再カウント結果が表と異なる場合、表が古くなっていますので、直接更新するか PR / Issue で報告してください。
凡例:
- ✅ 原典 (Source of truth) — ドキュメントを記述する際に基準とするロケールです。
- 🟡 部分 — 一部のページのみ翻訳済み。未翻訳のページは英語にフォールバックします。
- 🔴 スケルトン — 言語切替メニューには表示されますが、翻訳済みのページがまだリポジトリに追加されていない状態です。翻訳済みのナビゲーションラベルの下に、英語コンテンツがそのまま表示されます。
フォールバックの仕組み
ドキュメントサイトは mkdocs-static-i18n を fallback_to_default: true オプション付きで使用しています。これは次を意味します:
- 各翻訳ロケールについて、MkDocs はそのロケールディレクトリに実在するページのみをビルドして出力します。
- そのロケールに存在 しない ページは、英語版のページにフォールバックします。
- サイト全体の言語切替メニューは、各ロケールの翻訳量にかかわらず、設定されたすべてのロケールを常に表示します。各ページについて到達可能な URL をビルド時に生成するためで、必要に応じて英語ページがフォールバック表示されます。
つまり、言語切替メニューに表示される 🔴 スケルトンの項目は 翻訳済みであることを保証するものではなく、そのロケールがビルドターゲットとして設定されていることを示すだけです。これは、外部の貢献者が 1 ページずつ翻訳してもリンク構造が壊れないようにするための挙動ですが、その分、言語切替メニューが実際の翻訳進捗より整って見えることがあります。
ドキュメントサイトの読み方
- 最も正確で最新の情報 が必要であれば、常に英語ドキュメントを優先してください。
- 翻訳されたロケール を参照する場合は、まずこのページで該当ロケールのステータスを確認してください。🟡 または 🔴 状態のロケールで未翻訳の話題に飛んだ場合、翻訳されたナビゲーションラベルの下で英語のフォールバックページを見ていることになります。
貢献方法
現在のロールアウトは ロケールごとに 1 つのトラッキング Issue を立て、その中で 複数のフェーズ (phase) に分けて進める形を取っています。たとえば ko は Phase 1 (トップレベル + コアの user-guide)、Phase 2 (残りの user-guide + すべての tutorial)、Phase 3 (contributing + reference) という形で、段階的に反映してきました。各フェーズは独立した PR として提出されるため、レビュアーはロケール全体の完了を待たずに、まとまりのある単位でレビューして承認できます。
貢献したい場合は:
- 作業フロー、ツール、スタイル規約については 翻訳ガイド を参照してください。
- まずロケールごとのトラッキング Issue を確認するか、新しく開いてください。 すでにオープン中のトラッキング Issue があるロケールでは、その中でフェーズ (またはフェーズ内の特定ページ) を担当宣言し、作業の重複を避けてください。トラッキング Issue がないロケールを始める場合は、どのページをどのフェーズに割り当てるかを整理した Issue を新規に開き、Phase 1 から進めてください。
- フェーズごとに 1 PR という形を推奨します。「このページだけ修正」のような小さな PR — 特に英語原典とずれた翻訳の修正 — も引き続き歓迎しますが、ロケールを新規に立ち上げる作業ではフェーズ単位でまとめることで、用語集の決定や相互リンクの表記をその範囲内で一貫させやすくなります。
docs/<locale>/<same path>配下にファイルを追加する PR を提出してください。MkDocs が自動で取り込めるよう、英語原典とファイル名を同じに保ってください。- ロケール別の changelog ページが必要な場合は、翻訳版のリリース履歴を新しく書くのではなく、基準となる英語版
CHANGELOG.mdに案内するラッパーページとして維持してください (プロジェクト方針が明示的に変わらない限り)。 - 新しい翻訳が反映されたら、このページの表も更新してください。ページ上部の再カウントスニペットでカウントを再集計し、最終検証日が分かるよう「スナップショット検証日」も合わせて更新してください。ロケールがまだ部分翻訳の状態であれば、どのフェーズまで進んだかを「備考」列に記入してください。
翻訳ページが英語原典とずれているというバグ報告も歓迎します。トリアージしやすいように、英語ページと翻訳ページの両方をリンクしてください。
🔴 スケルトンのロケールをそのまま維持する理由
理由は 2 つあります:
- 予測しやすい URL 空間。 各ロケールはすでに自身の
/<locale>/サブツリーに到達可能なため、翻訳ページが反映された初日から安定したリンクとして機能します — このガイドに掲載されているリンクも同様です。 - 貢献者の参入障壁を下げる。 1 ページだけ翻訳する貢献者が、新しいロケールビルドを MkDocs 設定に追加する作業まで一緒に行わずに済むよう、ファイルを置くだけで動作するようにしてあります。
🔴 スケルトン状態のまま長期間貢献がないロケールがある場合、ビルドターゲットとして残し続けるかを別途検討する可能性があります。ただしその判断は別の場所で追跡されており、このステータスページが暗黙的に書き換えるものでは ありません。