국제화¶

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

명령 템플릿 번역¶

작동 방식¶

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

언어 설정¶

초기화 중¶

# 중국어 출력
codexspec init my-project --lang zh-CN

# 일본어 출력
codexspec init my-project --lang ja

초기화 후¶

# 현재 구성 보기
codexspec config

# 언어 변경
codexspec config --set-lang zh-CN

# 지원되는 언어 나열
codexspec config --list-langs

구성 파일¶

.codexspec/config.yml:

version: "1.0"

language:
  output: "zh-CN"  # 출력 언어
  templates: "en"  # "en"으로 유지

project:
  ai: "claude"
  created: "2025-02-15"

GitHub Pages 문서 i18n¶

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/              # 포르투갈어 (브라질) 번역

문서 번역¶

/translate-docs 명령을 사용하여 문서를 번역합니다:

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

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

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

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

번역 용어집¶

.codexspec/i18n/glossary.yml의 용어집은 일관된 용어를 보장합니다:

version: "1.0"

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

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

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

품질 검사¶

구조 검사¶

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

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

완전성 검사¶

번역에서 번역되지 않은 영어 콘텐츠 감지:

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

의미 검사¶

AI 기반 의미 일관성 분석:

/check-i18n-semantics --lang zh

CI/CD 통합¶

.github/workflows/docs-i18n.yml 워크플로우가 다음을 자동화합니다:

변경 감지: docs/en/가 변경될 때 트리거
병렬 번역: 7개 대상 언어에 대한 매트릭스 전략
품질 검사: 구조 및 완전성 검증
배포 차단: 검사 실패 시 배포 방지

수동 워크플로우 트리거¶

# GitHub UI 또는 CLI를 통해
gh workflow run docs-i18n.yml -f languages="zh,ja" -f dry_run="false"

이점¶

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