11# i18n Guide — Response Language Rules
22
3- Agent/workflow 응답 언어 처리의 단일 진실 원천(SSOT) .
3+ Single source of truth for agent/workflow response language handling .
44
55## Language Resolution
66
7- 응답 언어는 다음 우선순위로 결정한다 :
7+ Response language is determined by the following priority :
88
9- 1 . ** User prompt language** — 사용자가 특정 언어로 질문하면 해당 언어로 응답
10- 2 . ** ` user-preferences.yaml ` ** — ` .agents/config/user-preferences.yaml ` 의 ` language ` 필드
11- 3 . ** Fallback** — 위 둘 다 없으면 영어 (en)
9+ 1 . ** User prompt language** — if the user writes in a specific language, respond in that language
10+ 2 . ** ` user-preferences.yaml ` ** — ` language ` field in ` .agents/config/user-preferences.yaml `
11+ 3 . ** Fallback** — English (en) if neither of the above is set
1212
1313``` yaml
1414# .agents/config/user-preferences.yaml
@@ -19,44 +19,44 @@ language: ko # ko, en, ja, zh, ...
1919
2020| Category | Localize? | Example |
2121|----------|-----------|---------|
22- | 자연어 응답 / 설명 | Yes | "API 엔드포인트를 생성했습니다" |
23- | 에러 메시지 (사용자 대면 ) | Yes | "인증에 실패했습니다" |
24- | 상태 업데이트 / 진행 보고 | Yes | "Phase 2 완료, Phase 3 시작 " |
25- | Charter Preflight 출력 | Yes | 설명 텍스트는 로컬라이즈, 키워드는 영어 유지 |
26- | 결과 파일 (result-*.md) | Yes | 사용자가 읽는 텍스트 |
22+ | Natural language responses | Yes | User-facing explanations and descriptions |
23+ | Error messages (user-facing ) | Yes | Authentication failure messages |
24+ | Status updates / progress reports | Yes | "Phase 2 complete, starting Phase 3" |
25+ | Charter Preflight output | Yes | Descriptive text localized, keywords stay in English |
26+ | Result files (result-*.md) | Yes | User-readable text |
2727
2828## What Stays in English
2929
3030| Category | Why | Example |
3131|----------|-----|---------|
32- | 코드 (변수, 함수, 클래스 ) | 코드베이스 일관성 | ` getUserProfile()` |
33- | Git commit 메시지 | conventional commits 표준 | `feat : add user auth` |
34- | PR 제목/본문 | GitHub 협업 표준 | `fix : resolve race condition` |
35- | 기술 용어 / 도메인 용어 | 번역 시 의미 손실 | API, JWT, middleware, scaffold |
36- | 파일 경로 / 설정 키 | 시스템 식별자 | `.agents/config/` |
37- | 로그 레벨 / 상태 키워드 | 파싱 호환성 | `Status : completed`, `BLOCKED` |
38- | CLAUDE.md / SKILL.md 내부 | 시스템 프롬프트 | 영어 원본 유지 |
32+ | Code (variables, functions, classes ) | Codebase consistency | ` getUserProfile()` |
33+ | Git commit messages | Conventional commits standard | `feat : add user auth` |
34+ | PR titles/body | GitHub collaboration standard | `fix : resolve race condition` |
35+ | Technical / domain terms | Meaning loss when translated | API, JWT, middleware, scaffold |
36+ | File paths / config keys | System identifiers | `.agents/config/` |
37+ | Log levels / status keywords | Parsing compatibility | `Status : completed`, `BLOCKED` |
38+ | CLAUDE.md / SKILL.md content | System prompts | Keep English originals |
3939
4040# # Mixed-Language Rules
4141
42- 1. **기술 용어는 원어 유지 ** — 무리하게 번역하지 않는다
43- - Good : " JWT 토큰을 검증합니다 "
44- - Bad : " JSON 웹 토큰을 검증합니다 "
45- 2. **코드 블록 내부는 항상 영어 ** — 주석도 영어
46- 3. **인라인 코드 (`backtick`)는 번역하지 않음 **
47- 4. **괄호 보충 허용 ** — 낯선 용어는 `번역어(원어 )` 형식으로 한 번만 보충
48- 5. **존댓말 레벨 통일 ** — 한국어의 경우 해요체 기본, 문서는 합쇼체
42+ 1. **Keep technical terms in original language ** — don't force-translate
43+ - Good : " Validates the JWT token "
44+ - Bad : " Validates the JSON Web Token "
45+ 2. **Code blocks are always in English ** — including comments
46+ 3. **Inline code (`backtick`) is never translated **
47+ 4. **Parenthetical supplement allowed ** — for unfamiliar terms, use `translated(original )` format once
48+ 5. **Register consistency ** — match the target language's appropriate register for the context
4949
5050# # Workflow Integration
5151
52- 모든 워크플로우에서 이 규칙을 따른다. 기존 워크플로우의 아래 라인이 이 가이드를 참조하는 것과 동일하다 :
52+ All workflows follow these rules. The following line in existing workflows references this guide :
5353
5454` ` `
5555- **Response language follows ` language` setting in `.agents/config/user-preferences.yaml` if configured.**
5656```
5757
5858## Subagent Behavior
5959
60- - 서브에이전트의 ** 결과 파일 ** (` result-*.md ` )은 사용자 언어로 작성
61- - 서브에이전트 간 ** 내부 통신 ** (charter, status keywords)은 영어 유지
62- - 에이전트 정의 파일 (` .agents/agents/*.md ` )은 영어로 유지
60+ - Subagent ** result files ** (` result-*.md ` ) are written in the user's language
61+ - ** Internal communication ** between subagents (charter, status keywords) stays in English
62+ - Agent definition files (` .agents/agents/*.md ` ) stay in English
0 commit comments