Skip to content

Commit c14c9f6

Browse files
bnbongbnbong
committed
[DOCS] ko translation - phase 1
1 parent bbce06a commit c14c9f6

9 files changed

Lines changed: 2082 additions & 147 deletions

File tree

‎.pre-commit-config.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ repos:
55
rev: v6.0.0
66
hooks:
77
- id: trailing-whitespace
8+
args: [--markdown-linebreak-ext=md]
89
- id: end-of-file-fixer
910
- id: check-yaml
1011
- id: check-toml

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,14 +29,14 @@ next section explains).
2929
| Locale | Status | Markdown pages | Notes |
3030
|---|---|---:|---|
3131
| 🇬🇧 English (`en`) | ✅ Source of truth | 26 / 26 | Authoritative. |
32-
| 🇰🇷 Korean (`ko`) | 🟡 Partial | 2 / 26 | `index.md`, `changelog.md`. Other pages fall back to English. |
32+
| 🇰🇷 Korean (`ko`) | 🟡 Partial | 8 / 26 | `index.md`, `changelog.md`, `reference/translation-status.md`, plus 5 user-guide pages (`installation`, `quick-start`, `creating-projects`, `using-templates`, `choosing-a-starter`). Other pages fall back to English. |
3333
| 🇯🇵 Japanese (`ja`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
3434
| 🇨🇳 Chinese (`zh`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
3535
| 🇪🇸 Spanish (`es`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
3636
| 🇫🇷 French (`fr`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
3737
| 🇩🇪 German (`de`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
3838

39-
*Snapshot verified 2026-05-06.* These counts are maintained by hand;
39+
*Snapshot verified 2026-05-06; ko row recounted for the current branch.* These counts are maintained by hand;
4040
to recount the current state from the repo root, run:
4141

4242
```console

‎docs/ko/index.md‎

Lines changed: 140 additions & 145 deletions
Large diffs are not rendered by default.

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

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# 번역 현황
2+
3+
FastAPI-fastkit 문서는 여러 언어로 빌드되지만, 그 번역들이 **모두 동일한 수준으로 완료된 것은 아닙니다**. 이 페이지는 어디까지 번역됐는지, 번역되지 않은 페이지가 어떻게 표시되는지, 그리고 번역에 어떻게 기여할 수 있는지에 대한 단일 정보 소스입니다.
4+
5+
## 원본 (Source of truth)
6+
7+
> **영어 (`en`) 가 원본입니다.** 문서에 기술되는 모든 제품·CLI·API 동작은 영어 파일을 기준으로 먼저 작성됩니다. 다른 언어들은 그 영어 원본의 번역본이며, 릴리스 시점보다 뒤처져 있을 수 있습니다.
8+
>
9+
> 번역된 페이지가 영어 페이지와 다르면, 번역이 갱신될 때까지 **영어 페이지를 신뢰하세요**.
10+
11+
영어 문서는 [`docs/en/`](https://github.com/bnbong/FastAPI-fastkit/tree/main/docs/en) 아래에 있습니다. 그 밖의 모든 언어 (`docs/ko/`, `docs/ja/`, ...) 는 번역 대상입니다.
12+
13+
## 언어별 번역 진행 상황
14+
15+
아래 숫자는 각 언어 디렉터리에 실제로 존재하는 마크다운 페이지 수를 영어 원본 대비로 보여줍니다. 언어 선택기에 보이는 언어 목록이 아니라, 리포지토리에 실제 체크인된 파일 수가 기준입니다 (다음 섹션에서 그 차이를 설명합니다).
16+
17+
| 언어 | 상태 | 마크다운 페이지 | 비고 |
18+
|---|---|---:|---|
19+
| 🇬🇧 English (`en`) | ✅ 원본 | 26 / 26 | 권위 있는 원본. |
20+
| 🇰🇷 한국어 (`ko`) | 🟡 부분 번역 | 8 / 26 | `index.md`, `changelog.md`, `reference/translation-status.md`, 그리고 user-guide 5개 페이지. 나머지 페이지는 영어 원문으로 표시됩니다. |
21+
| 🇯🇵 일본어 (`ja`) | 🔴 스켈레톤 | 0 / 26 | 빌드 대상만 설정. 모든 페이지는 영어 원문으로 표시됩니다. |
22+
| 🇨🇳 중국어 (`zh`) | 🔴 스켈레톤 | 0 / 26 | 빌드 대상만 설정. 모든 페이지는 영어 원문으로 표시됩니다. |
23+
| 🇪🇸 스페인어 (`es`) | 🔴 스켈레톤 | 0 / 26 | 빌드 대상만 설정. 모든 페이지는 영어 원문으로 표시됩니다. |
24+
| 🇫🇷 프랑스어 (`fr`) | 🔴 스켈레톤 | 0 / 26 | 빌드 대상만 설정. 모든 페이지는 영어 원문으로 표시됩니다. |
25+
| 🇩🇪 독일어 (`de`) | 🔴 스켈레톤 | 0 / 26 | 빌드 대상만 설정. 모든 페이지는 영어 원문으로 표시됩니다. |
26+
27+
*스냅샷 검증 시점: 2026-05-06; ko 행은 현재 브랜치 기준으로 다시 집계됨.* 이 표는 수동으로 관리됩니다. 리포지토리 루트에서 현재 상태를 다시 세고 싶다면 다음을 실행하세요:
28+
29+
```console
30+
$ for loc in en ko ja zh es fr de; do
31+
echo "$loc: $(find docs/$loc -name '*.md' 2>/dev/null | wc -l | tr -d ' ')"
32+
done
33+
```
34+
35+
다시 센 결과가 표와 다르다면 표가 오래된 것이므로, 직접 갱신하거나 PR / 이슈로 알려주세요.
36+
37+
범례:
38+
39+
- ✅ **원본 (Source of truth)** — 우리가 기준으로 작성하는 언어.
40+
- 🟡 **부분 번역 (Partial)** — 일부 페이지만 번역됨. 번역되지 않은 페이지는 영어 원문으로 대체 표시됩니다.
41+
- 🔴 **스켈레톤 (Skeleton)** — 언어 선택기에는 노출되지만, 번역된 페이지가 아직 체크인되지 않은 상태. 모든 페이지가 번역된 nav 라벨 아래에서 영어 원문으로 표시됩니다.
42+
43+
## 대체 표시 (fallback) 동작 방식
44+
45+
이 문서 사이트는 [`mkdocs-static-i18n`](https://github.com/ultrabug/mkdocs-static-i18n) 을 `fallback_to_default: true` 옵션으로 사용합니다. 의미는 다음과 같습니다:
46+
47+
- 각 번역 언어에 대해 MkDocs 는 해당 언어 디렉터리에 실제로 존재하는 페이지만 빌드해서 출력합니다.
48+
- 어떤 페이지가 그 언어에 **존재하지 않으면**, 빌드는 그 페이지를 영어 버전으로 대체 표시합니다.
49+
- 사이트 전체 언어 선택기는 각 언어가 보유한 페이지 수와 무관하게 항상 설정된 모든 언어를 노출합니다 — 어차피 빌드가 모든 페이지에 도달 가능한 URL 을 만들어 주기 때문입니다 (필요 시 영어로 대체).
50+
51+
따라서 언어 선택기에 보이는 🔴 스켈레톤 항목은 **번역이 완료됐다는 약속이 아니라**, 그 언어의 빌드 대상이 설정되어 있다는 뜻일 뿐입니다. 외부 기여자가 한 번에 한 페이지씩 점진적으로 번역해도 링크 그래프가 깨지지 않도록 의도된 동작이지만, 결과적으로 언어 선택기는 실제 번역 정도보다 더 완성된 것처럼 보일 수 있습니다.
52+
53+
## 문서 사이트를 보는 방법
54+
55+
- **가장 정확하고 최신의 정보**를 보고 싶다면 항상 영어를 기본으로 사용하세요.
56+
- **번역된 언어**는 이 페이지에서 해당 언어의 상태를 먼저 확인한 뒤 사용하세요. 🟡 또는 🔴 상태이고 아직 번역되지 않은 주제에 도달하면, 번역된 nav 라벨 아래에서 영어 원문 대체 페이지를 보고 있는 것입니다.
57+
58+
## 기여 방법
59+
60+
페이지를 새로 번역하거나 기존 번역을 수정하고 싶다면:
61+
62+
1. 작업 흐름·도구·스타일 규약은 [Translation Guide](../contributing/translation-guide.md) 를 참고하세요.
63+
2. 한 번에 한 페이지씩 번역하세요 — 부분 번역도 환영하며 점진적으로 머지됩니다.
64+
3. `docs/<locale>/<same path>` 아래에 새 파일을 추가하는 PR 을 여세요. MkDocs 가 자동 인식하도록 영어 원본과 파일 이름을 동일하게 유지하세요.
65+
4. 새 번역 진행 상황을 반영하도록 이 페이지의 표를 갱신하세요 (페이지 상단의 재집계 스니펫 사용). 그리고 마지막으로 검증한 시점을 알 수 있도록 "스냅샷 검증 시점" 날짜도 함께 갱신하세요.
66+
67+
번역 페이지가 영어 원본과 어긋나 있다는 버그 신고도 환영합니다 — 분류가 쉽도록 영어 페이지와 번역 페이지를 함께 링크해 주세요.
68+
69+
## 🔴 스켈레톤 언어를 그대로 두는 이유
70+
71+
두 가지 이유가 있습니다:
72+
73+
1. **예측 가능한 URL 공간.** 각 언어는 이미 자신의 `/<locale>/` 하위 트리에 도달 가능하므로, 번역된 페이지가 들어오는 시점에 첫날부터 안정적인 링크가 됩니다 — 이 가이드에 게시된 링크들도 마찬가지입니다.
74+
2. **기여자 진입 장벽 낮추기.** 한 페이지를 번역하는 기여자가 새 언어 빌드를 MkDocs 설정에 추가하는 작업을 같이 할 필요 없이, 그냥 파일을 떨어뜨리기만 하면 되도록.
75+
76+
🔴 스켈레톤 상태로 오랫동안 기여 활동이 없는 언어가 있다면, 빌드 대상을 계속 활성화해 둘지 다시 검토할 수 있습니다. 그 결정은 별도로 추적되며, 이 현황 페이지가 조용히 바꾸는 일은 **없습니다**.

‎docs/ko/user-guide/choosing-a-starter.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# 어떤 스타터를 선택해야 할까?
2+
3+
FastAPI-fastkit 은 프로젝트를 시작하는 여러 가지 방법을 제공합니다. 이 페이지는 신규 사용자를 위한 **결정 가이드**입니다: 여기서 경로를 정한 다음, 실제 프로젝트 생성은 [퀵 스타트](quick-start.md) 로 이동해서 진행하세요.
4+
5+
확신이 없다면, 답은 다음과 같습니다:
6+
7+
> **`fastkit init --interactive` 로 시작해서 `domain-starter` 프리셋을 선택하세요.** 모던 API 프로젝트를 위한 권장 기본값입니다.
8+
9+
이 페이지의 나머지 부분은 그 이유와, 다른 선택을 해야 할 경우를 설명합니다.
10+
11+
## TL;DR — 사용자 유형별 선택
12+
13+
| 당신이... | 시작점 |
14+
|---|---|
15+
| FastAPI 가 처음이고 가이드를 따라가며 시작하고 싶다 | `fastkit init --interactive` (preset: **`domain-starter`**) |
16+
| 동작하는 CRUD 데모를 읽고 수정하면서 배우고 싶다 | `fastkit startdemo fastapi-default` |
17+
| 가능한 가장 작은 스캐폴드를 원한다 | `fastkit init --interactive` (preset: **`minimal`**) |
18+
| 빠른 프로토타입 / 단일 파일 스크립트를 작성한다 | `fastkit init --interactive` (preset: **`single-module`**) |
19+
| 실제 데이터베이스가 필요하다 (PostgreSQL + SQLAlchemy + Alembic) | `fastkit startdemo fastapi-psql-orm` |
20+
| 중간 규모 API 를 위한 프로덕션 스타일 도메인 레이아웃을 원한다 | `fastkit init --interactive` (preset: **`domain-starter`**) |
21+
22+
## `startdemo` vs `init --interactive` — 무엇이 다른가?
23+
24+
이 둘이 메인 진입점이며, 서로 다른 용도를 갖습니다.
25+
26+
### `fastkit startdemo <template>`
27+
28+
기본 제공되는 템플릿(`fastapi-default`, `fastapi-async-crud`, `fastapi-psql-orm`, `fastapi-domain-starter`, ...) 중 하나를 기반으로 **완성된, 동작하는 예제** 프로젝트를 디스크에 생성합니다. 템플릿의 소스 코드가 있는 그대로 복사되며, 메타데이터 플레이스홀더(`<project_name>` 등)만 치환됩니다.
29+
30+
- ✅ 실행 가능한 데모까지 가장 빠른 경로.
31+
- ✅ 모든 코드가 실제로 동작하고 읽기 쉬워, 예제로 학습하기에 좋음.
32+
- ❌ 템플릿의 스택과 구조가 고정되어 있어, 생성 시점에 "CORS 만 켜고 인증은 빼는" 식의 조합은 불가능.
33+
34+
```console
35+
$ fastkit list-templates # 사용 가능한 템플릿 표시
36+
$ fastkit startdemo fastapi-default # 그중 하나로 프로젝트 생성
37+
```
38+
39+
### `fastkit init --interactive`
40+
41+
**가이드형 마법사**를 따라 진행합니다: 프로젝트 메타데이터 → 아키텍처 프리셋 → 기능 선택 (데이터베이스, 인증, 테스트, 배포, ...) → 패키지 매니저 → 확인. 생성기는 프리셋별로 적절한 베이스 템플릿을 고르고, 그 위에 선택한 기능을 덧입힙니다.
42+
43+
- ✅ 실제로 원하는 스택을 직접 조립할 수 있음.
44+
- ✅ 아키텍처 프리셋이 프로젝트 레이아웃(단일 파일, 계층형, 도메인 지향, ...)을 결정.
45+
- ❌ `main.py` 보존 프리셋(`classic-layered`, `domain-starter`)은 설정 모듈을 생성해 주지만, 그 모듈을 라우터에 연결하는 작업은 사용자가 직접 해야 함. 프리셋별/기능별 계약은 [아키텍처 프리셋 매트릭스](../reference/preset-feature-matrix.md) 를 참고하세요.
46+
47+
```console
48+
$ fastkit init --interactive
49+
```
50+
51+
## 네 가지 아키텍처 프리셋
52+
53+
이 프리셋들은 `fastkit init --interactive` 의 프로젝트 정보 입력 다음 단계에서 나타납니다. 어떤 프리셋을 고를지 결정할 때 이 섹션을 사용하세요.
54+
55+
### `minimal` — 가장 단순하게 시작, 나중에 키우기
56+
57+
가장 작은 동작 가능한 FastAPI 앱. 빈 스캐폴드 + 선택한 기능 플래그로부터 재생성된 단일 `src/main.py` 입니다. CORS, 레이트 제한, Prometheus 계측은 선택 시 자동으로 `main.py` 에 연결됩니다.
58+
59+
- 👤 **대상**: 프로젝트가 자라남에 따라 직접 구조를 만들고 싶거나, 레이아웃에 대한 선입견 없이 FastAPI 를 탐색하고 싶은 사람.
60+
- 📦 **베이스 템플릿**: `fastapi-empty`.
61+
- 🧠 **멘탈 모델**: "FastAPI 를 import 한 단일 파일을 받고 나머지는 내가 알아서."
62+
63+
### `single-module` — 스크립트형 프로토타입
64+
65+
모든 코드가 한 모듈 안에 존재합니다. `minimal` 과 동일하게 `main.py` 가 재생성되는 오버레이를 사용합니다.
66+
67+
- 👤 **대상**: 글루 스크립트, 작은 webhook, 또는 패키지 경계가 필요 없는 하루짜리 프로토타입.
68+
- 📦 **베이스 템플릿**: `fastapi-single-module`.
69+
- 🧠 **멘탈 모델**: "한 번에 실행하고 한 번에 읽을 수 있는 Python 파일 하나만 있으면 된다."
70+
71+
### `classic-layered` — 계층형 분할 (api / crud / schemas / core)
72+
73+
"Django 풍" 레이아웃 — 코드를 관심사별로 수평 분할합니다: 라우터는 모두 `api/`, CRUD 로직은 모두 `crud/`, pydantic 스키마는 모두 `schemas/`, 설정은 모두 `core/`. 기본 제공된 `main.py` 는 **보존**되며 (이미 CORS 연결이 되어 있음), 생성된 데이터베이스/인증 설정 파일은 `src/core/` 아래에 배치됩니다.
74+
75+
- 👤 **대상**: Django/Rails 풍 레이아웃에 익숙한 팀, 공통 CRUD 배관을 공유하는 작은 엔드포인트가 많은 프로젝트.
76+
- 📦 **베이스 템플릿**: `fastapi-default`.
77+
- 🧠 **멘탈 모델**: "코드를 *무엇인지*에 따라 나눈다."
78+
79+
### `domain-starter` — 도메인 지향 (권장 기본값)
80+
81+
코드를 **비즈니스 개념별**로 수직 분할합니다: 각 도메인은 자신의 router, service, repository, schemas 를 `src/app/domains/<concept>/` 아래에 소유합니다. `/health` 엔드포인트와, 새 개념마다 복사해 이름만 바꾸면 되는 `items` 예제 도메인이 함께 제공됩니다. 기본 제공된 `main.py` (`src/app/` 아래) 는 보존되며, 생성된 설정 파일은 `src/app/core/` 아래에 배치됩니다.
82+
83+
- 👤 **대상**: 여러 개의 별개 개념(users, orders, billing, ...)이 자라날 중간 규모 API. 권장 모던 기본값.
84+
- 📦 **베이스 템플릿**: `fastapi-domain-starter`.
85+
- 🧠 **멘탈 모델**: "코드를 *비즈니스적으로 무엇을 하는지*에 따라 나눈다."
86+
87+
## 비교 매트릭스
88+
89+
한눈에 보는 비교표.
90+
91+
| | `minimal` | `single-module` | `classic-layered` | `domain-starter` |
92+
|---|---|---|---|---|
93+
| 베이스 템플릿 | `fastapi-empty` | `fastapi-single-module` | `fastapi-default` | `fastapi-domain-starter` |
94+
| 프로젝트 진입점 | `src/main.py` | `src/main.py` | `src/main.py` | `src/app/main.py` |
95+
| 라우터 위치 | (직접 추가) | (`main.py` 안) | `src/api/routes/` | `src/app/domains/<concept>/router.py` |
96+
| 도메인별 폴더 | ❌ | ❌ | ❌ | ✅ |
97+
| 내장 `/health` 엔드포인트 | ✅ | ✅ | ❌ | ✅ |
98+
| 기능에서 `main.py` 재생성 | ✅ | ✅ | ❌ | ❌ |
99+
| `main.py` 에 CORS 사전 연결 | 선택 시 추가 | 선택 시 추가 | 예 (env 기반) | 예 (env 기반) |
100+
| pyproject 우선 | 선택 사항 | 선택 사항 | 선택 사항 | ✅ |
101+
| 적합한 경우 | "구조는 내가 키운다" | "한 파일 프로토타입" | "관심사로 분할" | "비즈니스 개념으로 분할" |
102+
103+
기능별 전체 계약 (데이터베이스 / 인증 설정 파일 경로, 어떤 선택이 자동 연결되고 어떤 선택은 수동 연결이 필요한지, 경고가 언제 발생하는지) 은 [아키텍처 프리셋 매트릭스](../reference/preset-feature-matrix.md) 를 참고하세요.
104+
105+
## `startdemo` 템플릿 선택하기
106+
107+
`fastkit startdemo <template>` 는 가이드형 조립이 아닌 **완성된, 실행 가능한 예제**를 원할 때 가장 적합합니다. 대부분의 템플릿은 위 네 가지 프리셋 중 하나에 대략 대응하지만, 추가적인 예제 코드(목 스토어 위의 CRUD 엔드포인트, 커스텀 응답 처리, Docker 도구 등)와 함께 제공됩니다.
108+
109+
| 템플릿 | 가장 가까운 프리셋 | 선택 시점 |
110+
|---|---|---|
111+
| `fastapi-default` | `classic-layered` | 계층형 레이아웃 위의 동작하는 CRUD 데모. 좋은 첫 출발점. |
112+
| `fastapi-empty` | `minimal` | 빈 스캐폴드. `minimal` 이 도달하는 모양과 동일. |
113+
| `fastapi-single-module` | `single-module` | 단일 파일 데모. |
114+
| `fastapi-domain-starter` | `domain-starter` | 권장 모던 기본값. items 도메인 예제 포함. |
115+
| `fastapi-async-crud` | `classic-layered` | `fastapi-default` 의 비동기 버전. |
116+
| `fastapi-custom-response` | `classic-layered` | 커스텀 응답 envelope / 포매팅을 보여줌. |
117+
| `fastapi-dockerized` | `classic-layered` | 기본 레이아웃에 프로덕션 수준의 Dockerfile 추가. |
118+
| `fastapi-psql-orm` | (직접 대응 프리셋 없음) | PostgreSQL + SQLAlchemy + Alembic. 실제 데이터베이스가 필요할 때. |
119+
| `fastapi-mcp` | (직접 대응 프리셋 없음) | Model Context Protocol 통합. |
120+
121+
`fastkit list-templates` 는 한 줄 설명과 함께 현재 템플릿 목록을 보여줍니다.
122+
123+
## 자주 묻는 질문
124+
125+
**Q. 프리셋 / 템플릿을 미리 결정해야 하나요?**
126+
아닙니다 — 생성된 코드는 나중에 손으로 자유롭게 재구성할 수 있습니다. 프리셋은 출발점일 뿐 계약이 아닙니다. 너무 깊게 고민하지 마세요.
127+
128+
**Q. "모던한" 선택은 무엇인가요?**
129+
`domain-starter`. pyproject 우선이며, `/health` 엔드포인트가 내장되어 있고, 잘 운영되는 중간 규모 FastAPI 프로젝트가 자연스럽게 수렴하는 레이아웃을 사용합니다.
130+
131+
**Q. 나중에 `classic-layered` 에서 `domain-starter` 로 바꿀 수 있나요?**
132+
네, 단 마이그레이션 명령은 없으며 수동 리팩터링이 필요합니다. 프로젝트가 자라서 도메인 폴더가 필요해질 거라고 판단되면 처음부터 `domain-starter` 로 시작하세요.
133+
134+
**Q. 그냥 FastAPI 를 학습하고 싶다면요?**
135+
`fastkit startdemo fastapi-default` 로 시작하세요 — 코드를 읽고, 테스트를 실행하고, 엔드포인트 몇 개를 바꿔 보세요. 익숙해지면 `fastkit init --interactive` 의 `domain-starter` 프리셋이 자연스러운 다음 단계입니다.
136+
137+
**Q. 각 프리셋이 정확히 어떤 파일을 생성하는지는 어디서 보나요?**
138+
[아키텍처 프리셋 매트릭스](../reference/preset-feature-matrix.md) 가 그 레퍼런스 페이지입니다.
139+
140+
## 다음 단계
141+
142+
- [퀵 스타트](quick-start.md) — 실제로 첫 프로젝트를 만들어 봅니다.
143+
- [프로젝트 생성](creating-projects.md) — CLI 플래그를 더 깊이 다루는 안내.
144+
- [도메인 지향 프로젝트 튜토리얼](../tutorial/domain-starter.md) — `domain-starter` 를 골랐다면, 생성된 트리 / 번들된 `items` 예제 / 다음 도메인을 추가하는 방법까지 다루는 엔드투엔드 워크스루.
145+
- [아키텍처 프리셋 매트릭스](../reference/preset-feature-matrix.md) — 프리셋별/기능별 전체 계약.

0 commit comments

Comments
 (0)