국제화¶

CodexSpec은 LLM 동적 번역을 통해 여러 언어를 지원하며, GitHub Pages를 위한 다국어 문서를 제공합니다.

명령어 템플릿 번역¶

작동 방식¶

단일 영어 템플릿: 모든 명령어 템플릿은 영어로 유지
언어 설정: 프로젝트가 선호하는 출력 언어를 지정
동적 번역: Claude가 런타임에 콘텐츠를 번역

언어 차원¶

CodexSpec은 언어를 개별적으로 설정 가능한 네 가지 차원으로 나눕니다. output이 기반이며, 나머지는 이를 덮어쓰되 설정되지 않았을 때 이 언어(그 다음 en)로 폴백합니다.

차원	`config.yml` 키	init 시 설정	이후 설정	제어 대상	폴백
출력 (기반)	`output`	`--lang`	`config --set-lang`	나머지 세 가지의 기반	`en`
상호작용	`interaction`	`--interaction-lang`	`config --set-interaction-lang`	LLM 대화 + CLI 출력	output → `en`
문서	`document`	`--document-lang`	`config --set-document-lang`	생성된 spec/plan/tasks	output → `en`
커밋	`commit`	`--commit-lang`	`config --set-commit-lang`	git 커밋 메시지	output → `en`
템플릿	`templates`	—	—	명령어 템플릿 소스 (항상 `en`)	—

언어 설정¶

초기화 중¶

# 한국어 출력(출력 기반을 설정)
codexspec init my-project --lang ko-KR

# 완전한 비대화형: ko-KR 기반, 영어 커밋 메시지
codexspec init my-project --lang ko-KR --commit-lang en

# 모든 차원을 명시적으로 설정(스크립트용, 프롬프트 없음)
codexspec init my-project \
  --interaction-lang ko-KR --document-lang en --commit-lang en

TTY 환경에서 --lang(그리고 세 차원 플래그 모두) 없이 처음 init을 실행하면 기준 언어를 묻습니다. non-TTY(CI/스크립트)에서는 en이 기본값입니다. init을 다시 실행할 때 지정하지 않은 언어 키는 보존됩니다.

초기화 이후¶

# 현재 설정 보기
codexspec config

# 단일 차원 변경
codexspec config --set-lang ko-KR
codexspec config --set-interaction-lang ko-KR
codexspec config --set-document-lang en
codexspec config --set-commit-lang en

# workflow.auto_next 토글(플래그만 쓰면 토글, 또는 on/off 명시)
codexspec config --auto-next

# 지원 언어 목록
codexspec config --list-langs

설정 파일¶

.codexspec/config.yml:

version: "1.0"

language:
  output: "ko-KR"        # 기반 언어; 아래 세 가지는 여기로, 그 다음 "en"으로 폴백
  interaction: "ko-KR"   # LLM 대화 + codexspec CLI 출력 (선택 → 기본값은 output)
  document: "en"         # 생성된 requirements/spec/plan/tasks (선택 → 기본값은 output)
  commit: "en"           # git 커밋 메시지 (선택 → 기본값은 output)
  templates: "en"        # "en"으로 유지

project:
  ai: "claude"          # claude | codex | both — 이 프로젝트가 대상으로 하는 AI 어시스턴트
  created: "2025-02-15"

GitHub Pages 문서 i18n¶

문서 사이트 언어와 CLI/런타임 언어는 섞지 마세요.

문서 사이트(이 섹션): 8개 언어. MkDocs로 빌드되는 GitHub Pages 사이트는 아래 나열된 8개 로케일(en, zh, ja, ko, es, fr, de, pt-BR)만 제공합니다. 이는 docs/{lang}/ 디렉토리 구조와 mkdocs-i18n 플러그인이 정하는 고정된 집합입니다.

CLI / 런타임(위 섹션): 13개 언어. .codexspec/config.yml에서 설정하는 language.* 차원은 13개의 지원 코드(en, zh-CN, zh-TW, ja, ko, es, fr, de, pt-BR, ru, it, ar, hi)를 받고, LLM이 즉석에서 번역합니다. 공식 목록은 프로젝트 README의 "Supported Languages" 표를 참조하세요.

두 집합은 겹치지만 같지는 않습니다. 문서 사이트에는 zh-TW/ru/it/ar/hi 로케일이 없으며, CLI는 MkDocs가 폴더 이름으로 쓰는 zh/de/... 같은 단축 코드를 사용하지 않습니다.

CodexSpec의 문서 사이트는 mkdocs-i18n 플러그인과 함께 MkDocs를 사용해 8개 언어를 지원합니다.

지원 언어¶

코드	언어
`en`	English (기본값)
`zh`	中文简体
`ja`	日本語
`ko`	한국어
`es`	Español
`fr`	Français
`de`	Deutsch
`pt-BR`	Português (Brasil)

디렉토리 구조¶

docs/
├── en/                 # English (소스)
│   ├── index.md
│   ├── user-guide/
│   └── ...
├── zh/                 # 중국어 번역
├── ja/                 # 일본어 번역
├── ko/                 # 한국어 번역
├── es/                 # 스페인어 번역
├── fr/                 # 프랑스어 번역
├── de/                 # 독일어 번역
└── pt-BR/              # 포르투갈어(브라질) 번역

문서 번역 (메인테이너 전용)¶

참고: /codexspec:translate-docs 와 /codexspec:check-i18n-semantics 명령은 CodexSpec 메인테이너 전용 도구입니다. 이 명령들은 이 리포지토리의 MkDocs i18n 구조(docs/{lang}/)와 리포지토리 내부 전용 용어집 docs/i18n/glossary.yml에 강하게 결합되어 있습니다. codexspec init을 통해 사용자 프로젝트에 배포되지 않으며, 사용자용 슬래시 명령어로도 제공되지 않습니다.

CodexSpec 자체를 개발 중이라면 이 명령들은 .claude/commands/codexspec/에 위치하며, 다른 슬래시 명령어와 같은 방식으로 호출할 수 있습니다. 자기 프로젝트의 문서를 번역하려는 일반 사용자는 Claude를 직접 사용해 선호하는 워크플로우로 번역하면 됩니다.

CodexSpec 메인테이너는 /codexspec:translate-docs 명령으로 문서를 번역할 수 있습니다:

# 중국어로 번역
/codexspec:translate-docs --lang zh

# 특정 파일을 일본어로 번역
/codexspec:translate-docs user-guide/installation.md --lang ja

# 증분 번역(변경된 파일만)
/codexspec:translate-docs --lang ko --incremental

# 미리보기 모드(파일 변경 없음)
/codexspec:translate-docs --lang es --dry-run

번역 용어집¶

docs/i18n/glossary.yml(리포지토리 내부 전용)의 용어집은 CodexSpec 자체 문서를 번역할 때 용어 일관성을 보장합니다:

version: "1.0"

# 영어로 유지할 용어
keep_english:
  - CLI
  - API
  - YAML
  - JSON

# 일반 용어 번역
translations:
  zh:
    specification: "规格说明"
    constitution: "宪法"
    task: "任务"

# 특수한 경우를 위한 스마트 규칙
rules:
  - pattern: '\b(CLI|API)\b'
    action: keep

번역 방법론¶

번역은 영어를 낱말 그대로 옮기는 것이 아니라, 각 언어에서 자연스럽게 읽히도록 하는 것을 목표로 합니다:

의미 우선. 각 단락이 전달하는 바를 먼저 파악한 뒤, 대상 언어만의 표현과 문장 구조로 다시 풀어냅니다.
영어가 더 명확할 때는 영어로 유지. 적절한 모국어 대응이 없거나 영어가 더 익숙한 기술 용어는 억지로 번역하지 않고 영어 그대로 둡니다. 예컨대 "AI coding agent"는 어색한 직역이 아니라 "AI 코딩 어시스턴트" 같은 자연스러운 모국어 표현이 됩니다.
원어민다운 자연스러움. 처음부터 그 언어로 쓰인 것처럼 읽히는 글을 목표로 합니다.

품질 검사¶

구조 검사¶

모든 언어 디렉토리가 동일한 파일 구조를 갖추고 있는지 확인:

./scripts/bash/check-i18n-structure.sh

완전성 검사¶

번역에서 번역되지 않은 영어 콘텐츠를 찾아냅니다:

./scripts/bash/check-i18n-completeness.sh

의미 검사 (메인테이너 전용)¶

AI 기반 의미 일관성 분석은 내부 명령을 통해 CodexSpec 메인테이너만 사용할 수 있습니다(위 메인테이너 전용 안내 참조):

/codexspec:check-i18n-semantics --lang zh

CI/CD 통합¶

.github/workflows/docs-i18n.yml 워크플로우는 빌드 게이트 전용입니다. docs/** / mkdocs.yml이 변경될 때마다(main으로의 푸시 및 풀 리퀘스트 시) 모든 언어 버전에 대해 mkdocs build --strict를 실행해 빌드 오류, 끊어진 링크, 잘못된 형식의 콘텐츠를 잡아냅니다. 어떤 번역도 수행하지 않습니다.

번역은 /codexspec:translate-docs(위 참조)를 통해 수동으로 생성·커밋되며, 영어 소스와 모든 번역이 하나의 검토된 원자적 커밋으로 들어갑니다. CI 자동 번역은 의도적으로 제거했습니다. 과거의 잡은 실제로 실행된 적이 없고(잘못된 if가 이를 건너뛰었음), 상시 API 키가 필요했으며, 검토되지 않은 번역을 main에 직접 커밋했을 것입니다.

이점¶

번역 유지보수 부담 제로: 여러 템플릿 버전을 유지할 필요 없음
항상 최신: 템플릿 업데이트가 모든 언어에 즉시 혜택
컨텍스트 인식: 기술 용어는 적절할 때 영어로 유지
자동화된 품질: CI가 번역 일관성을 보장
AI 지원: Claude가 컨텍스트를 반영한 번역을 제공