콘텐츠로 이동

번역 현황

FastAPI-fastkit 문서는 여러 언어로 빌드되지만, 모든 번역이 똑같은 수준으로 완성된 것은 아닙니다. 이 페이지는 어디까지 번역되었는지, 번역되지 않은 페이지가 어떻게 보이는지, 그리고 번역에 어떻게 기여할 수 있는지를 한곳에서 안내합니다.

원본 (Source of truth)

영어 (en)가 원본입니다. 문서에 적힌 모든 제품·CLI·API 동작은 영어 파일을 기준으로 먼저 작성됩니다. 다른 언어는 그 영어 원본을 번역한 것이며, 릴리스 시점보다 뒤처질 수 있습니다.

번역된 페이지가 영어 페이지와 다르면, 번역이 갱신될 때까지 영어 페이지를 신뢰하세요.

영어 문서는 docs/en/ 아래에 있습니다. 그 밖의 모든 언어(docs/ko/, docs/ja/, ...)는 번역 대상입니다.

리포지토리 루트의 CHANGELOG.md 역시 이 영어 원본 범위에 포함됩니다. 언어별 changelog.md 페이지가 있더라도, 별도의 번역본 릴리스 이력을 유지하는 대신 영문 기준 changelog를 래핑하거나 진입점으로 제공하는 방식이 현재 정책입니다.

언어별 번역 진행 상황

아래 숫자는 각 언어 디렉터리에 실제로 존재하는 마크다운 페이지 수를 영어 원본 대비로 보여줍니다. 언어 선택기에 보이는 언어 목록이 아니라, 리포지토리에 실제 체크인된 파일 수가 기준입니다 (다음 섹션에서 그 차이를 설명합니다).

언어 상태 마크다운 페이지 비고
🇬🇧 English (en) ✅ 원본 26 / 26 기준이 되는 원문입니다.
🇰🇷 한국어 (ko) ✅ 완료 26 / 26 언어별 페이지는 모두 존재합니다. Phase 1: 최상위 + 핵심 user-guide, Phase 2: 나머지 user-guide + 모든 tutorial, Phase 3: contributing + reference. docs/ko/changelog.md 는 영문 기준 CHANGELOG.md 를 그대로 사용합니다.
🇯🇵 일본어 (ja) ✅ 완료 26 / 26 언어별 페이지는 모두 존재합니다. Phase 1: 최상위 + 핵심 user-guide, Phase 2: 나머지 user-guide + 모든 tutorial, Phase 3: contributing + reference. docs/ja/changelog.md 는 영문 기준 CHANGELOG.md 를 그대로 사용합니다.
🇨🇳 중국어 (zh) ✅ 완료 26 / 26 언어별 페이지는 모두 존재합니다. Phase 1: 최상위 + 핵심 user-guide, Phase 2: 나머지 user-guide + 모든 tutorial, Phase 3: contributing + reference. docs/zh/changelog.md 는 영문 기준 CHANGELOG.md 를 그대로 사용합니다.
🇪🇸 스페인어 (es) ✅ 완료 26 / 26 언어별 페이지는 모두 존재합니다. Phase 1: 최상위 + 핵심 user-guide, Phase 2: 나머지 user-guide + 모든 tutorial, Phase 3: contributing + reference. docs/es/changelog.md 는 영문 기준 CHANGELOG.md 를 그대로 사용합니다.
🇫🇷 프랑스어 (fr) ✅ 완료 26 / 26 모든 로케일 페이지가 존재합니다. Phase 1: 최상위 + 핵심 user-guide; Phase 2: 나머지 user-guide + 모든 tutorial; Phase 3: contributing + reference. docs/fr/changelog.md 는 영문 기준 CHANGELOG.md 를 그대로 재사용합니다.
🇩🇪 독일어 (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 / 이슈로 알려 주세요.

범례:

  • ✅ 원본 (Source of truth) — 문서를 작성할 때 기준으로 삼는 언어입니다.
  • 🟡 부분 번역 (Partial) — 일부 페이지만 번역된 상태입니다. 번역되지 않은 페이지는 영어 원문이 대신 표시됩니다.
  • 🔴 기본 구조만 있음 (Skeleton) — 언어 선택기에는 보이지만, 번역된 페이지가 아직 체크인되지 않은 상태입니다. 모든 페이지가 번역된 탐색 라벨 아래에서 영어 원문으로 표시됩니다.

영어 대체 표시(fallback) 동작 방식

이 문서 사이트는 mkdocs-static-i18n 을 fallback_to_default: true 옵션으로 사용합니다. 의미는 다음과 같습니다:

  • 각 번역 언어에 대해 MkDocs는 해당 언어 디렉터리에 실제로 존재하는 페이지만 빌드해 출력합니다.
  • 어떤 페이지가 그 언어에 존재하지 않으면, 그 페이지는 영어 버전이 대신 표시됩니다.
  • 사이트 전체 언어 선택기는 각 언어의 번역 분량과 관계없이 설정된 모든 언어를 항상 보여 줍니다. 빌드가 모든 페이지에 접근 가능한 URL을 만들어 주기 때문입니다. 필요하면 영어 페이지가 대신 노출됩니다.

따라서 언어 선택기에 보이는 🔴 기본 구조만 있음 항목은 번역이 완료되었다는 뜻이 아니라, 그 언어가 빌드 대상으로 설정되어 있다는 뜻일 뿐입니다. 외부 기여자가 페이지를 조금씩 번역해도 링크 구조가 깨지지 않도록 의도된 동작이지만, 그만큼 언어 선택기가 실제 번역 진행 상황보다 더 완성돼 보일 수 있습니다.

문서 사이트를 보는 방법

  • 가장 정확하고 최신의 정보가 필요하다면 항상 영어 문서를 우선으로 보세요.
  • 번역된 언어를 볼 때는 이 페이지에서 해당 언어의 상태를 먼저 확인하세요. 🟡 또는 🔴 상태인 언어에서 아직 번역되지 않은 주제로 이동하면, 번역된 탐색 라벨 아래에서 영어 원문 페이지를 보고 있는 것입니다.

기여 방법

현재는 언어별로 추적 이슈를 하나 두고, 그 안에서 여러 단계(phase)로 나누어 진행하는 방식을 사용합니다. 예를 들어 ko는 Phase 1(최상위 페이지 + 핵심 user-guide), Phase 2(나머지 user-guide + 모든 tutorial), Phase 3(contributing + reference)로 나누어 작업합니다. 각 단계는 독립된 PR로 머지되므로, 리뷰어는 언어 전체가 끝날 때까지 기다리지 않고 한 묶음씩 검토하고 승인할 수 있습니다.

기여하고 싶다면:

  1. 작업 흐름·도구·스타일 규약은 번역 가이드를 참고하세요.
  2. 언어별 추적 이슈를 먼저 확인하거나 새로 여세요. 이미 추적 이슈가 있는 언어라면 그 안에서 한 단계(또는 단계 안의 특정 페이지)를 맡아 작업이 겹치지 않도록 해 주세요. 추적 이슈가 없는 언어를 시작한다면, 어떤 페이지가 어느 단계에 속하는지 정리한 추적 이슈를 새로 열고 Phase 1부터 시작하세요.
  3. 단계별로 PR 하나를 올리는 방식을 권장합니다. "이 한 페이지만 고쳐 주세요"처럼 작은 PR, 특히 영어 원문과 어긋난 번역을 바로잡는 PR도 여전히 환영합니다. 다만 새 언어를 처음 도입하는 작업이라면, 단계 단위로 묶는 편이 용어집 결정과 교차 링크 표기를 한 묶음 안에서 일관되게 유지하기 쉽습니다.
  4. docs/<locale>/<same path> 아래에 새 파일을 추가하는 PR을 여세요. MkDocs가 자동으로 인식할 수 있도록 영어 원본과 파일 이름을 동일하게 유지하세요.
  5. 언어별 changelog 페이지가 필요하다면, 번역본 release history를 새로 쓰기보다는 영문 기준 CHANGELOG.md 로 연결되는 래퍼 페이지로 유지하세요.
  6. 새 번역이 반영되면 이 페이지의 표도 함께 갱신하세요. 페이지 상단의 재집계 스니펫으로 개수를 다시 세고, 마지막 검증 시점을 알 수 있도록 "스냅샷 검증 시점" 날짜도 함께 업데이트하세요. 언어가 아직 부분 번역 상태라면 어느 단계까지 진행되었는지 비고(Notes) 칸에 적어 주세요.

번역 페이지가 영어 원본과 어긋나 있다는 버그 신고도 환영합니다 — 분류가 쉽도록 영어 페이지와 번역 페이지를 함께 링크해 주세요.

🔴 기본 구조만 있는 언어를 그대로 두는 이유

두 가지 이유가 있습니다:

  1. 예측 가능한 URL 공간. 각 언어는 이미 자신의 /<locale>/ 하위 트리에 도달 가능하므로, 번역된 페이지가 들어오는 시점에 첫날부터 안정적인 링크가 됩니다 — 이 가이드에 게시된 링크들도 마찬가지입니다.
  2. 기여자 진입 장벽 낮추기. 한 페이지를 번역하는 기여자가 새 언어 빌드를 MkDocs 설정에 추가하는 작업을 같이 할 필요 없이, 그냥 파일을 떨어뜨리기만 하면 되도록.

🔴 기본 구조만 있는 상태로 오랫동안 기여가 없는 언어가 있다면, 빌드 대상을 계속 유지할지 다시 검토할 수 있습니다. 다만 그 결정은 별도로 추적되며, 이 현황 페이지에서 임의로 바꾸지는 않습니다.