국제화¶
설정은 .codexspec/config.yml에 저장합니다. 템플릿은 영어로 유지하지만,
에이전트는 설정된 언어로 대화와 산출물을 작성합니다.
표준 언어 코드는 13개입니다: en, zh-CN, zh-TW, ja, ko, es, fr, de, pt, ru, it, ar, hi.
포르투갈어 CLI 코드는 pt이며, 현지화된 문서와 번역 카탈로그는 pt-BR을 사용합니다.
언어별 설정¶
| 구분 | 설정 키 | 초기화 시 | 나중에 설정 | 적용 대상 |
|---|---|---|---|---|
| 출력·기본 언어 | language.output |
--lang |
config --set-lang |
다른 언어 설정이 없을 때 사용할 기본 언어 |
| 대화 | language.interaction |
--interaction-lang |
config --set-interaction-lang |
대화와 CLI 출력 |
| 문서 | language.document |
--document-lang |
config --set-document-lang |
요구사항, 명세서, 설계, 계획, 태스크 |
| 커밋 | language.commit |
--commit-lang |
config --set-commit-lang |
커밋 메시지와 Git 워크플로우에서 생성하는 텍스트 |
각 언어 설정은 독립적으로 language.output, 그다음 en을 기본값으로 사용합니다.
language.templates는 en으로 유지합니다.
codexspec init my-project --ai both \
--interaction-lang zh-CN --document-lang en --commit-lang en
codexspec config
codexspec config --set-document-lang en
codexspec config --list-langs
첫 TTY 초기화에서는 --lang 또는 세 가지 개별 언어 옵션을 모두 지정하지 않으면 기본 언어를 선택하라는 메시지가 표시됩니다.
--force는 다른 초기화 확인을 자동 승인하지만 이 언어 선택은 생략하지 않습니다.
비 TTY 초기화에서는 기본적으로 영어를 사용합니다. 재초기화할 때도 명시적으로 설정하지 않은 언어 키는 유지합니다.
다국어 문서¶
사이트와 루트 README는 8개 언어로 관리합니다. 런타임 언어 설정은 에이전트 출력을 제어하며 저장소 문서를 자동으로 번역하지는 않습니다. docs/en/의 영어 페이지가 번역 원본입니다. 영어는 사이트 루트에서, 나머지 언어는 각 로케일 경로에서 제공됩니다.
English · 中文 · 日本語 · 한국어 · Español · Français · Deutsch · Português
번역 유지보수¶
두 어시스턴트 모두에서 저장소 전용 번역 및 의미 검토 진입점을 사용할 수 있습니다. 이들은 유지보수 도구이며 codexspec init이 설치하는 공개 명령이 아닙니다. 공통 규칙은 internal/references/doc-translation.md, 용어집은 docs/i18n/glossary.yml에 있습니다.
$codexspec:translate-docs --source docs/en/getting-started/installation.md --lang all
$codexspec:check-i18n-semantics --source docs/en/getting-started/installation.md --lang all --strict
/codexspec:translate-docs --source docs/en/getting-started/installation.md --lang all
/codexspec:check-i18n-semantics --source docs/en/getting-started/installation.md --lang all --strict
변경된 영어 페이지를 선택하고 원문 전체를 읽은 뒤 모든 조건, 기본값, 제외 범위, 예제, 기술 토큰을 보존합니다. 대상 언어의 기술 문서로 자연스럽게 작성해야 하며 영어 문장 구조를 따를 필요는 없습니다. 의미의 충실성과 표현의 자연스러움을 따로 검토하고, 번역된 제목 링크는 실제 대상 페이지를 기준으로 확인합니다.
목록에는 정확한 원본·대상 파일 쌍과 원본 해시가 기록됩니다. 기계적 검사는 구조, 코드 예제, 토큰, 링크 차이를 찾지만 의미가 같다는 사실까지 입증하지는 못합니다. 선택한 모든 언어를 검토하고 누락이나 부자연스러운 표현을 고친 뒤 번역을 승인합니다. 드라이런은 선택 범위만 미리 보여 줍니다.
빌드 및 그림 확인¶
문서 CI는 MkDocs의 엄격한 검증으로 빌드합니다. 번역과 의미 검토는 별도로 명시적으로 수행해야 하는 유지보수 작업이며, 빌드 성공만으로 번역 품질을 보장할 수는 없습니다. 영향을 받는 페이지, 언어 탐색, 좁은 화면의 배치, 두 테마를 미리 확인하세요.
uv sync --extra dev --extra docs
uv run python -B -m internal.doc_translation inventory --lang all
uv run python -B -m internal.doc_translation verify --lang all
uv run mkdocs build --strict
uv run mkdocs serve
사이트는 hooks/workflow_assets.py를 통해 assets/workflow/의 README 워크플로 PNG를 재사용하며 문서 디렉터리에 원본 이미지를 별도로 보관하지 않습니다. 테마별 이미지 링크는 사이트의 라이트·다크 모드 전환을 따릅니다. 그림을 갱신할 때는 공통 유지보수 안내에 따라 원본 그림, 번역 카탈로그, 레이아웃과 모든 생성 리소스를 함께 갱신합니다.