Skip to content

Commit 64691f2

Browse files
bnbongbnbong
committed
[DOCS] add domain-starter tutorial & translation completeness & language status in docs
1 parent e548b3d commit 64691f2

8 files changed

Lines changed: 630 additions & 1 deletion

File tree

‎docs/en/contributing/translation-guide.md‎

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,26 @@
22

33
This guide explains how to contribute translations for FastAPI-fastkit documentation.
44

5+
## Source of truth and translation policy
6+
7+
> **English (`en`) is the canonical source of truth** for FastAPI-fastkit
8+
> documentation. Every other locale is a translation target that may
9+
> lag behind English by a release or by individual pages.
10+
>
11+
> If a translated page disagrees with the English page, **trust the
12+
> English page** until the translation catches up. Translations are
13+
> shipped at whatever completeness contributors have reached — partial
14+
> coverage is normal and expected.
15+
16+
The user-facing companion to this policy is the
17+
[Translation Status](../reference/translation-status.md) page, which
18+
lists each locale's actual completeness and how MkDocs renders pages
19+
that haven't been translated yet (TL;DR: they fall back to English).
20+
21+
When you contribute a translation, also update the status page's table
22+
so users can tell what's available without guessing from the language
23+
switcher.
24+
525
## Overview
626

727
FastAPI-fastkit uses an automated translation system powered by AI to translate documentation into multiple languages. The system:
@@ -11,9 +31,16 @@ FastAPI-fastkit uses an automated translation system powered by AI to translate
1131
- Saves translations to language-specific directories
1232
- Creates GitHub Pull Requests for review
1333

34+
The automation produces a starting point; human review is still
35+
required before merging. AI-generated translations should be flagged as
36+
"draft" in their PRs and reviewed by a fluent speaker before landing.
37+
1438
## Supported Languages
1539

16-
Currently supported languages:
40+
These are the locales the docs site currently **builds**. Build target
41+
configuration alone does **not** mean a locale's pages are translated —
42+
see [Translation Status](../reference/translation-status.md) for actual
43+
per-locale completeness.
1744

1845
- 🇰🇷 Korean (ko)
1946
- 🇯🇵 Japanese (ja)

‎docs/en/index.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,12 @@ This project was created to speed up the configuration of the development enviro
2222

2323
This project was inspired by the `SpringBoot initializer` & Python Django's `django-admin` cli operation.
2424

25+
!!! info "Translation status"
26+
English is the source of truth for these docs. Other languages in
27+
the language switcher may be partial or fall back to English page by
28+
page. See [Translation Status](reference/translation-status.md) for
29+
each locale's actual completeness.
30+
2531
## Key Features
2632

2733
- **⚡ Immediate FastAPI project creation** : Super-fast FastAPI workspace & project creation via CLI, inspired by `django-admin` feature of [Python Django](https://github.com/django/django)
@@ -481,6 +487,7 @@ Learn FastAPI development through practical use cases with our pre-built templat
481487

482488
- **[Building a Basic API Server](tutorial/basic-api-server.md)** - Create your first FastAPI server using the `fastapi-default` template
483489
- **[Building an Asynchronous CRUD API](tutorial/async-crud-api.md)** - Develop a high-performance async API with the `fastapi-async-crud` template
490+
- **[Domain-oriented Project (Domain Starter)](tutorial/domain-starter.md)** - Build a medium-sized API with the `fastapi-domain-starter` template, the recommended modern default
484491

485492
### 🗄️ Database & Infrastructure
486493

‎docs/en/reference/translation-status.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Translation status
2+
3+
FastAPI-fastkit ships docs in several languages, but those translations
4+
are **not at parity**. This page is the single source of truth for what
5+
is actually translated where, what gets shown when a page hasn't been
6+
translated, and how to help.
7+
8+
## Source of truth
9+
10+
> **English (`en`) is the source of truth.** All product, CLI, and API
11+
> behaviour described in the docs is authored against the English files
12+
> first. Other locales are translations of those English sources and may
13+
> lag behind a release.
14+
>
15+
> If a translated page disagrees with the English page, **trust the
16+
> English page** until the translation is updated.
17+
18+
The English files live under [`docs/en/`](https://github.com/bnbong/FastAPI-fastkit/tree/main/docs/en).
19+
Every other locale (`docs/ko/`, `docs/ja/`, ...) is a translation
20+
target.
21+
22+
## Per-locale completeness
23+
24+
The numbers below count Markdown pages in each locale's directory tree
25+
relative to the English source. They reflect what's actually present in
26+
the repository — not what shows up in the language switcher (which the
27+
next section explains).
28+
29+
| Locale | Status | Markdown pages | Notes |
30+
|---|---|---:|---|
31+
| 🇬🇧 English (`en`) | ✅ Source of truth | 26 / 26 | Authoritative. |
32+
| 🇰🇷 Korean (`ko`) | 🟡 Partial | 2 / 26 | `index.md`, `changelog.md`. Other pages fall back to English. |
33+
| 🇯🇵 Japanese (`ja`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
34+
| 🇨🇳 Chinese (`zh`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
35+
| 🇪🇸 Spanish (`es`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
36+
| 🇫🇷 French (`fr`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
37+
| 🇩🇪 German (`de`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
38+
39+
*Snapshot verified 2026-05-06.* These counts are maintained by hand;
40+
to recount the current state from the repo root, run:
41+
42+
```console
43+
$ for loc in en ko ja zh es fr de; do
44+
echo "$loc: $(find docs/$loc -name '*.md' 2>/dev/null | wc -l | tr -d ' ')"
45+
done
46+
```
47+
48+
If the recount disagrees with the table, the table is stale — please
49+
update it (or open a PR / issue noting the drift).
50+
51+
Legend:
52+
53+
- ✅ **Source of truth** — the locale we author against.
54+
- 🟡 **Partial** — some pages translated; missing pages fall back.
55+
- 🔴 **Skeleton** — language switcher entry exists, but no translated
56+
pages are checked in yet. The site renders English content under the
57+
translated nav labels.
58+
59+
## How fallback works
60+
61+
The docs site uses
62+
[`mkdocs-static-i18n`](https://github.com/ultrabug/mkdocs-static-i18n)
63+
with `fallback_to_default: true`. This means:
64+
65+
- For each translated locale, MkDocs only writes pages that exist in
66+
that locale's directory.
67+
- For every page **not** present in a locale, the build falls back to
68+
the English version of that page.
69+
- The site-wide language switcher always lists every configured locale
70+
regardless of how many pages each one has, because the build emits a
71+
reachable URL for each (page → fallback to English if needed).
72+
73+
So a 🔴 Skeleton entry in the language switcher is **not** a promise
74+
that the docs are translated — only that the locale build target is
75+
configured. The behaviour is intentional (out-of-tree contributors can
76+
incrementally translate a page at a time without breaking the link
77+
graph), but it makes the language switcher look more complete than the
78+
underlying content actually is.
79+
80+
## How to read the docs site
81+
82+
- **Always default to English** if you want the most accurate, current
83+
information.
84+
- **Use a translated locale** only after checking this page for the
85+
locale's status. If it's 🟡 or 🔴 and you hit a topic that hasn't been
86+
translated, you're reading an English fallback under a translated nav
87+
label.
88+
89+
## How to help
90+
91+
If you'd like to translate a page or fix an existing translation:
92+
93+
1. Read the [Translation Guide](../contributing/translation-guide.md)
94+
for the workflow, tooling, and style conventions.
95+
2. Translate one page at a time — partial translations are welcome and
96+
merged incrementally.
97+
3. Open a PR adding the new file(s) under `docs/<locale>/<same path>`.
98+
Keep filenames identical to the English source so MkDocs picks them
99+
up automatically.
100+
4. Update this page's table to reflect the new completeness count
101+
(use the recount snippet at the top of this page) and bump the
102+
"Snapshot verified" date so reviewers can see when it was last
103+
reconciled.
104+
105+
Bug reports about translated pages going out of sync with the English
106+
source are welcome — please link the English page and the translated
107+
page so we can triage.
108+
109+
## Why we ship 🔴 Skeleton locales at all
110+
111+
Two reasons:
112+
113+
1. **Predictable URL space.** Each locale already has its `/<locale>/`
114+
subtree reachable, so when a translated page lands the link is
115+
stable from day one — including links published in this guide.
116+
2. **Lower contributor friction.** Contributors translating a single
117+
page don't have to also wire a new locale build into MkDocs config —
118+
they just drop the file in.
119+
120+
If a locale stays at 🔴 Skeleton with no contribution activity for an
121+
extended period, we may revisit whether to keep its build target
122+
enabled. That decision is tracked separately and is **not** something
123+
this status page silently changes.

0 commit comments

Comments
 (0)