Table of Contents

국제화 (i18n) 가이드

Spec Kit은 명령, 템플릿 및 CLI 메시지에 대한 여러 언어를 지원합니다.

지원되는 언어

  • 영어 (en): 기본 언어, 항상 포함
  • 한국어 (ko): 전체 번역 사용 가능

아키텍처

Spec Kit은 하이브리드 i18n 접근 방식을 사용합니다:

  1. **기본 언어 (영어)**는 메인 패키지와 함께 번들로 제공됩니다
  2. 추가 언어는 별도로 설치할 수 있습니다 (곧 제공 예정)
  3. 언어 감지는 시스템 로케일 또는 환경 변수를 기반으로 자동으로 수행됩니다

디렉토리 구조

spec-mix/
├── locales/
│   ├── config.json                # 언어 구성
│   ├── en/                        # 영어 (기본값)
│   │   ├── strings.json           # CLI 메시지
│   │   ├── commands/              # 명령 지침
│   │   │   ├── specify.md
│   │   │   ├── plan.md
│   │   │   └── ...
│   │   └── templates/             # 문서 템플릿
│   │       ├── spec-template.md
│   │       ├── plan-template.md
│   │       └── ...
│   └── ko/                        # 한국어
│       ├── strings.json
│       ├── commands/
│       └── templates/

다양한 언어로 Spec Kit 사용

자동 언어 감지

Spec Kit은 다음을 기반으로 언어를 자동으로 감지합니다:

  1. SPECIFY_LANG 환경 변수 (최우선)
  2. 시스템 로케일 (LANG, LC_ALL)
  3. 기본 언어 (영어) 감지되지 않은 경우

수동으로 언어 설정

옵션 1: 환경 변수 (권장)

셸 프로필(~/.bashrc, ~/.zshrc 등)에 추가:

export SPECIFY_LANG=ko

옵션 2: 세션별

SPECIFY_LANG=ko spec-mix init my-project

옵션 3: CLI 사용

# 사용 가능한 언어 목록
spec-mix lang list

# 현재 언어 표시
spec-mix lang current

# 기본 언어 설정 (환경 변수 권장 사항 업데이트)
spec-mix lang set ko

언어 관리 명령

spec-mix lang list

사용 가능하고 설치된 모든 언어 목록:

$ spec-mix lang list

Available Languages
┌──────────┬────────────────────────┬─────────────────────────┐
│ Code     │ Name                   │ Status                  │
├──────────┼────────────────────────┼─────────────────────────┤
│ en       │ English (English)      │ Installed, Default      │
│ ko       │ 한국어 (Korean)         │ Installed               │
└──────────┴────────────────────────┴─────────────────────────┘

Current language: English (English)

spec-mix lang current

현재 활성 언어 표시:

$ spec-mix lang current

Current language: 한국어 (Korean) (ko)

To change language:
  spec-mix lang set <code>

To list available languages:
  spec-mix lang list

spec-mix lang set <code>

기본 언어를 설정하고 영구적으로 만드는 지침을 제공합니다:

$ spec-mix lang set ko

Default language set to: 한국어 (Korean)

To make this permanent, add to your shell profile:
  export SPECIFY_LANG=ko

spec-mix lang install <code> (곧 제공 예정)

GitHub 릴리스에서 언어 팩 설치:

$ spec-mix lang install ko

Installing language pack: ko
Downloading from GitHub releases...

[Feature Coming Soon]
Language pack installation from GitHub releases is not yet implemented.
For now, language packs are bundled with the main package.

언어 선택 작동 방식

템플릿 및 명령 로딩

/spec-mix.specify와 같은 명령을 실행하면:

  1. Spec Kit이 현재 언어 설정을 확인합니다
  2. locales/{lang}/commands/specify.md에서 적절한 명령 파일을 로드합니다
  3. locales/{lang}/templates/의 템플릿을 사용합니다
  4. 번역이 누락된 경우 영어로 대체합니다

CLI 메시지

모든 CLI 메시지(오류, 성공 메시지, 프롬프트)는 strings.json 파일을 사용하여 번역됩니다:

# Python 코드에서
from specmix.i18n import t

# 메시지 번역
message = t('cli.init.project_ready')  # English: "Project ready."
                                       # Korean: "프로젝트가 준비되었습니다."

# 포맷 인수 사용
message = t('cli.init.error_invalid_ai', ai='claude', options='claude, copilot')

새 언어 추가

1. 언어 디렉토리 생성

mkdir -p locales/{lang_code}/{commands,templates}

2. 구성에 추가

locales/config.json 편집:

{
  "supported_locales": [
    {
      "code": "en",
      "name": "English",
      "native_name": "English",
      "is_default": true
    },
    {
      "code": "ja",
      "name": "Japanese",
      "native_name": "日本語",
      "is_default": false
    }
  ]
}

3. 문자열 번역

모든 CLI 메시지가 번역된 locales/{lang_code}/strings.json 생성.

참조로 locales/en/strings.json 사용.

4. 명령 번역

locales/en/commands/에서 명령 파일을 복사하고 번역:

  • specify.md - 기능 사양 워크플로
  • constitution.md - 프로젝트 헌법 워크플로
  • plan.md - 구현 계획 워크플로
  • tasks.md - 작업 분해 워크플로
  • implement.md - 구현 실행 워크플로
  • clarify.md - 명확화 워크플로
  • analyze.md - 분석 워크플로
  • checklist.md - 체크리스트 생성 워크플로

5. 템플릿 번역

locales/en/templates/에서 템플릿 파일을 복사하고 번역:

  • spec-template.md - 기능 사양 템플릿
  • plan-template.md - 구현 계획 템플릿
  • tasks-template.md - 작업 분해 템플릿
  • checklist-template.md - 품질 체크리스트 템플릿

6. 번역 테스트

SPECIFY_LANG={lang_code} spec-mix init test-project

대체 동작

번역이 누락된 경우:

  1. 문자열을 찾을 수 없음: [MISSING: key.path] 표시
  2. 명령 파일을 찾을 수 없음: 영어로 대체
  3. 템플릿을 찾을 수 없음: 영어로 대체

이렇게 하면 부분 번역이 있어도 Spec Kit이 항상 작동합니다.

기술 구현

LocaleManager 클래스

LocaleManager 클래스(src/specmix/i18n.py)는 다음을 처리합니다:

  • 로케일 감지
  • 대체가 있는 문자열 로딩
  • 번역의 깊은 병합
  • 템플릿 경로 해결

주요 함수

from specmix.i18n import get_locale_manager, t, init_i18n

# i18n 초기화 (CLI에 의해 자동으로 수행됨)
init_i18n()

# 현재 로케일 관리자 가져오기
lm = get_locale_manager()

# 문자열 번역
message = t('cli.init.project_ready')

# 현재 로케일 확인
current_lang = lm.current_locale  # 예: "ko"

# 사용 가능한 로케일 가져오기
installed = lm.get_installed_locales()  # ['en', 'ko']
supported = lm.get_supported_locales()  # 전체 구성 목록

모범 사례

사용자용

  1. 언어를 한 번 설정: SPECIFY_LANG 환경 변수 사용
  2. 사용 가능한 언어 확인: spec-mix lang list를 실행하여 사용 가능한 항목 확인
  3. 번역 문제 보고: 번역이 잘못된 경우 GitHub 이슈 열기

기여자용

  1. 번역 일관성 유지: 전체에서 동일한 용어 사용
  2. 포맷팅 보존: 마크다운 포맷팅, 플레이스홀더 등 유지
  3. 철저히 테스트: 번역된 언어로 전체 워크플로 실행
  4. 모든 파일 업데이트: 새 기능을 추가할 때 모든 언어 파일 업데이트

문제 해결

언어가 감지되지 않음

# 현재 언어 확인
spec-mix lang current

# 명시적으로 설정
export SPECIFY_LANG=ko
spec-mix lang current

번역된 인터페이스에 부분 영어

일부 문자열이 아직 번역되지 않았음을 의미합니다. 다음을 확인하세요:

  1. locales/{lang}/strings.json CLI 메시지 누락
  2. locales/{lang}/commands/ 명령 번역 누락
  3. locales/{lang}/templates/ 템플릿 번역 누락

언어 팩을 설치할 수 없음

GitHub 릴리스의 언어 팩 설치는 향후 업데이트에서 제공될 예정입니다. 현재 지원되는 모든 언어는 메인 패키지와 함께 번들로 제공됩니다.

향후 개선사항

  • [ ] GitHub 릴리스에서 언어 팩 다운로드
  • [ ] 커뮤니티 기여 번역
  • [ ] 번역 완성도 확인 도구
  • [ ] 재시작 없이 앱 내 언어 전환
  • [ ] 지역 변형 (en-US, en-GB, zh-CN, zh-TW)
Edit this page